Create Bag Adjustment

Create Bag Adjustment

post

Creates a new adjustment record for a bag. Adjustments are immutable audit records that track corrections to bag totals (shipping, tax, or discount). The adjustment amounts (shopper, merchant, channel) must sum to zero. Only apps that created the bag (matching app_id) can create adjustments on it.

Path parameters

order_idinteger · int64Required

bag_idinteger · int64Required

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

Body

application/json

Financial adjustment to a Bag's totals

idinteger · int64Read-onlyOptional

Unique ID of the BagAdjustment.

bag_idinteger · int64Required

ID of the Bag this adjustment applies to.

order_idinteger · int64Required

ID of the parent Order (denormalized for convenience).

merchant_idinteger · int32Required

ID of the merchant this adjustment applies to.

app_idinteger · int32Required

ID of the App responsible for this Bag.

entity_typestring · enumRequired

Type of field being adjusted: SHIPPING_TOTAL, TAX_TOTAL, or DISCOUNT_TOTAL.

Possible values:

previous_valueinteger · int32Required

Original incorrect value in cents.

adjusted_valueinteger · int32Required

Corrected value in cents.

adjustment_deltainteger · int32Read-onlyOptional

Calculated difference (adjusted_value - previous_value) in cents.

shopper_adjustmentbooleanRequired

Whether this adjustment impacts the shopper.

shopper_adjustment_amountinteger · int32Required

Amount of impact on shopper in cents (negative = refund owed to shopper).

merchant_adjustmentbooleanRequired

Whether this adjustment impacts the merchant.

merchant_adjustment_amountinteger · int32Required

Amount of impact on merchant in cents (positive = merchant owed more, negative = merchant owed less).

channel_adjustmentbooleanRequired

Whether this adjustment impacts the channel.

channel_adjustment_amountinteger · int32Required

Amount of impact on channel in cents (typically opposite of merchant + shopper).

reasonstringRequired

Freeform text reason for the adjustment.

date_createdstring · date-time · max: 24Read-onlyOptional

Date the adjustment was created (immutable).

Responses

201

Adjustment created successfully

application/json

400

Invalid adjustment data

application/json

404

Order or bag not found

post

/orders/{order_id}/bags/{bag_id}/adjustments

HTTPcURLJavaScriptPython

POST /v1/orders/{order_id}/bags/{bag_id}/adjustments HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "entity_type": "SHIPPING_TOTAL",
  "previous_value": 1000,
  "adjusted_value": 500,
  "shopper_adjustment": true,
  "shopper_adjustment_amount": -500,
  "merchant_adjustment": false,
  "merchant_adjustment_amount": 0,
  "channel_adjustment": true,
  "channel_adjustment_amount": 500,
  "reason": "Shipping was overcharged due to carrier rate update"
}

Shipping AdjustmentTax Adjustment with MetadataDiscount Adjustment

{
  "id": 10001,
  "bag_id": 22222,
  "order_id": 11111,
  "merchant_id": 10000,
  "app_id": 10193,
  "entity_type": "SHIPPING_TOTAL",
  "previous_value": 1000,
  "adjusted_value": 500,
  "adjustment_delta": -500,
  "shopper_adjustment": true,
  "shopper_adjustment_amount": -500,
  "merchant_adjustment": false,
  "merchant_adjustment_amount": 0,
  "channel_adjustment": true,
  "channel_adjustment_amount": 500,
  "reason": "Shipping was overcharged due to carrier rate update",
  "date_created": "2024-12-08T15:30:00+0000"
}