Orders Guide
In 2026-04, bulk order writes keep per-item outcomes if a connection becomes unavailable during the request. Failed items appear in results[].error; if none succeeds, the response is 422 validation_error with results in error.details. Accepted items remain stored. Check the connection and those outcomes before retrying.
Orders tell Revi which customers can receive review invitations and which products were part of each purchase.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/2026-04/orders | List synchronized orders. |
POST | /api/2026-04/orders | Create or update orders in bulk. |
GET | /api/2026-04/orders/{id_order} | Read one order by external order ID. |
PATCH | /api/2026-04/orders/{id_order}/status | Update an order status. |
POST | /api/2026-04/orders/{id_order}/products | Attach products to an order. |
Recommended Flow
- Create or update products with
POST /api/2026-04/products. - Create or update orders with
POST /api/2026-04/orders. - Attach products with
POST /api/2026-04/orders/{id_order}/products. - Keep order status current with
PATCH /api/2026-04/orders/{id_order}/status.
Status Values
| Status | Meaning |
|---|---|
pending | Store the order, but do not send the review email yet. |
ready | The order is ready for the review invitation workflow. |
cancelled | Do not send a review email for this order. |
The API also accepts numeric status values 0, 1, and 2 when creating orders, but public integrations should prefer the string values above.
Create Or Update Orders
id_order is required and must be 36 characters or fewer. Other fields are optional, but sending customer, amount, language, and date fields keeps review workflows and reporting useful.
Send the complete language code in lang. For example, pt-BR and zh-Hant are distinct from pt and zh. Revi normalizes pt_BR to pt-BR and zh_TW to zh-Hant when those codes are available. If an exact regional or script code is unavailable, Revi may resolve it to an available base-language code; if no candidate is available, the order uses the business default language.
Supported input fields are id_order, customer_name, customer_lastname, email, lang, iso_country, currency, shipping_cost, total_discount, taxes, vat, total_products, total_paid, status, order_date, date_status_upd, and timezone. Store scope comes from the API key; id_store is returned by read endpoints but is not accepted in order creation payloads.
curl "https://api.revi.io/api/2026-04/orders" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-API-KEY: revi_test_xxxxxxxxx" \
-d '{
"orders": [
{
"id_order": "100045",
"lang": "en",
"customer_name": "Jane",
"customer_lastname": "Doe",
"email": "jane@example.com",
"currency": "EUR",
"shipping_cost": "6.00",
"total_discount": "0.00",
"taxes": "10.50",
"vat": "21",
"total_products": "50.00",
"total_paid": "66.50",
"status": "ready",
"order_date": "2026-05-09 10:30:00"
}
]
}'Batch responses include one result per order:
{
"success": true,
"data": {
"orders_count": 1,
"results": [
{
"id_order": "100045",
"success": true
}
]
},
"meta": {
"api_version": "2026-04"
}
}If all rows fail validation or processing, the API returns 422 with the per-row results inside error.details.
Attach Products
Attach products after the order exists. Each product requires id_product; variants can include id_combination.
{
"products": [
{
"id_product": "sku-123",
"id_combination": "sku-123-red-42",
"price": "29.90",
"sku": "RUN-RED-42"
}
]
}Successful response:
{
"success": true,
"data": {
"id_order": "100045",
"products_attached": 1
},
"meta": {
"api_version": "2026-04"
}
}Update Status
{
"status": "ready",
"date_status_upd": "2026-05-09 11:00:00"
}If date_status_upd is omitted, Revi records the current server time.
Read One Order
GET /api/2026-04/orders/{id_order} returns the order identity, customer fields, language, currency, total_paid, status dates, review state, and attached product summaries. Attached products include id_product, avg_rating, and num_reviews.
List Orders
Supported filters:
| Filter | Description |
|---|---|
page | Page number, starting at 1. |
per_page | Page size, from 1 to 100. Default is 25. |
status | pending, ready, or cancelled. |
from_date | Orders with order_date on or after the date. |
to_date | Orders with order_date on or before the date. |
email | Exact customer email match. |
List responses include meta.pagination.