Skip to content

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 ​

MethodPathPurpose
GET/api/2026-04/ordersList synchronized orders.
POST/api/2026-04/ordersCreate 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}/statusUpdate an order status.
POST/api/2026-04/orders/{id_order}/productsAttach products to an order.
  1. Create or update products with POST /api/2026-04/products.
  2. Create or update orders with POST /api/2026-04/orders.
  3. Attach products with POST /api/2026-04/orders/{id_order}/products.
  4. Keep order status current with PATCH /api/2026-04/orders/{id_order}/status.

Status Values ​

StatusMeaning
pendingStore the order, but do not send the review email yet.
readyThe order is ready for the review invitation workflow.
cancelledDo 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.

bash
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:

json
{
  "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.

json
{
  "products": [
    {
      "id_product": "sku-123",
      "id_combination": "sku-123-red-42",
      "price": "29.90",
      "sku": "RUN-RED-42"
    }
  ]
}

Successful response:

json
{
  "success": true,
  "data": {
    "id_order": "100045",
    "products_attached": 1
  },
  "meta": {
    "api_version": "2026-04"
  }
}

Update Status ​

json
{
  "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:

FilterDescription
pagePage number, starting at 1.
per_pagePage size, from 1 to 100. Default is 25.
statuspending, ready, or cancelled.
from_dateOrders with order_date on or after the date.
to_dateOrders with order_date on or before the date.
emailExact customer email match.

List responses include meta.pagination.

Public API documentation for Revi.