provedbuy

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. 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. 2

    Check the key

    Call GET /api/v1/integration/ping. The response gives your store name, your plan and your sending delay.

  3. 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. 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
  }
}
FieldMeaning
companyYour store name on ProvedBuy.
slugIdentifier of your public page and your badge.
planYour plan.
invitationDelayDaysDelay between receiving the order and sending the invitation, in days.
sendingActivefalse until your email address is confirmed: invitations wait.
remainingThisMonthInvitations 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)

FieldTypeMeaning
itemsarray, requiredFrom 1 to 500 orders per call.
items[].customerNametextCustomer first and last name, 80 characters at most. Used in the greeting.
items[].customerEmailtext, requiredAddress the invitation is sent to.
items[].orderReferencetext, requiredYour order number, 80 characters at most. The same order is never invited twice.
testbooleantrue for test mode. Missing or false: live sending.

Response

FieldMeaning
createdOrders scheduled (in test mode: those that would be).
skippedOrders left out.
skippedReasonsThe reason for each line left out, 20 at most.
testtrue when the call was in test mode.
previewSentToIn 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 statusMeaning
200Call processed. Read succeeded: false means no order was accepted (empty list, more than 500 lines).
401Key missing, invalid, replaced, or plan without API.
413Body larger than 1 MB: split the submission.
429More than 60 calls per minute: wait a minute, then send again.
5xxIncident 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.