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.

Related Documentation

• Distributions & Adjustments FAQ - Common questions about how adjustments work

• Understanding Adjustments (Merchants) - Merchant-facing guide

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
}

Automatic Adjustments

Violet automatically creates adjustments in certain scenarios:

Shipping Reconciliation: Before funds are transferred to merchants, Violet compares the shipping amount charged at checkout against re-estimated shipping costs. If a significant discrepancy is detected (over $3.00), an adjustment is automatically created with:

• entity_type: SHIPPING_TOTAL

• reason: SHIPPING_RECONCILIATION

These automatic adjustments ensure accurate payouts without manual intervention.

Billing Impact

When an adjustment is created, Violet's billing system automatically generates ADJUSTMENT distributions:

Party Adjusted	Distribution Behavior
Merchant	Creates PENDING distribution included in next transfer
Channel	Creates SENT distribution settled against channel balance
Shopper	Tracked for audit (actual refunds handled separately)

Key billing rules:

• No commission recalculation: Adjustments never affect commission. Commission was calculated on the original transaction.

• Zero-sum accounting: The three adjustment amounts must always sum to zero

• Idempotent: Multiple calls to generate distributions for the same adjustment return existing records

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}

Adjustment Metadata

Adjustments support an optional data object for additional context:

Field	Description
notes	Additional notes about the adjustment
adjusted_by	User or system that created the adjustment
ticket_id	Support ticket ID related to the adjustment
refund_id	Refund ID if a refund was issued
refund_issued	Whether a refund was issued to the shopper
original_tax_rate	Original tax rate (for tax adjustments)
corrected_tax_rate	Corrected tax rate (for tax adjustments)