---
title: "Refund order items"
method: POST
path: "/orders/{id}/refund"
tags: ["Orders"]
---

# Refund order items

`POST /orders/{id}/refund`

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

## Path parameters

- `id` string, required — Identifier of the order to refund

## Request body

- object
  - `fullRefund` boolean — When true, refunds all remaining refundable items. Mutually exclusive with items.
  - `items` object[] — Specific items and quantities to refund. Required if fullRefund is false.
    - `orderItemId` string, required — Identifier of the order item to refund
    - `quantity` integer, required — Number of units to refund for this item
  - `shippingAmount` integer — Amount of shipping to refund in cents. Cannot exceed remaining refundable shipping.
  - `cancelTickets` boolean — Whether to cancel tickets associated with refunded items. Defaults to true.
  - `notify` boolean — 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
  - `note` string — Free-form notes explaining the refund
  - `idempotencyKey` string — Client-provided key to prevent duplicate refund processing. Recommended for programmatic refunds.
  - `metadata` object — Custom key-value pairs passed through to the payment gateway

## Response `200`

OK

- object
  - `refund` object, required
    - `id` string, required — Unique identifier for this refund
    - `request` object — Request metadata supplied by Sessions or API callers
      - `idempotencyKey` string — Client-provided key to prevent duplicate refund processing
    - `status` 'PENDING' | 'PROCESSING' | 'SUCCEEDED' | 'FAILED', required — Current processing status. PENDING: awaiting gateway confirmation or async processing (e.g., bank transfers). PROCESSING: gateway confirmed, ticket cancellation in progress. SUCCEEDED/FAILED: terminal states.
    - `acceptedAt` string, date-time — Timestamp when the payment gateway accepted the refund
    - `failedAt` string, date-time — Timestamp when the refund failed
    - `failure` object — Failure details when the refund failed
      - `reason` string, required — Gateway or system failure reason
      - `message` string — User-facing failure message when available
    - `price` object, required — Refund amount breakdown
      - `currency` string, required — Currency used for all refund amounts
      - `total` integer, required — Total refund amount in cents, including ticket, shipping, and fee portions.
      - `items` integer, required — Ticket item portion of the refund in cents
      - `shipping` integer, required — Shipping portion of the refund in cents
      - `fees` integer, required — Fee portion of the refund in cents
    - `reason` 'CUSTOMER_REQUEST' | 'DUPLICATE' | 'EVENT_CANCELLED' | 'OTHER', required — Categorized reason for the refund used for analytics
    - `note` string — Free-form notes explaining the refund
    - `items` object[], required — Line items included in this refund with quantities and amounts
      - `orderItemId` string, required — Identifier of the order item being refunded
      - `quantity` integer, required — Number of units refunded for this item
      - `amount` integer, required — Refund amount for this item in cents (base price only, excludes booking fee)
      - `ticketIds` string[], required — Specific ticket identifiers that were refunded (selected via FIFO)
    - `tickets` object, required — Ticket cancellation state for the refund
      - `cancelRequested` boolean, required — Whether ticket cancellation was requested for the refund
      - `cancelled` boolean, required — Whether tickets were cancelled as part of this refund
      - `cancelledCount` integer, required — Number of tickets that were cancelled
    - `gateway` object, required — Gateway refund identifiers
      - `provider` 'FREE' | 'AIRWALLEX' | 'STRIPE', required — Payment gateway used to process the refund
      - `refundId` string — Refund identifier from the payment gateway
      - `idempotencyKey` string — Idempotency key sent to the payment gateway
    - `actor` object, required — Refund initiator
      - `type` 'USER' | 'GATEWAY' | 'SYSTEM', required — Who initiated the refund
      - `userId` string — Identifier of the user who initiated the refund
    - `metadata` object — Custom key-value pairs passed through to the payment gateway
    - `notification` object, required — Refund confirmation notification state
      - `requested` boolean, required — Whether a customer refund confirmation email was requested.
      - `sentAt` string, date-time — Timestamp when the refund confirmation email was sent.
    - `createdAt` string, date-time, required — Timestamp when the refund was created

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `409` — 409
- `412` — 412
- `422` — 422
- `429` — 429
- `500` — 500
- `501` — 501
- `503` — 503

---

[API](https://skmtc.net/session/apis/session-services-api.md) · [All operations](https://skmtc.net/session/apis/session-services-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/session/session-services-api/versions/a1bb6f6c8a2e/schema)