Skip to content

Conventions

The same rules for every resource. Each resource's fields are in the reference.

  • 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.

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.

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.

  • 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) is 2026-11-13, with no time zone: the day in the organization's calendar.
  • The organization's time zone (timezone) is answered by GET /organization; resources do not repeat it.

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.

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)

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.

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.

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.