Conventions

Requests and responses

Method: POST
For every operation, including reads.
Content type: application/json
Required when you send a body.
Empty body: Read as {}
A POST with a JSON content type and no body counts as an empty object.
Responses: Always a JSON object
Delete and cancel operations return {}.
Unknown fields: Ignored
New response fields can be added at any time.
Field names: snake_case
Requests also accept camelCase.
Enums: String names
Some include their type as a prefix, such as "FULFILLMENT_PRIORITY_HIGH" or "RETURN_STATUS_RETURNED". Order, inbound shipment and tracking statuses don't, for example "SHIPPED". Each field's page lists its values.

Money

Amounts are strings that hold a decimal value in the main currency unit. This applies to unit_price, unit_tax, discount, shipping_price, total, value.amount and unit_landed_cost.

{ "unit_price": "24.90", "unit_tax": "4.15", "currency": "EUR" }

"24.90" means 24.90 euros. Don't send cents: "2490" means 2,490 euros.
Precision depends on the currency, for example two decimals for EUR and none for JPY. Extra decimals are truncated.
On input, . and , both work as decimal separators, and spaces are removed. Send . without thousands separators.
An amount that can't be parsed, or an unknown currency, fails with invalid_argument.
An empty or missing amount counts as zero.
Responses return amounts without trailing zeros: "24.90" comes back as "24.9", and "5.00" as "5".

Each order has one currency, an ISO 4217 code, and its line items use it. Products set their currency in value.

See Prices for how an order's tax, discount and total are calculated.

Dates and times

Format	Example	Fields
RFC 3339 in UTC, to the second	`2026-03-14T09:30:00Z`	`submit_time`, `create_time`, `update_time`, `expected_arrival_time`, `auto_fulfill_schedule_time`, date ranges
Date	`2026-09-30`	`lot_expiration_date`

Timestamps must end in Z. Time zone offsets such as +02:00 and fractional seconds are rejected.

lot_expiration_time is deprecated

Use lot_expiration_date (YYYY-MM-DD). Responses still include lot_expiration_time, set to midnight UTC on that date. If you only send lot_expiration_time, its first ten characters are used as the date.

Updates

UpdateProduct, UpdateBundle and UpdateOrder replace the whole object. Fields you leave out are cleared. Get the current object, change it, then send all of it back.

UpdateInboundShipment and UpdateReturn work differently. They take an update_mask that lists the fields to change.

Empty values

An empty string, 0, false and a missing field mean the same thing.
You can't clear a single field by sending null. Fields are cleared when an update replaces the whole object.
Responses leave out empty values. A count of 0, an empty string, false and an empty list don't appear at all. For example, an inventory row with no damaged units has no damaged field, so read it as row.damaged ?? 0.
Treat enum values you don't recognize as unspecified.

Codes and formats

Field	Standard	Example
`country`, `origin_country`	ISO 3166-1 alpha-2	`FR`
`language`	ISO 639-1	`fr`
`currency`	ISO 4217	`EUR`
`tariff_number`	HS code, 6–16 digits and dots	`6109.10`

Addresses

Most ShippingAddress and BillingAddress lines are limited to 38 characters, postal to 12 and email to 128. These limits come from carrier labels. Values that are too long are rejected, not shortened.

A shipping address needs line1, city and country. The billing address is optional and defaults to the shipping address.