Docs

Managing Refunds ​

Refunds allow you to return purchased tickets and rail passes to the original payment method. The API provides a straightforward flow for checking what can be refunded, executing the refund, and tracking its status.

Refund Flow ​

The typical refund flow consists of three steps:

  1. Query refundable items: Use refundableItems to see what can be refunded and for how much
  2. Execute the refund: Use refundItems mutation to initiate the refund for selected items
  3. Track refund status: Use refunds to monitor the state of requested refunds

Getting Refundable Items ​

Before initiating a refund, you need to check which items on an order are eligible for refunding. The refundableItems query returns a list of items that can be refunded, along with the refund amount for each.

Wait for ticket issuance

Before requesting refundable items, ensure that tickets have been fully issued. Attempting to query refundable items before ticket issuance is complete may result in incomplete or inaccurate results. Check the order status and wait for all resources (tickets or pass codes) to be available before proceeding with refund operations.

Example: Query refundable items
graphql
query RefundableItems {
  refundableItems(orderId: "order_7275c515m1n6n2w1y50355c626") {
    id
    description
    amount {
      amount
      currency
    }
    ... on RefundableOfferItem {
      refundParts {
        __typename
        price {
          amount
          currency
        }
        segments {
          departureAt
          identifier
        }
      }
    }
    ... on RefundablePassItem {
      passItem {
        code
        product
        class
      }
    }
  }
}
query RefundableItems {
  refundableItems(orderId: "order_7275c515m1n6n2w1y50355c626") {
    id
    description
    amount {
      amount
      currency
    }
    ... on RefundableOfferItem {
      refundParts {
        __typename
        price {
          amount
          currency
        }
        segments {
          departureAt
          identifier
        }
      }
    }
    ... on RefundablePassItem {
      passItem {
        code
        product
        class
      }
    }
  }
}

Executing a Refund ​

Once you have identified the items to refund, use the refundItems mutation to execute the refund. You can refund one or more items in a single request.

Example: Execute a refund
graphql
mutation RefundItems {
  refundItems(
    orderId: "order_7275c515m1n6n2w1y50355c626"
    refundableItemIds: ["rfi_458237t546t741a664n7r05790"]
  ) {
    id
    state
    createdAt
    items {
      id
      state
      description
      amount {
        amount
        currency
      }
    }
  }
}
mutation RefundItems {
  refundItems(
    orderId: "order_7275c515m1n6n2w1y50355c626"
    refundableItemIds: ["rfi_458237t546t741a664n7r05790"]
  ) {
    id
    state
    createdAt
    items {
      id
      state
      description
      amount {
        amount
        currency
      }
    }
  }
}

The mutation returns a Refund object containing the state of the refund and the individual items being refunded. Each item has its own state which may differ from the overall refund state.

Tracking Refund Status ​

To check the status of previously requested refunds, use the refunds query. This returns all refunds associated with an order.

Example: Get refund status
graphql
query Refunds {
  refunds(orderId: "order_7275c515m1n6n2w1y50355c626") {
    id
    state
    createdAt
    items {
      id
      state
      description
      amount {
        amount
        currency
      }
      ... on RefundOfferItem {
        refundParts {
          __typename
          price {
            amount
            currency
          }
          segments {
            departureAt
            identifier
          }
        }
      }
      ... on RefundPassItem {
        passItem {
          product
        }
      }
    }
  }
}
query Refunds {
  refunds(orderId: "order_7275c515m1n6n2w1y50355c626") {
    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 ​

For a ready-made user interface, consider using the Refund Manager Embed. The embed provides a complete interface for managing refunds on an order, including refund history and the ability to select and process new refunds, all without writing any custom UI code.

Because the embed runs on a public page, publicApiKey takes an access token minted on your server for that one order — not your API key.

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