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.
