POST
/
orders
/
{order_id}
/
bags
/
{bag_id}
/
refunds
curl --request POST \
  --url https://sandbox-api.violet.io/v1/orders/{order_id}/bags/{bag_id}/refunds \
  --header 'Content-Type: application/json' \
  --data '{
  "amount_refunded": 1000,
  "shipping": {
    "amount": 500
  },
  "skus": [
    {
      "order_sku_id": 10000,
      "quantity_refunded": 1,
      "amount_refunded": 500
    }
  ]
}'
{
  "id": 123,
  "order_id": 123,
  "bag_id": 123,
  "merchant_id": 123,
  "app_id": 123,
  "transaction_id": 123,
  "gateway_transaction_id": "<string>",
  "amount": 123,
  "merchant_transfer_reversal_amount_usd": 123,
  "developer_transfer_reversal_amount_usd": 123,
  "merchant_transfer_reversal_amount_platform_currency": 123,
  "developer_transfer_reversal_amount_platform_currency": 123,
  "reason": "<string>",
  "reason_code": "OTHER",
  "refund_currency": "<string>",
  "platform_currency": "<string>",
  "status": "PROCESSING",
  "skus": [
    {
      "id": 123,
      "refund_id": 123,
      "bag_id": 123,
      "quantity_refunded": 123,
      "external_id": "<string>",
      "order_sku_id": 123
    }
  ],
  "date_created": "2023-11-07T05:31:56Z",
  "date_last_modified": "2023-11-07T05:31:56Z",
  "external_id": "<string>",
  "errors": [
    {
      "id": 123,
      "error_code": 123,
      "error_message": "<string>",
      "resolved": true,
      "date_resolved": "2023-11-07T05:31:56Z",
      "date_created": "2023-11-07T05:31:56Z",
      "refund_id": 123
    }
  ],
  "shipping": {
    "amount": 1,
    "tax_amount": 1,
    "full_refund": true,
    "discrepancy_reason": "<string>"
  },
  "tax_amount": 1
}

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.

Headers

X-Violet-Token
string
X-Violet-App-Secret
string
X-Violet-App-Id
integer

Path Parameters

order_id
integer
required
bag_id
integer
required

Body

application/json

Request used to initiate a bag refund.

reason
string | null

Custom reason message for the refund.

Maximum length: 255
restock_items
boolean | null
default:false

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

notify_customer
boolean | null
default:false

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.

amount_refunded
integer | null

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

Required range: x >= 0
shipping
object | null

Details of any shipping refunds.

skus
array | null

Sku level refund data. If no Sku's are provided then all Skus will be refunded.

Sku level refund data. If no Sku's are provided then all Skus will be refunded.

Response

default - application/json
default response

Order Refund

order_id
integer
required

ID of the Order being refunded

merchant_id
integer
required

ID of the merchant making the refund

app_id
integer
required

ID of the App that created the Order

transaction_id
integer
required

ID of the Transaction being refunded

gateway_transaction_id
string
required

ID of the Transaction in the Payment Gateway

amount
integer
required

Amount being refunded. In Cents

id
integer
bag_id
integer

ID of the Bag being refunded

merchant_transfer_reversal_amount_usd
integer

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

developer_transfer_reversal_amount_usd
integer

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

merchant_transfer_reversal_amount_platform_currency
integer

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_currency
integer

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

reason
string

Reason for refund

reason_code
enum<string>

Reason code for refund

Available options:
OTHER,
CUSTOMER,
INVENTORY,
FRAUD,
DECLINED
refund_currency
string

Currency set for this refund by the external ecom platform

platform_currency
string

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

status
enum<string>

Status of the Refund

Available options:
PROCESSING,
COMPLETED,
CANCELED,
PARTIALLY_COMPLETED,
FAILED,
EXTERNAL
skus
object[]

SKUs the refund applies to

Refunded Order Sku

date_created
string

Date of creation

date_last_modified
string

Date of last update

external_id
string

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

errors
object[]

List of errors associated to this refund during processing. This value will only be populated if there are errors during processing

Error associated to a refund

shipping
object | null

Details of any refunded shipping amounts.

tax_amount
integer | null

Tax amount being refunded. In Cents.

Required range: x >= 0