Order Adjustments

Manages adjustment records for orders and bags.

Overview

Adjustments are immutable audit records that track corrections to bag totals after an order has been placed. They provide a transparent history of any changes made to shipping, tax, or discount amounts.

Adjustment Entity Types

Adjustments can be created for the following entity types:

Entity Type	Description
SHIPPING_TOTAL	Corrections to shipping charges (e.g., carrier rate updates)
TAX_TOTAL	Corrections to tax amounts (e.g., jurisdiction miscalculations)
DISCOUNT_TOTAL	Post-order promotional discounts or corrections

How Adjustments Work

Each adjustment tracks:

• Previous Value: The original amount before correction

• Adjusted Value: The new corrected amount

• Adjustment Delta: The difference between previous and adjusted values

Cost Distribution

Adjustments must specify how the cost change is distributed among three parties. The sum of these amounts must equal zero:

Party	Description
Shopper	Amount the shopper owes (positive) or is refunded (negative)
Merchant	Amount the merchant receives (positive) or absorbs (negative)
Channel	Amount the channel receives (positive) or absorbs (negative)

Example Scenarios

Shipping Overcharge Correction

When shipping was overcharged and the channel absorbs the cost:

{
  "entity_type": "SHIPPING_TOTAL",
  "previous_value": 1000,
  "adjusted_value": 500,
  "shopper_adjustment_amount": -500,
  "merchant_adjustment_amount": 0,
  "channel_adjustment_amount": 500
}

Tax Miscalculation

When tax was undercharged and the merchant absorbs the difference:

{
  "entity_type": "TAX_TOTAL",
  "previous_value": 850,
  "adjusted_value": 1050,
  "shopper_adjustment_amount": 200,
  "merchant_adjustment_amount": -200,
  "channel_adjustment_amount": 0
}

Access Control

Only apps that created the order or bag (matching app_id) can access or create adjustments.

Available endpoints:

 GET /v1/orders/{order_id}/adjustments
 GET /v1/orders/{order_id}/bags/{bag_id}/adjustments
POST /v1/orders/{order_id}/bags/{bag_id}/adjustments
 GET /v1/orders/{order_id}/bags/{bag_id}/adjustments/{adjustment_id}