Contents

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.

Updated on 15 November 2026Version 1.2Stores on their own platform

Introduction

Flow-e reads the orders of a single customer, at the time of the request, from the store's system. The connector (adapter) is provided and maintained by Flow-e. The store provides read-only access to an orders API: an existing API can be used in its own format; for a new endpoint the recommended format is Flow-e Orders API v1.
  1. 1OverviewThe functions available to the customer in the chat: orders, returns, profile.
  2. 2Possible pathsExisting API in any format, new endpoint in the recommended format, or reference to the orders page.
  3. 3Endpoint requirementsTwo lookups, read-only, HTTPS, response within 4 seconds.

Overview: what the customer sees in the chat#

FeatureBehaviour in the chatRequirement
Order status, guestWhen 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 customerWhen 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 exchangesFrom 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 profileFor 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:

  1. The API documentation (link or PDF) and the test environment address, where available.
  2. 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.
  3. 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.
  4. The list of order statuses of the system, with the meaning of each.
  5. The optional fields available: variant options (size, colour), line category and brand, quantity still returnable, shipping and delivery dates.
  6. 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 fieldFlow-e field
orderNumberorder_ref
createdAtplaced_at
state: "SENT"status: "shipped"
buyer.email · buyer.idemail · customer_ref
lines[].qtyOrdereditems[].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).

TopicRequirement
Two lookupsby 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 codeused exclusively for the ownership check and removed immediately afterwards: neither shown in the chat nor stored
Protocolhttps:// only, with a valid certificate
Authenticationkey in an HTTP header (Authorization: Bearer … or X-Api-Key: …), never in the URL
Response timewithin 4 seconds; beyond that limit the call is considered failed
Response sizebody up to 1 MB; a larger response is considered failed
X-Request-Id headerpresent in every Flow-e call: unique identifier of the call, to be recorded in the store's logs to correlate calls
Permissionsread-only, limited to orders
Order not found200 with an empty list, or 404
Errors401/403, 429, 5xx, non-JSON body: "system unavailable"
FormatsUTF-8 JSON; ISO 8601 dates with time zone (2026-11-02T10:15:00Z); amounts as numbers or strings with a decimal point
Identifiersany 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
Volumeone 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.

Request#

A single URL, POST method, JSON body, key in a header. Two operations:

FieldTypeWhenMeaning
operation"search" | "by_customer"alwaysguest lookup or logged-in customer lookup
order_refstring ≤ 64searchorder number as shown to the customer, without #
emailstring ≤ 254searchemail provided by the customer, compared by Flow-e with the order's email
customer_refstring ≤ 128by_customercustomer code, identical to the one in the signature
limitinteger 1-25by_customermaximum 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.

RuleDetail
Length1 to 64 characters
Allowed charactersASCII letters (A-Z, a-z), digits (0-9) and the symbols - _ . /
First charactera 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.

FieldTypeRequiredUsage
order_refstring ≤ 64yesorder number shown to the customer: lookup and card
order_idstring ≤ 128 | nullnointernal identifier; reference in returns
placed_atstring ISO 8601yescard, sorting, profile
statusenum (9 values)yescard
status_labelstring | nullnolabel in the store's language, shown when the status is unknown
closedbooleanrecommendedtrue = no longer returnable (cancelled, payment voided, refunded)
currencystring ISO 4217yescard, profile
totals.totalnumberyescard, profile
totals.subtotal · shipping · discount · taxnumber | nullnocard; discount feeds the profile (purchases on promotion)
emailstringyesguest check
customer_refstring ≤ 128yes for logged-in customerslogged-in check
order_page_urlhttps | nullnobutton on the card
shipments[]array ≤ 10recommendedcard; the return window starts at delivery (or shipping + 7 days)
shipments[].carrier · tracking_number · tracking_urlstring | nullnocarrier and tracking
shipments[].shipped_at · eta · delivered_atstring ISO 8601 | nullrecommendedshipped, estimated delivery, delivered
items[]array ≤ 50yesorder lines
items[].line_refstring ≤ 128recommended (yes for returns)identifies the item to return
items[].sku · product_refstring | nullrecommendedidentical to those in the Flow-e catalog: images, exchanges for other variants, return exclusions
items[].namestringyescard
items[].variantstring | nullnovariant label (M · Blue)
items[].options[][{ name, value }] ≤ 10novariant options (Size: M): profile, sizes per category
items[].qtynumberyesordered quantity
items[].qty_returnablenumber | nullrecommendedquantity still returnable (if absent, qty applies)
items[].unit_price_paid · unit_price_listnumber | nullnocard, sale items in returns
items[].image_urlhttps | nullnocard
items[].brand · categorystring | nullnoprofile; return exclusions by brand or category
items[].tags[]string[] ≤ 20noreturn 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.

ElementLimitBeyond the limit
Orders25excess orders are ignored
Lines per order (items[])50excess lines are ignored
Shipments per order (shipments[])10excess shipments are ignored
Options per line (items[].options[])10excess options are ignored
Tags per line (items[].tags[])20excess tags are ignored
items[].name, items[].brand, items[].category200 characterstext truncated
items[].variant, name and value of items[].options[], items[].tags[]120 characterstext truncated
Other texts500 characterstext truncated
order_ref64 charactersthe whole order is discarded
Other identifiers (order_id, customer_ref, line_ref, sku, product_ref)128 charactersvalue ignored, never truncated
email254 charactersvalue ignored
URLs (order_page_url, tracking_url, image_url)https:// only, up to 2000 characters, without spaces, quotes or angle bracketsvalue 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.

statusMeaning
pending_paymentawaiting payment
processingpaid, being prepared
shippedshipped
partially_shippedpartially shipped
delivereddelivered
cancelledcancelled
refundedrefunded
returnedreturned
unknownnot recognised (status_label is shown)

Examples#

Request#

bash
# 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"}'
bash
# 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)#

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

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

text
signature = HMAC-SHA256( secret, "<customer_ref>:<ts>" )   // lowercase hex
ts        = Unix seconds when the page is generated
php
<?php
// Server side: the secret never reaches the browser
$ts        = (string) time();
$signature = hash_hmac('sha256', $customerRef . ':' . $ts, $secret);
javascript
// 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");
RuleDetail
Secretthe 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
Validity24 hours from ts; a ts more than 5 minutes ahead of the current time is rejected
data-user-ididentical 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 inonly 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_ref and email match 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_ref matches the verified signature;
  • orders of other customers returned by the API are discarded;
  • email and customer_ref are then removed from every order;
  • customer_ref must 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#

DataLocationRetention
Store API responsenot retained—
Order shown in the chatin the conversation, like any message120 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 profilerefreshed at most once an hour; deleted after 120 days of inactivity
Return requestthe store's ticket in the Flow-e portalas 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 textFlow-e databasedeleted 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 (search or by_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 fieldValue for stores connected according to this guide
data.order.idthe order's order_id, or order_ref if order_id is absent
data.order.nameorder_ref, as shown to the customer
data.order.platformthe store's platform
data.return.lines[].line_item_iditems[].line_ref returned by the store's API
data.return.lines[].exchange.variant_idthe identifier of the Flow-e catalog product selected for the exchange
data.return.customer_verified_byorder_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:

#CaseExpected result
1guest, correct number and emailorder card
2guest, incorrect email"order not found"
3guest, non-existent number"order not found", identical to case 2
4guest, order number onlythe assistant requests the email
5logged-in customeronly the customer's own orders
6logged-in customer providing another customer's order number"order not found"
7API unreachable or slower than 4 stechnical problem reported, no unverified data
8return of a delivered itemreturn panel and ticket created; an identical second submission does not create a new ticket
9return of an order not shipped or cancelledexplanation, no return
10API unreachable for several consecutive callsafter the fifth error within 60 seconds, calls are suspended for 60 seconds; meanwhile a technical problem is reported; automatic resumption
11guest, 5 lookups with an incorrect emailafter the fifth unsuccessful request, "order not found" for 15 minutes even with the correct email
12guest lookup disabledinvitation 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 responseFlow-e interpretationResponse to the customer
200 with one or more ordersfound (followed by the ownership check)the card, if the order belongs to the customer
200 with { "orders": [] }, or 404not found"order not found"
401, 403incorrect or revoked key: system unavailabletechnical problem
429, 5xx, over 4 seconds, network error, non-JSON body or larger than 1 MBsystem unavailabletechnical problem

No error discloses to the customer whether an order exists.

Protection of the store's API and alerts#

SituationBehaviour
5 "system unavailable" responses within 60 secondsFlow-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 customersthe 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 storethe 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 frequencyat 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.