Cancel Order

Order cancellation is in beta. Please report any errors to Violet.

Cancel a complete Order. This action will attempt to cancel the external order in the merchants system for every Bag in the Order. The total amount paid for each Bag will be refunded to the shopper upon successful cancellation.

All Bag's must be in a cancellable state. If any Bag has a status of IN_PROGRESS, REFUNDED, or CANCELED the request will be rejected.

Cancel Order

post

Cancels all bags within an order by forwarding cancellation requests to each merchant's external commerce platform. Each bag must be in an ACCEPTED, SUBMITTED, COMPLETED, or PARTIALLY_REFUNDED state to qualify for cancellation. If all external cancellations succeed, full refunds are automatically processed for each bag. Returns an OrderCancellation object containing the cancellation status, individual bag cancellation records, and any associated refunds. If some bags fail cancellation on the external platform, the response will include error details for those bags.

Path parameters

order_idinteger · int64Required

ID of the order to cancel

Example: 11111

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 to cancel an Order. Only orders that have not yet been fulfilled can be canceled. By default, items will be restocked and the customer will not be notified.

reasonstring · max: 255Optional

Custom message describing the reason for the cancellation.

reason_codestring · enum · max: 255Optional

Code that best represents the reason for the cancellation.

Default: OTHERPossible values:

restock_itemsbooleanOptional

Should the items be restocked. In most cases this should be true since only unfulfilled orders can be cancelled.

Default: true

notify_customerbooleanOptional

Should the customer be notified by the merchants system that a cancellation has occurred.

Default: false

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.

202

accepted

application/json

400

bad request

application/json

404

not found

application/json

500

internal server error

application/json

post

/orders/{order_id}/cancel

HTTPcURLJavaScriptPython

POST /v1/orders/{order_id}/cancel 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: 93

{
  "notify_customer": true,
  "reason_code": "CUSTOMER",
  "reason": "Customer requested cancellation."
}

Cancel order at customer's requestCancel order flagged for fraudulent payment

{
  "order_id": 10000,
  "app_id": 10000,
  "status": "CANCELED",
  "cancelled_bags": [
    {
      "order_id": 10000,
      "bag_id": 11111,
      "merchant_id": 22222,
      "external_order_id": "7438192837181",
      "status": "CANCELED",
      "originated_by": "VIOLET",
      "date_cancelled": "2024-10-24T14:00:39.000+00:00",
      "refund": {
        "id": 99999,
        "order_id": 10000,
        "bag_id": 11111,
        "merchant_id": 22222,
        "app_id": 10000,
        "transaction_id": 44444,
        "amount": 9900,
        "reason": "Order canceled",
        "refund_currency": "USD",
        "status": "COMPLETED",
        "skus": [
          {
            "id": 55555,
            "bag_id": 11111,
            "quantity_refunded": 1,
            "external_id": "41818918453315",
            "order_sku_id": 8014657
          },
          {
            "id": 55556,
            "bag_id": 77777,
            "quantity_refunded": 1,
            "external_id": "41832890171459",
            "order_sku_id": 77777
          }
        ],
        "date_created": "2024-10-24T14:00:35+0000",
        "date_last_modified": "2024-10-24T14:00:35+0000",
        "external_id": "943916482627",
        "errors": []
      }
    }
  ],
  "message": "All external orders were cancelled."
}