Skip to content

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 /). v and t identify the conversation; p lists 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.levelMeaning
directAt least one line was added to the cart by the assistant.
recommendedNo line came from the assistant, but the conversation showed or cited a product of the order.
cartThe visitor had a conversation, and nothing in the order came from it.
nullNo 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

FieldRequiredTypeNotes
external_idyesstring or integer, up to 128The order id on your platform (id_order on PrestaShop). The key of the upsert.
namenostring, up to 64The order number as the customer knows it (reference on PrestaShop). Used by the chat to find an order by its number.
created_atyesISO 8601Order date.
cancelled_atnoISO 8601Set when the order is cancelled. Cancelled orders stay recorded and count for nothing.
currencynoISO 4217EUR, USD...
total_priceyesnumberTotal paid, after discounts, in major units.
subtotal_pricenonumberBefore shipping and taxes, in major units.
testnobooleanTest orders are recorded and excluded from every figure.
channelnostring, up to 64Sales channel (web, pos...).
customer.external_idnostring or integer, up to 128The customer id on your platform (id_customer). Needed for the signed-in order lookup, see Customer identity.
customer.emailnoemailThe purchase email. Stored as a keyed hash only, for the order number + email lookup of the chat. Never stored in clear.
statusnostring, up to 64Fulfillment 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_labelnostring, up to 128The status as your back office labels it, shown to the customer when status is not a known key.
tracking_numbernostring, up to 128Parcel tracking number.
tracking_urlnoURL, up to 2048Carrier tracking page.
attributesnoobject or [{ name, value }] listOrder-level key/values. Put _humind_visitor and _humind_thread here, from the cookie.
line_itemsyesarray, up to 500See below.

Each line item:

FieldRequiredTypeNotes
external_product_idnostring or integerThe 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_idnostring or integerThe variant id, identical to the catalog sync (product-<id> or combination-<id> on PrestaShop).
quantityyesinteger
pricenonumberUnit price in the order currency, major units.
titlenostringProduct title, shown on the order card in the chat. Trimmed to 255 characters.
variant_titlenostringTrimmed to 255 characters.
skunostring, up to 128Merchant reference of the line. Accepted, not stored today.
propertiesnoobject or [{ name, value }] listLine 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 ​

bash
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) ​

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

FieldTypeNotes
statusstring, up to 64Same keys as on the push.
status_labelstring, up to 128
tracking_numberstring, up to 128
tracking_urlURL, up to 2048
cancelled_atISO 8601

At least one field is required.

Request ​

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

  1. The widget, on a storefront whose integration is PrestaShop, calls the module's identity controller (index.php?fc=module&module=humind&controller=identity under the shop's base URL) when the chat opens, with the store session cookie.
  2. The module checks the PrestaShop session. If nobody is signed in, it answers 204 No Content. Otherwise it calls POST /customer-identity/tokens with your API key and the customer id, and returns the token to the browser as { "token": "...", "expiresIn": 1800 } (the API answers expires_in, the module renames it).
  3. 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

FieldRequiredTypeNotes
customer_external_idyesstring or integer, up to 64The customer id on your platform, the one you send in customer.external_id of the orders.
emailnoemailAccepted for forward compatibility, not used today.

Request ​

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

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

StatusCodeWhen
400validation_failedA field is missing, malformed, unknown, or the PATCH body is empty. error.details.issues lists the fields.
403insufficient_scopeThe key lacks orders:write or customers:identity.
404not_foundPATCH on an order never pushed for this store.
429rate_limitedSee Rate limits. Order pushes use the writes bucket, identity tokens the reads bucket.

See Errors for the envelope and the shared codes.

Released under the proprietary Humind license.