v11

latestOpenAPI 3.1.12026-08-03174162.0 MB

Orders

Refund order items

Process a refund for order items. Supports full or partial refunds with optional ticket cancellation.

post/orders/{id}/refund

Path parameters

idstring required

Identifier of the order to refund

Example:ord_01jps5cgsfgve5b5g2666kyryh

Request body

fullRefundboolean

When true, refunds all remaining refundable items. Mutually exclusive with items.

shippingAmountinteger

Amount of shipping to refund in cents. Cannot exceed remaining refundable shipping.

cancelTicketsboolean

Whether to cancel tickets associated with refunded items. Defaults to true.

notifyboolean

Whether to send a refund confirmation email to the customer. Defaults to true.

reason'CUSTOMER_REQUEST' | 'DUPLICATE' | 'EVENT_CANCELLED' | 'OTHER' required

Categorized reason for the refund

notestring

Free-form notes explaining the refund

idempotencyKeystring

Client-provided key to prevent duplicate refund processing. Recommended for programmatic refunds.

metadataobject

Custom key-value pairs passed through to the payment gateway

Example request

{
  "items": [
    {
      "orderItemId": "itm_01jps5cgsfwyxj0516571eaf17",
      "quantity": 2
    }
  ],
  "shippingAmount": 500,
  "cancelTickets": true,
  "notify": true,
  "reason": "CUSTOMER_REQUEST",
  "note": "Customer requested refund due to schedule conflict",
  "idempotencyKey": "refund_12345_customer_request",
  "metadata": {
    "supportTicket": "#12345"
  }
}

Response

Example response

{
  "refund": {
    "id": "rfd_01jps5cgsfgve5b5g2666kyryh",
    "request": {
      "idempotencyKey": "refund_12345_customer_request"
    },
    "status": "PENDING",
    "acceptedAt": "2026-08-03T06:13:52.219Z",
    "failedAt": "2026-08-03T06:13:52.219Z",
    "failure": {
      "reason": "Insufficient funds for refund",
      "message": "The refund could not be processed."
    },
    "price": {
      "currency": "AUD",
      "total": 1200,
      "items": 1200
    },
    "reason": "CUSTOMER_REQUEST",
    "note": "Customer requested refund due to schedule conflict",
    "items": [
      {
        "orderItemId": "itm_01jps5cgsfwyxj0516571eaf17",
        "quantity": 2,
        "amount": 1200,
        "ticketIds": [
          "tkt_01jps5cgsg0s32w2pr73vbccde"
        ]
      }
    ],
    "tickets": {
      "cancelRequested": true,
      "cancelled": true,
      "cancelledCount": 2
    },
    "gateway": {
      "provider": "STRIPE",
      "refundId": "re_1234567890abcdef",
      "idempotencyKey": "rfd_01jps5cgsfgve5b5g2666kyryh"
    },
    "actor": {
      "type": "USER",
      "userId": "usr_01jps5cgsd4tzjghtnt45qnhn0"
    },
    "metadata": {
      "supportTicket": "#12345"
    },
    "notification": {
      "requested": true,
      "sentAt": "2026-08-03T06:13:52.219Z"
    },
    "createdAt": "2026-08-03T06:13:52.219Z"
  }
}