/refund

POST /refund

Create a refund for an order.

Refunds money to the shopper against the underlying Purple Dot preorder payments. You must provide either a line-item refund (only supported for Shopify stores) or an custom amount refund, but not both.

Request Body:

• id (string) - Required. Idempotency key.

  • Must be unique for each distinct refund. This could be a refund document number, return ID, or support case/ticket ID tied to that specific refund.

  • Reuse the same id, order, and payload when retrying after a timeout or network error. A successful prior attempt returns the same result and will not refund the shopper twice. Sending a different payload for the same id and order returns 409 Conflict.

  • Use a new id for each separate refund, even on the same order.

  • Do not generate a new random ID on every HTTP retry.

• order (string) - Required. External order ID to refund.

  • On Shopify stores, use the Shopify order ID.

  • For other e-commerce platforms, use the Purple Dot fulfillment order UUID. Look up the fulfillment order via GET /fulfillment-orders.

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.

Note: line-item refunds are currently only supported for Shopify stores.

For a custom amount refund, provide:

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

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

Response Data:

• 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"
    }
  }
}