Developers
Integration API
Your store sends each paid order to ProvedBuy. We schedule the invitation, send it to the customer after the delay you chose, and the published review carries the "verified order" label.
Get started in 4 steps
1
Create the key
In your account, Settings page, API block. The key is shown once: store it in an environment variable on your server, never in your code or in the browser.
2
Check the key
Call GET /api/v1/integration/ping. The response gives your store name, your plan and your sending delay.
3
Try test mode
Send a real order with "test": true. Nothing is created, the customer receives nothing, and you receive a preview of the invitation.
4
Go live
Remove "test": true. Each paid order is then scheduled and the invitation leaves on its own after the delay.
Authentication
Every call carries the X-Api-Key header with your key. The API is part of the Pro plan. Calls are made from your server: a key sent by the browser would be visible to everyone. If a key leaks, create a new one in your settings: the old one stops working at once.
- Base address
- https://provedbuy.com/api/v1/integration
- Message language
- Messages are in French by default. Add the X-Lang: en header to receive them in English.
Check the key
GEThttps://provedbuy.com/api/v1/integration/ping
Creates nothing and sends nothing. Call it at installation, or from an admin page of your store to show the connection status.
Code curl
curl https://provedbuy.com/api/v1/integration/ping \
-H "X-Api-Key: $PROVEDBUY_API_KEY"Response
{
"succeeded": true,
"messages": ["Valid API key"],
"data": {
"company": "Ma Boutique",
"slug": "ma-boutique.fr",
"plan": "Pro",
"invitationDelayDays": 7,
"sendingActive": true,
"remainingThisMonth": null
}
}| Field | Meaning |
|---|---|
| company | Your store name on ProvedBuy. |
| slug | Identifier of your public page and your badge. |
| plan | Your plan. |
| invitationDelayDays | Delay between receiving the order and sending the invitation, in days. |
| sendingActive | false until your email address is confirmed: invitations wait. |
| remainingThisMonth | Invitations still available this month, null when unlimited. |
Send orders
POSThttps://provedbuy.com/api/v1/integration/invitations
Call this address once the order is paid, not when it is created. An order cancelled before payment must not receive an invitation.
Request body (JSON)
| Field | Type | Meaning |
|---|---|---|
| items | array, required | From 1 to 500 orders per call. |
| items[].customerName | text | Customer first and last name, 80 characters at most. Used in the greeting. |
| items[].customerEmail | text, required | Address the invitation is sent to. |
| items[].orderReference | text, required | Your order number, 80 characters at most. The same order is never invited twice. |
| test | boolean | true for test mode. Missing or false: live sending. |
Response
| Field | Meaning |
|---|---|
| created | Orders scheduled (in test mode: those that would be). |
| skipped | Orders left out. |
| skippedReasons | The reason for each line left out, 20 at most. |
| test | true when the call was in test mode. |
| previewSentTo | In test mode, the address that received the preview. |
Test mode
Add "test": true to the request body. Orders go through the same checks as live, but no invitation is created, no email goes to the customer and your quota does not move.
- The response tells, line by line, what would be accepted or left out.
- A preview of the invitation goes to the address of your ProvedBuy account, with the name and order of the first accepted line.
- You can therefore test with real orders, with no risk for your customers.
Examples by language
Each example sends one order in test mode. Remove test to go live. The key is read from the PROVEDBUY_API_KEY environment variable.
Code curl
curl -X POST https://provedbuy.com/api/v1/integration/invitations \
-H "X-Api-Key: $PROVEDBUY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"test": true,
"items": [
{ "customerName": "Lea Martin", "customerEmail": "lea@example.com", "orderReference": "CMD-1001" }
]
}'WooCommerce, PrestaShop, Shopify
There is no extension to install yet. Here is where to hook the call in each tool.
WooCommerce
In the functions.php file of your child theme or in a small plugin. Triggered when the payment is confirmed. Define PROVEDBUY_API_KEY in wp-config.php.
Code WooCommerce
add_action('woocommerce_payment_complete', function ($order_id) {
$order = wc_get_order($order_id);
wp_remote_post('https://provedbuy.com/api/v1/integration/invitations', [
'timeout' => 10,
'headers' => [
'X-Api-Key' => PROVEDBUY_API_KEY,
'Content-Type' => 'application/json',
],
'body' => wp_json_encode([
'items' => [[
'customerName' => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
'customerEmail' => $order->get_billing_email(),
'orderReference' => $order->get_order_number(),
]],
]),
]);
});PrestaShop
In a module hooked on actionValidateOrder. Store the key in the module configuration.
Code PrestaShop
public function hookActionValidateOrder($params)
{
$order = $params['order'];
$customer = $params['customer'];
$payload = json_encode(['items' => [[
'customerName' => $customer->firstname . ' ' . $customer->lastname,
'customerEmail' => $customer->email,
'orderReference' => $order->reference,
]]]);
$ch = curl_init('https://provedbuy.com/api/v1/integration/invitations');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['X-Api-Key: ' . Configuration::get('PROVEDBUY_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $payload,
]);
curl_exec($ch);
curl_close($ch);
}Shopify
Create an "Order payment" webhook (orders/paid) that calls your server, then your server calls ProvedBuy. Example with Node.js and Express, to be completed with the Shopify signature check.
Code Shopify
app.post("/webhooks/shopify/orders-paid", express.raw({ type: "application/json" }), async (req, res) => {
res.sendStatus(200);
const order = JSON.parse(req.body);
await fetch("https://provedbuy.com/api/v1/integration/invitations", {
method: "POST",
headers: { "X-Api-Key": process.env.PROVEDBUY_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
items: [{
customerName: [order.customer?.first_name, order.customer?.last_name].filter(Boolean).join(" "),
customerEmail: order.email,
orderReference: order.name,
}],
}),
});
});Responses and errors
Every response has the same shape: succeeded, messages and data.
Test mode response
{
"succeeded": true,
"messages": ["Test mode: 1 invitation(s) would be scheduled, none was created"],
"data": {
"created": 1,
"skipped": 0,
"skippedReasons": [],
"test": true,
"previewSentTo": "vous@ma-boutique.fr"
}
}Key refused
{
"succeeded": false,
"messages": ["Invalid API key"],
"data": 0
}| HTTP status | Meaning |
|---|---|
| 200 | Call processed. Read succeeded: false means no order was accepted (empty list, more than 500 lines). |
| 401 | Key missing, invalid, replaced, or plan without API. |
| 413 | Body larger than 1 MB: split the submission. |
| 429 | More than 60 calls per minute: wait a minute, then send again. |
| 5xx | Incident on our side: send again later. An order already received is recognised and is not invited twice. |
Rules and limits
- An order is invited only once: sending the same number again creates no duplicate. You can therefore resend safely after a network error.
- Addresses on your own domain are never invited.
- The invitation leaves after your sending delay, adjustable from 0 to 30 days in your settings.
- Invitations only leave once your email address is confirmed.
- Call the API in the background: an outage on our side must never block your order.
- A review received by invitation carries the "verified order" label and can be neither deleted nor hidden by the store.
Ready to connect your store?
Create your key in your settings, then make a first call in test mode.