Refunds
Tickets and rail passes can be refunded to the payment method they were bought with. You check what can be refunded, request the refund, and then follow its status.
Refund flow
A refund takes three steps:
- Get the refundable items: Use
refundableItemsto see what can be refunded, and for how much. - Request the refund: Use the
refundItemsmutation to refund the items you choose. - Follow the refund: Use
refundsto see the state of the refunds you have requested.
Getting refundable items
The refundableItems query returns the items of an order that can be refunded, with the refund amount for each.
Example: Query refundable items
query RefundableItems {
refundableItems(orderId: "order_r352t53434n241d175b4t69133") {
id
description
amount {
amount
currency
}
... on RefundableOfferItem {
refundParts {
__typename
price {
amount
currency
}
segments {
departureAt
identifier
}
}
}
... on RefundablePassItem {
passItem {
code
product
class
}
}
}
}Executing a refund
Pass the ids of the items you want to refund to the refundItems mutation. You can refund several items in one request.
Example: Execute a refund
mutation RefundItems {
refundItems(
orderId: "order_r352t53434n241d175b4t69133"
refundableItemIds: ["rfi_q5s267a7a0w343d3t5a3k777z7"]
) {
id
state
createdAt
items {
id
state
description
amount {
amount
currency
}
}
}
}The mutation returns a Refund with its state and the items being refunded. Each item has its own state, which can differ from the state of the refund as a whole.
A refund and each of its items is in one of three states:
PENDING: The refund has been requested and isn't settled yet. Read it again withrefundsuntil it changes.SUCCEEDED: The refund is done and the money is on its way back to the original payment method.ERROR: The refund failed, and what it covers has not been refunded.
A refund that can't be started at all fails with an error instead. See Refund errors. Reading and starting refunds needs the orders:read scope.
Tracking refund status
The refunds query returns all the refunds of an order, with their states.
Example: Get refund status
query Refunds {
refunds(orderId: "order_r352t53434n241d175b4t69133") {
id
state
createdAt
items {
id
state
description
amount {
amount
currency
}
... on RefundOfferItem {
refundParts {
__typename
price {
amount
currency
}
segments {
departureAt
identifier
}
}
}
... on RefundPassItem {
passItem {
product
}
}
}
}
}Using the Refund Manager embed
If you don't want to build the interface yourself, use the Refund Manager embed. It shows an order's refund history, and lets the user select items and refund them.
The embed runs on a public page, so its publicApiKey takes an access token minted on your server for that one order, not your API key. Mint it with capabilities: [WRITE]. The default, READ, can show the refunds but not start one.
<aa-refund-manager-modal
open
publicApiKey="aat_your-access-token-here"
order="order_r352t53434n241d175b4t69133"></aa-refund-manager-modal>