| HQ |
Headquarters. Owns this API and the standard code lists. |
| Partner |
A company (or its POS vendor) that pushes data for one or more stores. Identified by partner_id. |
partner_id |
Your partner code, assigned by HQ (e.g. NCMD001). It is linked to your API key — you never send it. |
store_id |
Your store code. Must be registered with HQ for your partner account. |
Business date (business_date) |
The store-local date a transaction belongs to, in YYYY-MM-DD. It is cut at the store's workday_start, not at midnight. |
workday_start |
Store-local time (HH:mm) when a new business date begins. With 04:00, a sale at 01:30 on Oct 15 belongs to business date Oct 14. |
| Batch |
One write request. Each batch carries up to 500 records. |
batch_id |
A UUID you generate for every write request. It is the idempotency key: resending the same batch_id never creates duplicates. See Idempotency & Retry. |
batch_seq |
Sequence number (from 1) of a /trade-records batch within one store and business date. |
version |
Integer revision of a record. Increase it by 1 every time a transaction or product changes. The highest version wins. |
| Source code |
Your own POS code, e.g. your transaction type "Refund" (source_transaction_type). |
| Standard code |
HQ's code for the same concept, e.g. REFUND. You map source codes to standard codes once via Transaction Type Mappings. |
| Suggested code list |
A code list (e.g. order_source, payment_type) where HQ recommends values but also accepts free strings. |
| Decimal string |
A number sent as a JSON string, e.g. "12.50". All amounts and quantities use this format. |
| Localized text |
An object keyed by BCP 47 language tag, e.g. {"en-US":"Fries","zh-TW":"薯條"}. |
| Combo |
A set meal sold at one price, recorded as a parent line plus child lines. See Recording Rules. |
| Modifier |
An option chosen for an item (flavor, add-on, drink upgrade), possibly with a price delta. |
| Daily close |
The message you send after all of a business date's transactions, carrying control totals. |
| Control totals |
Counts and amounts you calculated for the day (records, items, payments, net sales…). HQ compares them with what it received. |
| Reconciliation |
HQ's comparison of your control totals with the transactions it received. Result: MATCHED or MISMATCHED. |