# Report paid orders

> POST /api/v0/carts: report every paid order to Releva, with the field table, a working curl, responses, errors and limits.

`POST /api/v0/carts` reports paid orders. Releva records each order once, on the customer’s profile, and counts it in revenue, attribution and order-based segments.

## When to use it

Call it for every paid order, unless a Releva plugin or connector already does it for your platform. Without it, store revenue, attribution and order-based segmentation do not work. Send it from your server when the payment is confirmed.

Refunds and order statuses have their own calls: [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/) and [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/).

## Authentication

Send your shop’s **Secret Key** as a bearer token: `authorization: Bearer $RELEVA_SECRET_KEY`. Never use it in a browser or an app. Find it under **Settings › Shop & Integration** ([Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The error messages are in [Orders and refunds API: Authentication](https://releva.ai/documentation/reference/orders/overview/#authentication).

## Request

`POST https://releva.ai/api/v0/carts` with `content-type: application/json` and a body `{ "carts": [ ... ] }` that holds at least one cart. A cart is validated strictly: a key that is not in this table is rejected.

| Field                               | Type             | Required     | Notes                                                                                                                                                                                                                                                            |
| ----------------------------------- | ---------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderId`                           | string           | yes          | Your order id. Recorded once per shop; keep it under 255 characters.                                                                                                                                                                                             |
| `cartPaid`                          | boolean          | yes          | Send `true`. This endpoint reports paid orders: a cart sent with `false` records no order, no revenue and no event. Use the [JavaScript SDK](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/) for carts that have not been paid for.        |
| `products`                          | array of objects | yes          | The order lines; may be empty. See below.                                                                                                                                                                                                                        |
| `email`, `phoneNumber`, `profileId` | string           | at least one | Who placed the order. See [Identifying the shopper](https://releva.ai/documentation/reference/orders/report-paid-orders/#identifying-the-shopper). `phoneNumber` must start with `+` followed by digits, for example `+49875345976`.                                                                                                 |
| `timestamp`                         | string           | no           | When the order was paid. ISO-8601 with seconds and a zone (`Z`, `+0200` or `+02:00`). Default: now.                                                                                                                                                              |
| `companyId`                         | string           | no           | The B2B company.                                                                                                                                                                                                                                                 |
| `mergeProfileIds`                   | array of strings | no           | Ids of other profiles to merge into this shopper’s profile, typically the anonymous id a guest browsed under before checking out.                                                                                                                                |
| `acceptPrivacyPolicy`               | boolean          | no           | The shopper’s consent to your privacy policy. When `true`, the consent is recorded on the shopper’s profile.                                                                                                                                                     |
| `custom`                            | object           | no           | `string`, `numeric` and `date` lists of `{ key, values }`, for example the reward points gained for this order or the order’s city. Send `orderName` (the order number the customer sees, for example `#1001`) as a string field when it differs from `orderId`. |
| `ip`                                | string           | no           | The **shopper’s** IP address, forwarded from the storefront session, max 45 characters. Do not send your server’s IP address. See [Improving ad platform attribution](https://releva.ai/documentation/reference/orders/report-paid-orders/#improving-ad-platform-attribution).                                                       |
| `userAgent`                         | string           | no           | The **shopper’s** browser user agent, forwarded from the storefront session, max 1024 characters. Do not send your HTTP client’s user agent.                                                                                                                     |
| `url`                               | string           | no           | The storefront URL the order was completed on, max 2048 characters. Lets ad platforms record the purchase as a website conversion rather than an offline one.                                                                                                    |
| `address`                           | object           | no           | `city` and `region` (max 128 characters each), `postalCode` and `country` (max 32 each). Use codes, not names, for `region` and `country`. For ad-platform matching.                                                                                             |
| `eventId`                           | string           | no           | Max 200 characters. The id your browser pixel used for the same purchase, so Meta and TikTok de-duplicate it. Not stored.                                                                                                                                        |
| `group`                             | integer          | no           | 0 to 9999: the A/B test bucket of the browser the shopper bought in (the SDK’s `rlv_g` cookie). Send it only as the unchanged cookie value; otherwise leave it out.                                                                                              |

Each product:

| Field       | Type    | Required | Notes                                                                                                                                                                              |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `price`     | number  | yes      | The unit price at which the product was purchased. Revenue is `price` × `quantity`, summed over the lines.                                                                         |
| `quantity`  | integer | yes      | The units purchased.                                                                                                                                                               |
| `id`        | string  | no       | The same id you send to [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/), including the locale and market suffix if your catalog uses one. |
| `variantId` | string  | no       | The purchased variant, when `id` identifies the product rather than the variant. Recorded for variant-level reporting.                                                             |
| `currency`  | string  | no       | ISO-4217 code. Leave it out only when the price is already in your shop’s currency.                                                                                                |
| `custom`    | object  | no       | `string`, `numeric` and `date` lists of `{ key, values }`, for example the chosen size and color.                                                                                  |

Releva looks each line up in your catalog by `id` and copies the product’s name, categories and custom fields onto the order. That is what makes segments such as “bought in category X in the last 30 days” work. A line whose id matches nothing in the catalog still counts towards revenue, but carries no product attributes.

```plaintext
curl -X POST 'https://releva.ai/api/v0/carts' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "carts": [
      {
        "orderId": "DEMO-ORDER-1001",
        "cartPaid": true,
        "email": "maria@example.com",
        "phoneNumber": "+15555550199",
        "timestamp": "2026-03-27T14:05:00.000Z",
        "products": [
          {
            "id": "DEMO-1001",
            "variantId": "DEMO-1001-M",
            "price": 39.9,
            "currency": "EUR",
            "quantity": 1,
            "custom": {
              "string": [{ "key": "color", "values": ["white"] }],
              "numeric": [{ "key": "size", "values": [40] }]
            }
          },
          { "id": "DEMO-1002", "price": 19.2, "currency": "EUR", "quantity": 2 }
        ],
        "custom": {
          "string": [{ "key": "city", "values": ["Sofia"] }],
          "numeric": [{ "key": "rewardPoints", "values": [18] }]
        }
      }
    ]
  }'
```

### Identifying the shopper

Every cart needs at least one of `email`, `phoneNumber` or `profileId`: this is how the order is attached to a profile. Send as many of them as you have; Releva resolves them to a single profile.

* `email` and `phoneNumber`: the shopper’s contact details as they appear on the order. Send phone numbers in international format, `+` followed by digits.
* `profileId`: your own customer id, if you have one. Use it consistently across the Profile APIs and this one, and orders are attached to the right profile even for shoppers who change their email address.
* `mergeProfileIds`: on a guest checkout, pass the anonymous id the shopper browsed under, so their pre-purchase browsing history and campaign attribution follow them onto the identified profile.

### One order, one record

An `orderId` is recorded once per shop. If the same order reaches Releva twice (a webhook redelivery, a retry after a timeout, a backfill that overlaps live traffic), only the first one counts, so repeating a call never double-counts revenue. The flip side: a mistake cannot be corrected by sending the same `orderId` again; contact support if an order needs changing. A repeat can only add cart-level `custom` keys the stored order is missing, such as a late `orderName`. Use the order identifier your own systems use: support, refunds and order-level reports match on it.

### Improving ad platform attribution

Orders reported from your backend carry none of the browser context that ad platforms use to match a purchase to an ad click. Forward what you have, and the purchase events Releva sends to Meta, Google and TikTok get better match quality:

```plaintext
curl -X POST 'https://releva.ai/api/v0/carts' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "carts": [
      {
        "orderId": "DEMO-ORDER-1002",
        "cartPaid": true,
        "email": "maria@example.com",
        "timestamp": "2026-03-27T14:05:00.000Z",
        "ip": "203.0.113.24",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1",
        "url": "https://demo-store.example.com/checkout/thank-you",
        "address": { "city": "Sofia", "region": "23", "postalCode": "1000", "country": "BG" },
        "eventId": "b7f3c1e2-4a5d-4f0a-9c3e-1d2b3a4c5d6e",
        "products": [{ "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 }]
      }
    ]
  }'
```

Send the **shopper’s** values, not your server’s: `ip` and `userAgent` are the ones the shopper was browsing with (most platforms let you keep them on the cart or session during checkout), and `url` is the storefront page the order was completed on. Leave out any you cannot supply: no value is better than your data center’s IP address or your HTTP client’s user agent, which would be matched as if they were the customer’s.

## Response

`202 Accepted` with the body `{}`. The orders are live within about a minute. A `202` means the request was valid and queued, not that the order was recorded:

* Orders are held for about 30 seconds before they are recorded, so a browser report of the same order can add its session details.
* A repeated `orderId` answers `202` and is dropped. It adds only cart-level `custom` keys the stored order does not have yet; nothing else from it is recorded.
* A cart with no `email`, `phoneNumber` or `profileId` is dropped without an error when another cart in the request is valid.

## Errors

Errors have one shape, `{ "message": "..." }`. When several fields fail, the messages are joined with a space.

| Status | When                                                 | Message                                                                                                                                                                                                                                   |
| ------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Authentication failed                                | See [Orders and refunds API: Authentication](https://releva.ai/documentation/reference/orders/overview/#authentication)                                                                                                                                    |
| `400`  | Empty `carts`                                        | `The 'carts' field must contain at least 1 items.`                                                                                                                                                                                        |
| `400`  | Missing `orderId`                                    | `The 'carts[0].orderId' field is required.`                                                                                                                                                                                               |
| `400`  | Numeric `orderId`                                    | `The 'carts[0].orderId' field must be a string.`                                                                                                                                                                                          |
| `400`  | Missing `cartPaid`                                   | `The 'carts[0].cartPaid' field is required.`                                                                                                                                                                                              |
| `400`  | `cartPaid: "yes"`                                    | `The 'carts[0].cartPaid' field must be a boolean.`                                                                                                                                                                                        |
| `400`  | Missing `products`                                   | `The 'carts[0].products' field is required.`                                                                                                                                                                                              |
| `400`  | No `email`, `phoneNumber` or `profileId` on any cart | `For each cart, at least one of (email, phoneNumber, profileId) is required!`                                                                                                                                                             |
| `400`  | `email: "maria.example.com"`                         | `The 'carts[0].email' field must be a valid e-mail.`                                                                                                                                                                                      |
| `400`  | `timestamp: "2026-03-27"`                            | `carts[0].timestamp must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-03-27 instead.` |
| `400`  | Unknown key `total` on the cart                      | `The object 'carts[0]' contains forbidden keys: 'total'.`                                                                                                                                                                                 |
| `400`  | Unknown key `street` in `address`                    | `The object 'carts[0].address' contains forbidden keys: 'street'.`                                                                                                                                                                        |
| `400`  | `ip` longer than 45 characters                       | `The 'carts[0].ip' field length must be less than or equal to 45 characters long.`                                                                                                                                                        |
| `400`  | `currency: "EURO"`                                   | `carts[0].products[0].currency must be a valid ISO-4217 currency code! Got EURO instead.`                                                                                                                                                 |
| `400`  | `price: "39.90"` (a string)                          | `The 'carts[0].products[0].price' field must be a number.`                                                                                                                                                                                |
| `400`  | Missing `quantity`                                   | `The 'carts[0].products[0].quantity' field is required.`                                                                                                                                                                                  |
| `402`  | Your shop is disabled                                | `Domain is disabled. Please reach out to support@releva.ai to enable it.`                                                                                                                                                                 |
| `413`  | Body larger than 800 KB                              | `request entity too large`                                                                                                                                                                                                                |
| `500`  | Unexpected error; retry later                        | `An internal error occurred.`                                                                                                                                                                                                             |

A `null` cart in the array answers `500` instead of `400`. Do not send one.

## Limits

* Body size: 800 KB per request. Send backfills in batches.
* Rate limits: none.
* Processing: each order is recorded about 30 seconds after the call.

## Next steps

* [How orders and refunds work](https://releva.ai/documentation/learn/orders/how-orders-and-refunds-work/): Learn why one order id is recorded once and where orders show up.
* [See a customer’s orders](https://releva.ai/documentation/guides/orders/see-a-customers-orders/): Check in the admin that the orders you sent appear on the customer’s profile.
* [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/): Take refunded money back out of an order’s revenue.
* [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/): Tell Releva when an order ships, arrives or is cancelled.