Refund Bag

Bag refunds is in beta. Please report any errors to Violet.

Initiate a refund on a Bag. This can be a full refund or a partial refund depending on the amounts you provide. This action will attempt to refund the external order in the merchants system.

The Bag must be in a refundable state. Any Bag's that have a status of IN_PROGRESS, REFUNDED, or CANCELED cannot be refunded.

Refund Bag

post

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

Request used to initiate a bag refund.

reasonstring · max: 255 · nullableOptional

Custom reason message for the refund.

restock_itemsboolean · nullableOptional

Should the items be restocked. Set to true when the order is being returned.

Default: false

notify_customerboolean · nullableOptional

Should the customer be notified by the merchants system of the refund. If no value is provided the merchants default system configuration for this feature will be used.

Default: false

amount_refundedinteger · int32 · nullableOptional

Amount that should be refunded in cents. If no value is provided the full bag amount will be refunded.

Responses

default

default response

application/json

post

/orders/{order_id}/bags/{bag_id}/refunds

HTTPcURLJavaScriptPython

POST /v1/orders/{order_id}/bags/{bag_id}/refunds 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: 126

{
  "amount_refunded": 1000,
  "shipping": {
    "amount": 500
  },
  "skus": [
    {
      "order_sku_id": 10000,
      "quantity_refunded": 1,
      "amount_refunded": 500
    }
  ]
}

default

default response

{
  "id": 1,
  "order_id": 1,
  "bag_id": 1,
  "merchant_id": 1,
  "app_id": 1,
  "transaction_id": 1,
  "payment_transaction_id": 1,
  "gateway_transaction_id": "text",
  "amount": 1,
  "merchant_transfer_reversal_amount_usd": 1,
  "developer_transfer_reversal_amount_usd": 1,
  "merchant_transfer_reversal_amount_platform_currency": 1,
  "developer_transfer_reversal_amount_platform_currency": 1,
  "reason": "text",
  "reason_code": "OTHER",
  "refund_currency": "text",
  "platform_currency": "text",
  "status": "PROCESSING",
  "skus": [
    {
      "id": 1,
      "refund_id": 1,
      "order_sku_id": 1,
      "bag_id": 1,
      "quantity_refunded": 1,
      "external_id": "text"
    }
  ],
  "transfer_reversals": [
    "text"
  ],
  "date_created": "2026-02-02T17:38:54.218Z",
  "date_last_modified": "2026-02-02T17:38:54.218Z",
  "external_id": "text",
  "errors": [
    {
      "id": 1,
      "error_code": 1,
      "error_message": "text",
      "resolved": true,
      "date_resolved": "2026-02-02T17:38:54.218Z",
      "date_created": "2026-02-02T17:38:54.218Z",
      "refund_id": 1
    }
  ],
  "shipping": {
    "amount": 1,
    "tax_amount": 1,
    "full_refund": true,
    "discrepancy_reason": "text"
  },
  "tax_amount": 1
}