Skip to content
Docs
Open Backstage
Operation

Create a refund request

POST/refund-requests
Raises a refund or exchange request against an order on behalf of the customer.

Headers

Idempotency-KeystringOptional
Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.

Body

orderId*string
type*"refund" | "exchange"
reasonstring
refundTo"original" | "account_credit"Where the refund should go: back to how the order was paid (`original`, the default), or into the customer's account credit. Staff may change it before the request is processed (PATCH /refund-requests/{requestId}). Account credit needs a customer on the order (STORED_VALUE_CUSTOMER_REQUIRED when the request is made otherwise).

Returns

Refund request created successfully

Errors

400
Bad Request - Invalid input
401
Unauthorized - Authentication required
403
Forbidden - Insufficient permissions
404
Not Found - Resource not found
500
Internal Server Error

Every error names its code and links to it. All error codes

curl -X POST "https://api.ticketlayer.com/v1/refund-requests" \  -H "Authorization: Bearer tlak_..." \  -H "X-Ticketlayer-Org: your-org-slug" \  -H "Content-Type: application/json" \  -d '{    "orderId": "string",    "type": "refund",    "reason": "string",    "refundTo": "original"  }'
Response 201
{
  "request": {
    "id": "rfr_abc123",
    "organisationId": "org_abc123",
    "orderId": "ord_abc123",
    "accountId": "acc_abc123",
    "type": "refund",
    "status": "pending",
    "reason": "Customer cannot attend",
    "refundTo": "original",
    "notes": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Try it in test mode

Body
Where the refund should go: back to how the order was paid (`original`, the default), or into the customer's account credit. Staff may change it before the request is processed (PATCH /refund-requests/{requestId}). Account credit needs a customer on the order (STORED_VALUE_CUSTOMER_REQUIRED when the request is made otherwise).