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

ID of the order containing the bag

Example: 11111

bag_idinteger · int64Required

ID of the bag to adjust

Example: 22222

Header parameters

X-Violet-TokenstringRequired

API token for authentication

X-Violet-App-SecretstringRequired

Application secret key

X-Violet-App-Idinteger · int32Required

Application ID

Example: 10000

Body

application/json

Financial adjustment to a Bag's totals

idinteger · int64Read-onlyRequired

Unique ID of the BagAdjustment.

bag_idinteger · int64Read-onlyOptional

ID of the Bag this adjustment applies to.

order_idinteger · int64Read-onlyOptional

ID of the parent Order (denormalized for convenience).

merchant_idinteger · int32Read-onlyOptional

ID of the merchant this adjustment applies to.

app_idinteger · int32Read-onlyOptional

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

created

application/json

Financial adjustment to a Bag's totals

idinteger · int64Read-onlyRequired

Unique ID of the BagAdjustment.

bag_idinteger · int64Read-onlyOptional

ID of the Bag this adjustment applies to.

order_idinteger · int64Read-onlyOptional

ID of the parent Order (denormalized for convenience).

merchant_idinteger · int32Read-onlyOptional

ID of the merchant this adjustment applies to.

app_idinteger · int32Read-onlyOptional

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

400

bad request

application/json

403

forbidden

application/json

404

not found

application/json

500

internal server error

application/json

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"
}

Correct a shipping overchargeCorrect a tax miscalculation with tracking dataApply a post-order promotional discount

{
  "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"
}