Conventions
The same rules for every resource. Each resource's fields are in the reference.
Requests and responses
Section titled "Requests and responses"- JSON both ways. A request with a body sends
Content-Type: application/json. - No sessions and no cookies: every request authenticates with
Authorization: Bearer(authentication). - The API's texts (error titles and details) are in English.
Identifiers
Section titled "Identifiers"Every resource has a public, opaque identifier with a prefix for its type:
| Prefix | Resource |
|---|---|
ord_ |
order |
shp_ |
shipment (AWB) |
inv_ |
invoice |
int_ |
integration |
org_ |
organization (GET /organization, a webhook's organization field) |
msg_ |
webhook delivery (the webhook-id header) |
A ULID follows the prefix. Treat the identifier as opaque text: do not parse it, do not build it, and rely on nothing in its shape beyond the prefix. Internal numeric ids never appear in the API.
An amount is an object with the value as a decimal string and the currency:
{ "amount": "149.90", "currency": "RON" }The value has at least the currency's minor digits (its ISO 4217 exponent: RON and EUR 2, JPY 0, KWD 3), and more only where the stored value has non-zero digits past them:
| Stored | Currency | amount |
|---|---|---|
149.9000 |
RON | "149.90" |
12.3456 |
RON | "12.3456" |
10.5000 |
JPY | "10.5" |
1500.0000 |
JPY | "1500" |
The value is a string so it never goes through floating-point numbers. Read it into a decimal type (decimal, BigDecimal, Decimal), never a float, and assume no fixed number of decimals.
Quantities, rates and measures
Section titled "Quantities, rates and measures"Every other decimal is a decimal string with no trailing zeros: a quantity (quantity on an order's or an invoice's lines: "2", "1.5", "-2", negative on a storno), a tax rate (tax_rate: "21", "9.5"), a weight in kilograms (total_weight_kg, a parcel's weight_kg: "1.25") and a size in centimetres (length_cm, width_cm, height_cm: "30"). Read it into a decimal type too.
Dates and times
Section titled "Dates and times"- A moment is ISO 8601 / RFC 3339, in UTC, with microseconds, always six digits:
2026-11-13T09:30:00.123456Z. Two changes within one second stay in order. - A calendar day with no time (an invoice's
issue_date, for example) is2026-11-13, with no time zone: the day in the organization's calendar. - The organization's time zone (
timezone) is answered byGET /organization; resources do not repeat it.
Codes, not labels
Section titled "Codes, not labels"Statuses and kinds are stable codes, documented in the reference, never translated text. A code does not change in v1; the label the merchant sees in the dashboard may change at any time. Always compare codes.
Code lists can grow within v1 (a new status, a new issue code). Treat an unknown code as unknown and carry on: never fail on it.
The same names in every resource
Section titled "The same names in every resource"| Field | Means |
|---|---|
integration_id |
the integration (int_...) the record came or went through: an order's store, an AWB's courier account, an invoice's invoicing account |
vendor |
that integration's vendor code (shopify, sameday, smartbill); on an AWB, carrier is who transports the parcel |
external_id |
the vendor's own identifier (an order's in its store, a pickup point's at its courier) |
cod |
cash on delivery, as money (payment.cod on an order, cod on an AWB) |
tax, tax_rate, tax_id |
the tax (money), its rate (a percentage, "21"), the fiscal code (CUI, VAT number, CNP) |
<list>_count |
how many items the list has in all, when the list in the response is bounded (line_items_count, lines_count) |
delivery.method / delivery_method |
where the parcel goes: address or pickup_point (an order may also be store_pickup or mixed) |
Addresses
Section titled "Addresses"An order's addresses, an AWB's sender and recipient and an invoice's buyer share one shape:
{ "name": "Ana Pop", "first_name": "Ana", "last_name": "Pop", "company": null, "email": "ana@example.com", "phone": "+40722111222", "address_line_1": "Str. Lungă 2", "address_line_2": "Ap. 3", "city": "Cluj-Napoca", "region": "Cluj", "region_code": "CJ", "postal_code": "400001", "country_code": "RO", "locality_code": "54975"}Every field is present; where the source holds none, the value is null. An AWB and an invoice keep no separate first and last name (first_name, last_name are null); an invoice's company is the buyer's name when the buyer is a company. region_code is the ISO 3166-2 subdivision without its country, locality_code the locality's code in its country's official register (SIRUTA, EKATTE), null until placed. A resource may add fields of its own beside the address: tax_id on an order's addresses, contact_person on an AWB, tax_id and registration_number on an invoice's buyer.
Errors on records
Section titled "Errors on records"An AWB or an invoice in status failed or needs_attention says why:
error_code: a stable code (vendor_rejected,invalid_data,outcome_unknown...), listed in the reference;error_message: the code's meaning, in English;vendor_message: the vendor's own words, when it answered, as it sent them (usually in its language): for display only, never to parse.
In any other status all three are null. The full reason, in the merchant's language, is in the dashboard.
New fields
Section titled "New fields"Within v1, responses can gain new fields and the API can gain new endpoints (versioning). Your client must ignore fields it does not know and never fail on them. Do not validate responses against a schema that rejects extra fields.