/refund

POST /refund

Create a refund for an order.

Request:

• id (string) - Required. Idempotency key. Reusing the same id and order with the same payload returns the existing refund result; sending a different payload for the same id and order returns 409 Conflict.

• order (string) - Required. External order ID (e.g. Shopify order ID).

You must provide either a line-item refund or an appeasement refund, but not both.

For a line-item refund, provide at least one of:

• line_items (array) - Optional. The line items to refund. Each element must have:

  • id (string) - Required. External line item ID (e.g. Shopify line item ID).

  • quantity (number) - Required. Must be 1.

• shipping (boolean) - Optional. Refund shipping for the order. Shipping can only be refunded once per order.

For an appeasement refund, provide:

• amount (string) - Required. The amount to refund (must be a decimal string).

• currency (string) - Required. Must match the order's presentment currency.

Body:

• id - The idempotency key from the request

• order - The external order ID from the request

• refunded

  • amount - The refunded amount as a string

  • currency - The refunded amount currency

Errors:

• 400 - INVALID_REFUND_REQUEST: Mixed line-item and appeasement payload; missing or invalid amount/currency for appeasement; or currency does not match the order.

• 400 - INVALID_LINE_ITEMS: The line items array contains invalid entries (e.g. missing id or quantity, or quantity is not 1).

• 400 - CURRENCY_MISMATCH: Appeasement refund currency does not match the order's presentment currency.

• 400 - SHIPPING_ALREADY_REFUNDED: Line-item refund with shipping requested but shipping was already refunded for this order.

• 400 - NOT_ENOUGH_ITEMS_LEFT_TO_REFUND: Requested line-item quantities exceed the remaining refundable quantity.

• 404 - UNKNOWN_ORDER: Order not found or not for this store.

• 404 - UNKNOWN_LINE_ITEMS: One or more line item ids are not on the order.

• 409 - IDEMPOTENT_REQUEST_PAYLOAD_MISMATCH: Same id and order were used with a different payload.

• 500 - REFUND_FAILED: Order has mixed checkout/preorder line items, or the payment refund failed.

• 501 - Orders that span multiple pre-orders are not supported.

Examples:

curl --request POST \
     --url 'https://www.purpledotprice.com/admin/api/v1/refund' \
     --header 'Content-Type: application/json' \
     --header 'X-Purple-Dot-Access-Token: <access_token>' \
     --data '{"id": "refund-001", "order": "gid://shopify/Order/123", "line_items": [{"id": "gid://shopify/LineItem/456", "quantity": 1}], "shipping": false}'

curl --request POST \
     --url 'https://www.purpledotprice.com/admin/api/v1/refund' \
     --header 'Content-Type: application/json' \
     --header 'X-Purple-Dot-Access-Token: <access_token>' \
     --data '{"id": "refund-002", "order": "gid://shopify/Order/123", "amount": "10.00", "currency": "USD"}'

{
  "meta": {
    "result": "success"
  },
  "data": {
    "id": "refund-001",
    "order": "gid://shopify/Order/123",
    "refunded": {
      "amount": "42.00",
      "currency": "USD"
    }
  }
}