Orders
Push the orders of your store so Humind can measure what it brought in (which orders followed a conversation, which lines were added to the cart by the assistant) and, on PrestaShop, answer "where is my order?" in the chat for your customers. The Humind PrestaShop module does all of this for you; this page documents what it sends. Any other back office can push orders the same way for attribution; the chat's order tracking and the customer identity below are served for PrestaShop stores only (another platform keeps the custom order tracking API).
Both endpoints here are write-only and need the orders:write scope. There is no GET: you already have your orders, and the results show up on your side in the dashboard (attribution) and in the chat (order tracking).
On PrestaShop
Install the Humind module and connect it: it pushes every validated order and every status change by itself, and serves the customer identity endpoint of the widget. Nothing to write.
How attribution works
The chat widget leaves markers on the storefront while the visitor talks to the assistant:
- on Shopify, as cart attributes and line item properties, read by our webhooks;
- on PrestaShop and any other platform, in a first-party cookie named
humind_attribution, a JSON object{ "v": "<visitor id>", "t": "<thread id>", "p": ["<product>_<variant>", ...] }(30 days,SameSite=Lax, path/).vandtidentify the conversation;plists the cart lines the assistant added, as<id_product>_<id_product_attribute>on PrestaShop.
When an order is validated, copy the cookie onto the order you push: v and t become the _humind_visitor and _humind_thread order attributes, and every line whose key is in p gets the line property _humind_source: "humind". Humind then decides the verdict exactly as it does for Shopify:
attribution.level | Meaning |
|---|---|
direct | At least one line was added to the cart by the assistant. |
recommended | No line came from the assistant, but the conversation showed or cited a product of the order. |
cart | The visitor had a conversation, and nothing in the order came from it. |
null | No Humind marker on the order. |
The verdict is returned on every push and visible in the dashboard. The cookie values come from the browser, so treat them as declarative: they are pseudonymous Humind ids, never customer data.
Push an order
POST /orders records an order, or updates it when the same external_id was pushed before. The call is idempotent by external_id: a retry after a network error is harmless, and no Idempotency-Key header is needed. On an order already known, a status or tracking field left empty keeps its stored value, so a replayed push never erases a status set by PATCH, and a new status always replaces status_label.
Required scope: orders:write
| Field | Required | Type | Notes |
|---|---|---|---|
external_id | yes | string or integer, up to 128 | The order id on your platform (id_order on PrestaShop). The key of the upsert. |
name | no | string, up to 64 | The order number as the customer knows it (reference on PrestaShop). Used by the chat to find an order by its number. |
created_at | yes | ISO 8601 | Order date. |
cancelled_at | no | ISO 8601 | Set when the order is cancelled. Cancelled orders stay recorded and count for nothing. |
currency | no | ISO 4217 | EUR, USD... |
total_price | yes | number | Total paid, after discounts, in major units. |
subtotal_price | no | number | Before shipping and taxes, in major units. |
test | no | boolean | Test orders are recorded and excluded from every figure. |
channel | no | string, up to 64 | Sales channel (web, pos...). |
customer.external_id | no | string or integer, up to 128 | The customer id on your platform (id_customer). Needed for the signed-in order lookup, see Customer identity. |
customer.email | no | The purchase email. Stored as a keyed hash only, for the order number + email lookup of the chat. Never stored in clear. | |
status | no | string, up to 64 | Fulfillment status. Use a known key when you can map to one: unfulfilled, partially_fulfilled, fulfilled, delivered, ready_for_pickup, picked_up, voided; the chat translates them. Otherwise send your own key and a status_label. |
status_label | no | string, up to 128 | The status as your back office labels it, shown to the customer when status is not a known key. |
tracking_number | no | string, up to 128 | Parcel tracking number. |
tracking_url | no | URL, up to 2048 | Carrier tracking page. |
attributes | no | object or [{ name, value }] list | Order-level key/values. Put _humind_visitor and _humind_thread here, from the cookie. |
line_items | yes | array, up to 500 | See below. |
Each line item:
| Field | Required | Type | Notes |
|---|---|---|---|
external_product_id | no | string or integer | The product id, as sent in the catalog sync (id_product). Lets Humind match the line with the catalog and tell whether the conversation recommended it. |
external_variant_id | no | string or integer | The variant id, identical to the catalog sync (product-<id> or combination-<id> on PrestaShop). |
quantity | yes | integer | |
price | no | number | Unit price in the order currency, major units. |
title | no | string | Product title, shown on the order card in the chat. Trimmed to 255 characters. |
variant_title | no | string | Trimmed to 255 characters. |
sku | no | string, up to 128 | Merchant reference of the line. Accepted, not stored today. |
properties | no | object or [{ name, value }] list | Line key/values. Put _humind_source: "humind" here when the line key is in the cookie's p. |
Unknown fields are rejected with validation_failed, so a typo in a marker key never passes silently. An empty string in an optional text field (status_label, customer.email, tracking_number...) is read as "no value", never as an error.
Request
curl -X POST https://api.thehumind.com/public/v1/orders \
-H "Authorization: Bearer hmd_live_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": 1042,
"name": "XKBKNABJK",
"created_at": "2026-11-03T08:15:00Z",
"currency": "EUR",
"total_price": 89.9,
"subtotal_price": 84.9,
"customer": { "external_id": 7, "email": "jane@example.com" },
"status": "unfulfilled",
"status_label": "Payment accepted",
"attributes": { "_humind_visitor": "v_8f3a", "_humind_thread": "68a1c2d3e4f5a6b7c8d9e0f1" },
"line_items": [
{ "external_product_id": 11, "external_variant_id": "combination-111", "quantity": 1, "price": 49.9, "title": "CBD oil", "variant_title": "10%" },
{ "external_product_id": 22, "external_variant_id": "product-22", "quantity": 2, "price": 20, "title": "Balm", "properties": { "_humind_source": "humind" } }
]
}'Response 201 Created (first push) or 200 OK (already known)
{
"data": {
"id": "68a1c2d3e4f5a6b7c8d9e0f9",
"external_id": "1042",
"name": "XKBKNABJK",
"platform": "prestashop",
"store_id": "www.example.com",
"created_at": "2026-11-03T08:15:00.000Z",
"cancelled_at": null,
"test": false,
"currency": "EUR",
"total_price": 89.9,
"attribution": {
"level": "direct",
"sources": ["humind"],
"visitor_id": "v_8f3a",
"thread_id": "68a1c2d3e4f5a6b7c8d9e0f1"
},
"status": "unfulfilled",
"status_label": "Payment accepted",
"tracking_number": null,
"tracking_url": null,
"ingested_via": "api",
"updated_at": "2026-11-03T08:15:02.000Z"
}
}platform is prestashop when your catalog integration is PrestaShop and custom otherwise. store_id is the host of your storefront: the storefront hostname of your company, else the primary one of your allowed domains, else the first one; together with external_id it makes the order unique across your stores.
Update an order's status
PATCH /orders/api:{external_id} updates the fulfillment of an order already pushed: status, label, parcel tracking, cancellation. Last write wins, a field left out keeps its value, a new status without status_label clears the former label, and cancelled_at is never reset once set. The order must have been pushed first, otherwise the call answers 404 not_found.
Required scope: orders:write
| Field | Type | Notes |
|---|---|---|
status | string, up to 64 | Same keys as on the push. |
status_label | string, up to 128 | |
tracking_number | string, up to 128 | |
tracking_url | URL, up to 2048 | |
cancelled_at | ISO 8601 |
At least one field is required.
Request
curl -X PATCH https://api.thehumind.com/public/v1/orders/api:1042 \
-H "Authorization: Bearer hmd_live_..." \
-H "Content-Type: application/json" \
-d '{ "status": "fulfilled", "status_label": "Shipped", "tracking_number": "6A12345678901", "tracking_url": "https://www.laposte.fr/outils/suivre-vos-envois?code=6A12345678901" }'The response is the same object as on the push, with the updated fields.
Customer identity
Once your orders are pushed, the chat can show a signed-in customer their own orders without asking for an order number and an email. That needs a proof that the visitor is signed in as a given customer, and only your server can give it: the widget never trusts a customer id read from the page. PrestaShop stores only, through the Humind module.
The flow:
- The widget, on a storefront whose integration is PrestaShop, calls the module's identity controller (
index.php?fc=module&module=humind&controller=identityunder the shop's base URL) when the chat opens, with the store session cookie. - The module checks the PrestaShop session. If nobody is signed in, it answers
204 No Content. Otherwise it callsPOST /customer-identity/tokenswith your API key and the customer id, and returns the token to the browser as{ "token": "...", "expiresIn": 1800 }(the API answersexpires_in, the module renames it). - The widget sends the token with each message. The assistant lists the customer's recent orders (the ones you pushed, with their current status) and can narrow to one by its number.
POST /customer-identity/tokens is server-to-server only. A key holding customers:identity must never reach the browser: anyone with it could impersonate any customer of your store in the chat.
Required scope: customers:identity
| Field | Required | Type | Notes |
|---|---|---|---|
customer_external_id | yes | string or integer, up to 64 | The customer id on your platform, the one you send in customer.external_id of the orders. |
email | no | Accepted for forward compatibility, not used today. |
Request
curl -X POST https://api.thehumind.com/public/v1/customer-identity/tokens \
-H "Authorization: Bearer hmd_live_..." \
-H "Content-Type: application/json" \
-d '{ "customer_external_id": 7 }'Response 200 OK
{ "token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 1800 }The token lives 30 minutes and names your store and the customer, nothing else. It is a bearer credential readable by any script on the storefront, like the customer's own account pages: never log it and never persist it. The widget asks for a new one when it expires. This call is charged to the reads rate-limit bucket, so a busy storefront is never throttled on it by its order pushes.
What the chat shows
The order card shows the order number, the status (translated when it is a known key, your label otherwise), the tracking link, the items and a timeline (order placed, then shipped or delivered when the status says so, voided when cancelled). It never shows an address or an email, because the pushed order carries none.
Errors
| Status | Code | When |
|---|---|---|
400 | validation_failed | A field is missing, malformed, unknown, or the PATCH body is empty. error.details.issues lists the fields. |
403 | insufficient_scope | The key lacks orders:write or customers:identity. |
404 | not_found | PATCH on an order never pushed for this store. |
429 | rate_limited | See Rate limits. Order pushes use the writes bucket, identity tokens the reads bucket. |
See Errors for the envelope and the shared codes.