Skip to main content

Adjustment (object schema)

Adjustment object schema — manual corrections to the amount of an order or one of its line items. Available from API version 07.2025.

Written by Frank Birzle

An Adjustment is a manual change to the amount of an order or of one of its line items — a price correction, a surcharge, a goodwill deduction. Adjustments are supplied in the adjustments array on the Order object.

Only supported from API version 07.2025. Earlier versions ignore the field instead of rejecting it, so a payload containing adjustments sent to 12.2022 is accepted but the adjustments are silently dropped.

id

Type: string — required

Description: Must be unique within the order. The same id may be used in other orders.

Example Value(s): 'adj-1'

target

Type: string — required

Description: What the adjustment applies to: one line item of the order, or the order as a whole. One of 'item' or 'order'.

Example Value(s): 'item' or 'order'

lineItemId

Type: string — conditional

Description: Id of a line item of the same order (not of a bundled product). Required when target is 'item', must be omitted when target is 'order'.

Example Value(s): '999999'

adjustmentAmount

Type: number — required

Description: Amount in the order's currency, on the same basis as totalAmountAfterTaxesAndDiscounts. Positive values reduce the total of the target, negative values increase it.

Example Value(s): 5 or -1.25

Mind the sign. A positive adjustmentAmount makes the target cheaper, a negative one makes it more expensive. That is the opposite of what most systems do, and it is the most common mistake with this object.

createdAt

Type: integer — required

Description: Unix timestamp in seconds.

Example Value(s): 1640979772

description

Type: string — optional

Description: A free-text label for the adjustment, for your own reference.

Example Value(s): 'Price correction' or 'Small-order surcharge'

Example

The adjustments array of an order carrying both kinds of adjustment:

"adjustments": [
{
"id": "adj-1",
"target": "item",
"lineItemId": "999999",
"adjustmentAmount": 5,
"createdAt": 1640979772,
"description": "Price correction"
},
{
"id": "adj-2",
"target": "order",
"adjustmentAmount": -1.25,
"createdAt": 1640979772,
"description": "Small-order surcharge"
}
]

The first entry takes 5.00 off line item 999999. The second adds 1.25 to the order total.

Did this answer your question?