Flow-e Connect
Orders, returns and customer profile
Connect the store's orders API: order status in the chat, returns and exchanges, logged-in customer profile.
Introduction
Overview: what the customer sees in the chat#
| Feature | Behaviour in the chat | Requirement |
|---|---|---|
| Order status, guest | When the customer asks about an order ("where is my order?"), the assistant requests the order number and email and presents the order card: status, date, amounts, items, carrier with tracking number and link, link to the order page on the site. | search lookup (order number + email) |
| Order status, logged-in customer | When the customer asks for "my orders", the assistant presents the latest orders (up to 5 in a list, or the order in progress) without requesting a number or email. | by_customer lookup (customer code) and customer signature |
| Returns and exchanges | From the order card the customer opens the return panel, which lists only items that can still be returned, and selects a reason and a solution (refund, exchange for another variant, replacement, repair), attaching photos where required. The request is recorded as a ticket in the store's Flow-e portal and, if configured, sent to the store's system with the return.requested event. | the same data as order status, including lines; rules defined by the store in the portal |
| Customer profile | For logged-in customers Flow-e derives a summary from the latest orders (most purchased categories and brands, average spend, purchases on promotion, sizes per category), used for more relevant suggestions. | by_customer lookup and customer signature |
If the store's system does not respond, the assistant reports a technical problem and provides no unverified data; if errors recur, Flow-e briefly suspends calls to the store's API (protection of the API). A non-existent order and an incorrect email receive the same response: the response does not disclose whether an order number exists, and guest attempts are limited (limit on attempts).
Possible paths#
Path A — existing orders API, in any format#
The API requires no changes: the conversion to the Flow-e format is performed by the adapter. The connection requires:
- The API documentation (link or PDF) and the test environment address, where available.
- A read-only key dedicated to Flow-e and limited to orders, transmitted over a secure channel (not by plain-text email). The key is stored exclusively in the Flow-e credential store.
- Two test orders with their associated emails, preferably of test customers, one shipped and one delivered, and a test customer code with at least two orders.
- The list of order statuses of the system, with the meaning of each.
- The optional fields available: variant options (size, colour), line category and brand, quantity still returnable, shipping and delivery dates.
- Authorisation of the Flow-e IP address, if the API is restricted by address.
Example of field correspondence (hypothetical API, for illustration only):
| Store API field | Flow-e field |
|---|---|
orderNumber | order_ref |
createdAt | placed_at |
state: "SENT" | status: "shipped" |
buyer.email · buyer.id | email · customer_ref |
lines[].qtyOrdered | items[].qty |
Path B — no orders API: recommended format "Flow-e Orders API v1"#
For a new endpoint the recommended format is Flow-e Orders API v1 (API reference): request and response match the format used by Flow-e and require no conversion. The endpoint is read-only and provides two lookups. Alternatively, reading from another system that already holds the orders (ERP, back office) can be agreed.
Order submission and the assistant
Submitting orders with POST /api/connect/v1/orders (see the OpenAPI reference) is used exclusively to attribute visits to sales: it does not feed order status, returns or the profile.
Path C — reference to the "My orders" page#
No order data passes through Flow-e. For requests about orders or returns, the assistant answers with the instructions and links entered by the store in its knowledge base (for example the "My orders" page and the returns page).
Minimum endpoint requirements#
The requirements apply to any format (path A or B).
| Topic | Requirement |
|---|---|
| Two lookups | by order number (guests): the order with that number, including the customer's email. By customer code (logged-in customers): the customer's orders, up to 25, preferably newest first, each including the customer code |
| Email and customer code | used exclusively for the ownership check and removed immediately afterwards: neither shown in the chat nor stored |
| Protocol | https:// only, with a valid certificate |
| Authentication | key in an HTTP header (Authorization: Bearer … or X-Api-Key: …), never in the URL |
| Response time | within 4 seconds; beyond that limit the call is considered failed |
| Response size | body up to 1 MB; a larger response is considered failed |
X-Request-Id header | present in every Flow-e call: unique identifier of the call, to be recorded in the store's logs to correlate calls |
| Permissions | read-only, limited to orders |
| Order not found | 200 with an empty list, or 404 |
| Errors | 401/403, 429, 5xx, non-JSON body: "system unavailable" |
| Formats | UTF-8 JSON; ISO 8601 dates with time zone (2026-11-02T10:15:00Z); amounts as numbers or strings with a decimal point |
| Identifiers | any string (e.g. C-00A93F), compared by exact equality and never reduced to digits; up to 128 characters; the order number follows the request rules |
| Volume | one call per customer request; for the profile at most one call per hour per logged-in customer; subject to the protection of the API |
Excluded data
Addresses, phone numbers, payment data and internal notes are not requested. If the API returns them, the adapter discards them: they are neither copied nor stored.
Flow-e Orders API v1 — recommended format for a new endpoint.
Request#
A single URL, POST method, JSON body, key in a header. Two operations:
| Field | Type | When | Meaning |
|---|---|---|---|
operation | "search" | "by_customer" | always | guest lookup or logged-in customer lookup |
order_ref | string ≤ 64 | search | order number as shown to the customer, without # |
email | string ≤ 254 | search | email provided by the customer, compared by Flow-e with the order's email |
customer_ref | string ≤ 128 | by_customer | customer code, identical to the one in the signature |
limit | integer 1-25 | by_customer | maximum number of orders, newest first |
Headers of every call: Content-Type: application/json, the read-only key and X-Request-Id (unique identifier of the call, to be recorded in the store's logs).
Order number#
Guest lookup is guaranteed on every channel for order numbers that comply with the following rules. The widget's returns panel applies them to the number entered by the customer; the chat accepts up to 64 characters without spaces.
| Rule | Detail |
|---|---|
| Length | 1 to 64 characters |
| Allowed characters | ASCII letters (A-Z, a-z), digits (0-9) and the symbols - _ . / |
| First character | a letter, a digit or - |
| Excluded sequences | .. and // |
Leading # | removed before the call: #SP-1001 becomes SP-1001 |
Response fields#
Root: { "orders": [ … ] }, at most 25 orders. Identifiers are always strings (a numeric value is converted). Unexpected fields are ignored.
| Field | Type | Required | Usage |
|---|---|---|---|
order_ref | string ≤ 64 | yes | order number shown to the customer: lookup and card |
order_id | string ≤ 128 | null | no | internal identifier; reference in returns |
placed_at | string ISO 8601 | yes | card, sorting, profile |
status | enum (9 values) | yes | card |
status_label | string | null | no | label in the store's language, shown when the status is unknown |
closed | boolean | recommended | true = no longer returnable (cancelled, payment voided, refunded) |
currency | string ISO 4217 | yes | card, profile |
totals.total | number | yes | card, profile |
totals.subtotal · shipping · discount · tax | number | null | no | card; discount feeds the profile (purchases on promotion) |
email | string | yes | guest check |
customer_ref | string ≤ 128 | yes for logged-in customers | logged-in check |
order_page_url | https | null | no | button on the card |
shipments[] | array ≤ 10 | recommended | card; the return window starts at delivery (or shipping + 7 days) |
shipments[].carrier · tracking_number · tracking_url | string | null | no | carrier and tracking |
shipments[].shipped_at · eta · delivered_at | string ISO 8601 | null | recommended | shipped, estimated delivery, delivered |
items[] | array ≤ 50 | yes | order lines |
items[].line_ref | string ≤ 128 | recommended (yes for returns) | identifies the item to return |
items[].sku · product_ref | string | null | recommended | identical to those in the Flow-e catalog: images, exchanges for other variants, return exclusions |
items[].name | string | yes | card |
items[].variant | string | null | no | variant label (M · Blue) |
items[].options[] | [{ name, value }] ≤ 10 | no | variant options (Size: M): profile, sizes per category |
items[].qty | number | yes | ordered quantity |
items[].qty_returnable | number | null | recommended | quantity still returnable (if absent, qty applies) |
items[].unit_price_paid · unit_price_list | number | null | no | card, sale items in returns |
items[].image_url | https | null | no | card |
items[].brand · category | string | null | no | profile; return exclusions by brand or category |
items[].tags[] | string[] ≤ 20 | no | return exclusions by tag |
Limits applied to the response#
The body is accepted up to 1 MB; beyond that, the response is considered failed. Within that limit the following rules apply and the response remains valid.
| Element | Limit | Beyond the limit |
|---|---|---|
| Orders | 25 | excess orders are ignored |
Lines per order (items[]) | 50 | excess lines are ignored |
Shipments per order (shipments[]) | 10 | excess shipments are ignored |
Options per line (items[].options[]) | 10 | excess options are ignored |
Tags per line (items[].tags[]) | 20 | excess tags are ignored |
items[].name, items[].brand, items[].category | 200 characters | text truncated |
items[].variant, name and value of items[].options[], items[].tags[] | 120 characters | text truncated |
| Other texts | 500 characters | text truncated |
order_ref | 64 characters | the whole order is discarded |
Other identifiers (order_id, customer_ref, line_ref, sku, product_ref) | 128 characters | value ignored, never truncated |
email | 254 characters | value ignored |
URLs (order_page_url, tracking_url, image_url) | https:// only, up to 2000 characters, without spaces, quotes or angle brackets | value ignored |
An identifier is never truncated: a truncated value could match that of another order or another customer. An object or an array in place of a text value is ignored.
Order statuses#
In path A each status of the store's system is mapped to one of the following nine values. A value outside the list becomes unknown and the card shows status_label.
status | Meaning |
|---|---|
pending_payment | awaiting payment |
processing | paid, being prepared |
shipped | shipped |
partially_shipped | partially shipped |
delivered | delivered |
cancelled | cancelled |
refunded | refunded |
returned | returned |
unknown | not recognised (status_label is shown) |
Examples#
Request#
# search — guest (order number + email)
curl -X POST https://api.store.example/flowe/orders \
-H "X-Api-Key: <read-only key>" \
-H "Content-Type: application/json" \
-H "X-Request-Id: 348112" \
-d '{"operation":"search","order_ref":"SP-1001","email":"mario.rossi@connect.test"}'# by_customer — logged-in customer, up to 25 orders
curl -X POST https://api.store.example/flowe/orders \
-H "X-Api-Key: <read-only key>" \
-H "Content-Type: application/json" \
-H "X-Request-Id: 348113" \
-d '{"operation":"by_customer","customer_ref":"C-0093","limit":25}'Response (sample data)#
{
"orders": [{
"order_ref": "SP-1001",
"order_id": "9001",
"placed_at": "2026-11-02T10:15:00Z",
"status": "shipped",
"status_label": "Shipped",
"closed": false,
"currency": "EUR",
"totals": { "total": 177.9, "subtotal": 171, "shipping": 6.9, "discount": 0, "tax": null },
"email": "mario.rossi@connect.test",
"customer_ref": "C-0093",
"order_page_url": "https://shop.example.com/account/orders/SP-1001",
"shipments": [{
"carrier": "BRT",
"tracking_number": "BRT000123456",
"tracking_url": "https://www.brt.it/it/tracking",
"shipped_at": "2026-11-03T08:00:00Z",
"eta": "2026-11-06T00:00:00Z",
"delivered_at": null
}],
"items": [{
"line_ref": "1",
"sku": "MG-JACKET-M-BLU",
"product_ref": "MG-JACKET",
"name": "Softshell jacket",
"variant": "M · Blue",
"options": [{ "name": "Size", "value": "M" }, { "name": "Colour", "value": "Blue" }],
"qty": 1,
"qty_returnable": 1,
"unit_price_paid": 119.9,
"unit_price_list": 129.9,
"image_url": "https://shop.example.com/media/mg-jacket.jpg",
"brand": "Montagna",
"category": "Jackets",
"tags": ["outdoor"]
}]
}]
}Order not found#
HTTP/1.1 200 OK
Content-Type: application/json
{ "orders": [] }Alternatively 404. The response is identical for a non-existent number and for an incorrect email.
IP address to authorise#
Calls to the store's API originate from a single Flow-e server with a fixed IP address. If the API is protected by a firewall or an IP allow-list, the following IP address must be authorised: 72.60.81.115 (IPv4). Any change of address is communicated in writing before it takes effect.
Where bot protection is in place (WAF, Cloudflare, Fastly), the API address must be excluded from the challenge.
Logged-in customers: customer code in the signature and in the orders#
To recognise a logged-in customer, the store page passes the customer code, signed by the store's server, to the Flow-e script. The snippet for sites on their own platform is available in the Flow-e portal under Integrations › Install the widget (embed-v2.js); for a logged-in customer the identity attributes are added:
<script src="https://<widget>/embed-v2.js"
data-widget-url="https://<widget>"
data-api-key="pk_live_…"
data-user-id="C-0093"
data-user-ts="1763116800"
data-user-hmac="<signature>"
data-logged-in="true" defer></script>The signature is computed on the server, never in the browser:
signature = HMAC-SHA256( secret, "<customer_ref>:<ts>" ) // lowercase hex
ts = Unix seconds when the page is generated<?php
// Server side: the secret never reaches the browser
$ts = (string) time();
$signature = hash_hmac('sha256', $customerRef . ':' . $ts, $secret);// Node.js, server side
import { createHmac } from "node:crypto";
const ts = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", secret).update(`${customerRef}:${ts}`).digest("hex");| Rule | Detail |
|---|---|
| Secret | the organization's Identity Secret Key, in the Flow-e portal under Integrations › API keys. It remains on the server: never in the page or in JavaScript code |
| Validity | 24 hours from ts; a ts more than 5 minutes ahead of the current time is rejected |
data-user-id | identical to the value the store's API returns as customer_ref, character for character (1-128 characters, no spaces or control characters) |
| Customer not logged in | only data-logged-in="false", with no other identity attribute |
Customer code consistency
If the signature uses the internal numeric identifier and the orders API returns a different code (e.g. C-0093), the check fails and the customer cannot see their orders. Codes are never reduced to digits: C-0093 and 0093 are distinct customers.
Security and privacy#
Ownership check#
The adapter queries the API and converts the response; it does not determine which orders the customer may see. After each response, a check in the Flow-e code (not an AI model) retains only the customer's orders:
- guest: an order is shown only if
order_refandemailmatch those provided by the customer. If the API does not return the email, no order is shown to guests; never a list, at most one order; - logged-in customer: only orders whose
customer_refmatches the verified signature; - orders of other customers returned by the API are discarded;
emailandcustomer_refare then removed from every order;customer_refmust be a string (or a number): an array or an object fails the check.
At the store's request, guest lookup can be disabled (logged-in customers only); the setting is managed by Flow-e. In that case, when a guest asks about an order or a return, the assistant invites the customer to sign in to their account on the site.
Limit on guest attempts#
After 5 unsuccessful lookups (order not found or email not matching) within 15 minutes for the same email or the same order number, for the following 15 minutes lookups with that email or that number receive the response "order not found", even when the data is correct. Technical problems of the API do not count as attempts. The limit prevents the lookup from being used to guess order numbers or emails; email and number are compared case-insensitively, without leading or trailing spaces and without leading # characters.
Trade-off of the limit. Anyone who knows an email or an order number can, with 5 incorrect lookups, block guest lookup for that email or that number for 15 minutes. Logged-in customers are not affected: their orders are read with the site signature.
Retained data and retention periods#
| Data | Location | Retention |
|---|---|---|
| Store API response | not retained | — |
| Order shown in the chat | in the conversation, like any message | 120 days |
| Logged-in customer profile: summary and latest orders (up to 25, with number, date, total, status and items; no email, customer code or addresses) | the store's Flow-e customer profile | refreshed at most once an hour; deleted after 120 days of inactivity |
| Return request | the store's ticket in the Flow-e portal | as for the store's other tickets |
| Counters of the protection and of the limit on attempts: for guest attempts only the cryptographic fingerprint (SHA-256) of email and order number, never the text | Flow-e database | deleted within 3 days of the last update |
A profile is created exclusively for logged-in customers with a verified signature who visit pages with the assistant, if the store has enabled personalisation and the customer has not objected. No profile is created for guests. Flow-e does not replicate the store's order archive: it reads only the orders of the customer being served, at the time of the request.
Store side#
- A key dedicated to Flow-e, read-only, revocable at any time.
- Each call contains only the lookup data (number and email, or customer code).
- Every call carries the
X-Request-Idheader, a unique identifier of the call, to be recorded in the store's logs to correlate calls. Flow-e does not retain these identifiers. - In the event of an anomaly, Flow-e communicates the date and time (UTC) and the operation concerned (
searchorby_customer); likewise, to report an anomalous call, the store provides Flow-e with its date and time.
Returns#
A return request submitted by the customer is recorded as a ticket in the "Returns" category in the store's portal. If the store has configured a webhook destination with the return.requested event, the store's system receives the structured request (lines, reasons, solutions, exchanges, price difference, window), signed with HMAC-SHA256 per the Standard Webhooks specification. The full event contract will be published in the Webhooks section; in the meantime it is available on request.
| Webhook field | Value for stores connected according to this guide |
|---|---|
data.order.id | the order's order_id, or order_ref if order_id is absent |
data.order.name | order_ref, as shown to the customer |
data.order.platform | the store's platform |
data.return.lines[].line_item_id | items[].line_ref returned by the store's API |
data.return.lines[].exchange.variant_id | the identifier of the Flow-e catalog product selected for the exchange |
data.return.customer_verified_by | order_email (guest) or store_account (logged-in customer) |
All identifiers are opaque strings of up to 128 characters, to be stored and compared without transformation. Flow-e does not modify the order in the store's system: the store remains responsible for handling the return. Return rules (window, allowed reasons, exclusions, sale items, exchanges) are defined in the Flow-e portal.
Acceptance testing#
Acceptance testing is carried out on the test environment, where available, otherwise on the production environment with test data. Flow-e runs the following cases with the test orders provided by the store:
| # | Case | Expected result |
|---|---|---|
| 1 | guest, correct number and email | order card |
| 2 | guest, incorrect email | "order not found" |
| 3 | guest, non-existent number | "order not found", identical to case 2 |
| 4 | guest, order number only | the assistant requests the email |
| 5 | logged-in customer | only the customer's own orders |
| 6 | logged-in customer providing another customer's order number | "order not found" |
| 7 | API unreachable or slower than 4 s | technical problem reported, no unverified data |
| 8 | return of a delivered item | return panel and ticket created; an identical second submission does not create a new ticket |
| 9 | return of an order not shipped or cancelled | explanation, no return |
| 10 | API unreachable for several consecutive calls | after the fifth error within 60 seconds, calls are suspended for 60 seconds; meanwhile a technical problem is reported; automatic resumption |
| 11 | guest, 5 lookups with an incorrect email | after the fifth unsuccessful request, "order not found" for 15 minutes even with the correct email |
| 12 | guest lookup disabled | invitation to sign in to the account |
Once acceptance testing is passed, Flow-e enables the connection. Disabling it takes effect immediately and does not affect the other functions of the assistant.
Response codes#
| Store API response | Flow-e interpretation | Response to the customer |
|---|---|---|
200 with one or more orders | found (followed by the ownership check) | the card, if the order belongs to the customer |
200 with { "orders": [] }, or 404 | not found | "order not found" |
401, 403 | incorrect or revoked key: system unavailable | technical problem |
429, 5xx, over 4 seconds, network error, non-JSON body or larger than 1 MB | system unavailable | technical problem |
No error discloses to the customer whether an order exists.
Protection of the store's API and alerts#
| Situation | Behaviour |
|---|---|
| 5 "system unavailable" responses within 60 seconds | Flow-e suspends calls to that store's API for 60 seconds. During the interval the assistant immediately reports the technical problem, with the option to retry, without querying the API; calls then resume automatically. The suspension affects only that store. |
| Repeated errors | "API error" alert to the Flow-e team, when the suspension starts or after 3 errors within 30 minutes |
| The API returns orders of other customers | the orders are discarded by the ownership check and the Flow-e team receives an "orders of other customers" alert: it indicates a defect of the endpoint |
| The response comes from a connector configured for another store | the response is discarded, the customer is informed of a technical problem and the Flow-e team receives an "isolation" alert (internal Flow-e check) |
| Alert frequency | at most one alert every 30 minutes for each type; one type does not hold back the alerts of the others |
When an alert is raised, the Flow-e team contacts the store's technical contact, stating the date and time (UTC) and the operation of the calls concerned.
FAQ#
What is required for the connection?#
With an existing API: documentation, a read-only key, test orders and, where applicable, authorisation of the Flow-e IP address. Without an API: a read-only endpoint that meets the requirements. For logged-in customers: the signature on the page.
Is the Flow-e Orders API v1 format mandatory?#
No. An existing API can be used in any format, with conversion performed by the adapter. The recommended format applies to new endpoints, which then require no conversion.
Does the store's system need to send data to Flow-e?#
No. Flow-e queries the store's API, exclusively in response to a customer request.
Can an API error expose other customers' orders?#
No. The ownership check is performed by Flow-e and discards any order that does not match.
Can the customer code be alphanumeric?#
Yes: any string of up to 128 characters, compared by exact equality.
Is it possible to expose only lookup by order number and email?#
Yes: order status and returns are then available to guests. The order list and the profile of logged-in customers require lookup by customer code.
What happens if the API is slow or unavailable?#
Any call exceeding 4 seconds is considered failed and the customer is informed of a technical problem. After 5 errors within 60 seconds, calls are suspended for 60 seconds and the Flow-e team receives an alert; the other functions of the assistant are not affected.
How are changes to the API handled?#
Changes to the API must be communicated in advance so that the adapter can be updated. Until the update, the assistant reports a technical problem; other functions of the site are not affected. Contact: team@looma.company.