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

Issues a refund for a specific bag within an order. Supports full bag refunds, partial amount refunds, and SKU-level refunds with optional shipping refunds. The bag must be in an ACCEPTED, SUBMITTED, COMPLETED, PARTIALLY_REFUNDED, or CANCELED state. If no amount_refunded is provided, the full bag total is refunded. If no skus array is provided, all SKUs in the bag are included in the refund. The refund is forwarded to the merchant's external commerce platform for processing. All monetary values are in the smallest currency unit (e.g. cents for USD).

Path parameters

order_idinteger · int64Required

ID of the order containing the bag to refund

Example: 11111

bag_idinteger · int64Required

ID of the bag to refund

Example: 22222

Query parameters

skip_external_refundbooleanOptionalDefault: false

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

Request used to initiate a refund for a specific Bag. Supports three refund modes: (1) Full refund — omit amount_refunded and skus to refund the entire Bag. (2) Partial refund by amount — set amount_refunded to a specific amount in cents. (3) Line-item refund — provide skus with specific OrderSku IDs and optional quantities/amounts to refund individual items. All monetary values are in cents.

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

200

success

application/json

Order Refund

idinteger · int64Read-onlyRequired

Unique ID of the Refund.

order_idinteger · int64Required

ID of the Order being refunded

bag_idinteger · int64Optional

ID of the Bag being refunded

merchant_idinteger · int32Required

ID of the merchant making the refund

app_idinteger · int32Required

ID of the App that created the Order

transaction_idinteger · int64Required

ID of the Transaction being refunded

payment_transaction_idinteger · int64Required

ID of the Payment Transaction in Violet

gateway_transaction_idstringRequired

ID of the Transaction in the Payment Gateway

amountinteger · int32Required

Amount being refunded. In Cents

merchant_transfer_reversal_amount_usdinteger · int32Optional

Amount being taken back from the associated transfer to the merchant. In Cents

developer_transfer_reversal_amount_usdinteger · int32Optional

Amount being taken back from the associated transfer to the developer. In Cents

merchant_transfer_reversal_amount_platform_currencyinteger · int32Optional

Amount in fractional currency unit (e.g. cents) being taken back from the associated transfer to the merchant, in platform currency.

developer_transfer_reversal_amount_platform_currencyinteger · int32Optional

Amount in fractional currency unit (e.g. cents) being taken back from the associated transfer to the developer, in platform currency.

reasonstringOptional

Reason for refund

reason_codestring · enumOptional

Reason code for refund

Possible values:

refund_currencystringOptional

Currency set for this refund by the external ecom platform

platform_currencystringOptional

Currency used by the platform account for the payment provider that processed this Refund

statusstring · enumOptional

Status of the Refund

Possible values:

transfer_reversalsstring[]Optional

Unique identifiers of the Transfer Reversal objects in Violet that are associated with this transfer.

date_createdstring · date-timeOptional

Date of creation

date_last_modifiedstring · date-timeOptional

Date of last update

external_idstringOptional

ID of the refund on the external commerce platform. This value will only be populated if the external commerce platform supports refund ID's.

tax_amountinteger · int32 · nullableOptional

Tax amount being refunded. In Cents.

400

bad request

application/json

404

not found

application/json

500

internal server error

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

{
  "amount_refunded": 1000,
  "reason": "Customer returned item due to defect.",
  "restock_items": true,
  "notify_customer": true,
  "shipping": {
    "amount": 500
  },
  "skus": [
    {
      "order_sku_id": 10000,
      "quantity_refunded": 1,
      "amount_refunded": 500
    }
  ]
}

Refund specific SKUs with custom amount and shippingRefund entire bag with no amount or SKU detailsRefund a specific amount without SKU breakdownRefund specific SKUs onlyRefund with explicit shipping amount and full_refund flag

{
  "id": 10000,
  "order_id": 11111,
  "bag_id": 22222,
  "merchant_id": 11111,
  "app_id": 10000,
  "transaction_id": 99999,
  "amount": 2500,
  "reason": "Customer returned item due to defect.",
  "refund_currency": "USD",
  "status": "COMPLETED",
  "skus": [
    {
      "id": 33333,
      "refund_id": 10000,
      "bag_id": 22222,
      "quantity_refunded": 1,
      "external_id": "43522846032108",
      "order_sku_id": 10000
    }
  ],
  "date_created": "2024-10-24T14:00:35+0000",
  "date_last_modified": "2024-10-24T14:00:35+0000",
  "external_id": "910123663596",
  "errors": []
}