# 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.

{% hint style="info" %}
**Related Documentation**

* [Distributions & Adjustments FAQ](https://github.com/violetio/docs/blob/main/channel-docs/faqs/distributions.md) - Common questions about how adjustments work
* [Understanding Adjustments (Merchants)](https://github.com/violetio/docs/blob/main/merchant-docs/interactions/understanding-adjustments.md) - Merchant-facing guide
  {% endhint %}

### 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:

```json
{
  "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:

```json
{
  "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)    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/api-reference/orders-and-checkout/order-adjustments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.