Switch to dark mode

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:

  1. Get the refundable items: Use refundableItems to see what can be refunded, and for how much.
  2. Request the refund: Use the refundItems mutation to refund the items you choose.
  3. Follow the refund: Use refunds to 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.

Wait for ticket issuance

Only ask for refundable items when all the order's tickets or pass codes have been issued. Before that, the result can be incomplete or wrong.

Example: Query refundable items

graphql
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

graphql
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 with refunds until 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

graphql
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.

html
<aa-refund-manager-modal
  open
  publicApiKey="aat_your-access-token-here"
  order="order_r352t53434n241d175b4t69133"></aa-refund-manager-modal>