Orders ​

Orders represent confirmed purchases. They hold tickets and passes for a booking, and once finalized, trigger automatic ticket issuance.

Understanding Orders ​

The order lifecycle has two stages:

1. Created: The order is created and tickets are pre-booked with train operators. At this point, tickets are reserved but not yet issued.

2. Finalized: The order is finalized, payment is processed (if applicable), and ticket issuance begins automatically.

Only finalized orders result in issued tickets. You can create an order and finalize it later, but tickets won't be issued until finalization.

Creating Orders ​

Every payment method starts the same way: create the order with createOrder. This pre-books the tickets with train operators and can take up to 30 seconds depending on the operator, so use WebSocket connections to avoid timeouts.

mutation CreateOrder {
  createOrder(booking: "booking_j4g1p2e5c7m1f4k4t3q2c004s1") {
    id
    status
    reference
  }
}

mutation CreateOrder {
  createOrder(booking: "booking_72s370w5f6322627g044m6a4h0") {
    id
    status
    reference
  }
}

How you finalize the order is what differs between payment methods. See Finalizing Orders below, or Payments for details on the payment gateway flow.

Finalizing Orders ​

After creating an order, you must finalize it to complete the purchase and trigger ticket issuance. How you do this depends on your payment method:

Wallet Credits ​

When you finalize an order with wallet credits, the order total is deducted from your wallet balance automatically. If you don't have sufficient credits, finalization fails.

Finalize immediately after creating the order, or store the order ID and finalize later (within the booking expiration window).

Invoice Billing ​

For invoice billing, finalization works the same way. You call finalizeOrder to complete the purchase. The order is tracked for monthly invoicing instead of immediate payment.

Payment Gateway ​

Orders paid through the payment gateway are finalized automatically after successful payment. Pass the order's id to createPayment as orderId; you don't call finalizeOrder yourself.

mutation FinalizeOrder {
  finalizeOrder(order: "order_m2t41732e27517615605c79007") {
    id
    status
    reference
  }
}

mutation FinalizeOrder {
  finalizeOrder(order: "order_g266s700h3y596a020k492v311") {
    id
    status
    reference
  }
}

Order Status ​

Orders have a status field that indicates their current state:

• PENDING: Order created but not yet finalized or paid
• CONFIRMED: Purchase complete. Tickets are fetched from the operator afterward, so they may not be available yet
• FAILED: Order creation or processing failed
• REFUNDED: All refundable items have been refunded
• PARTIALLY_REFUNDED: Some refundable items have been refunded
• REFUND_FAILED: The refund attempt failed
• VOIDED: The order has been voided
• UNKNOWN: Order status could not be determined

CONFIRMED means the purchase is complete, not that the tickets are ready. To know when they are, poll the order with node until each item's resources are present, or for rail passes until the item's code is set. See Retrieving Tickets and Retrieving Pass Codes.

The Full Flow ​

For where orders fit in the whole flow from search to tickets, for every payment method, see Booking Flows.

Best Practices ​

• Use WebSocket: Order creation can be slow. Use WebSocket connections to avoid timeouts and see progress updates.

• Handle failures: If order creation or finalization fails, check the error code. finalizeOrder can fail with NOT_ENOUGH_FUNDS, PAYMENT_METHOD_NOT_ALLOWED, WALLET_NOT_AVAILABLE, RATE_LIMITED, FINALIZE_FAILED or one of the finalization errors from operators. You may need to create a new booking if the original expired.

• Queue finalizations: finalizeOrder is rate limited per sales agent (20 orders per minute by default). A rate-limited order isn't booked or charged, so retry it later.

• Poll for tickets: After finalization, poll the order until its items' resources appear. The order status alone doesn't tell you the tickets are ready. Most tickets are available within 15 minutes.

• Keep your wallet topped up: If using wallet credits, top up and check your balance in the Dashboard; the API can't do either. When the balance is too low, finalizeOrder fails with NOT_ENOUGH_FUNDS. Nothing is booked or charged, so you can top up and finalize the same order again.

Next Steps ​

After finalizing an order, tickets are automatically issued. See Booking Tickets for details on retrieving tickets from finalized orders.