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_d6h1b0g510h310b76111m2q4d2") {
    id
    status
    reference
  }
}

mutation CreateOrder {
  createOrder(booking: "booking_y3k372m392v3n7c3e0y30296s3") {
    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_d7h6c7j4h2j6q0a7j3j6x5a7x3") {
    id
    status
    reference
  }
}

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

Order Status ​

Orders have a status field that indicates their current state:

• PENDING: Order created but not yet confirmed
• CONFIRMED: Order confirmed, ticket issuance in progress
• FAILED: Order creation or processing failed
• REFUNDED: All refundable items have been refunded
• UNKNOWN: Order status could not be determined

Check the order status to know when tickets are ready for download.

Complete Flow ​

The complete order flow for wallet/invoice users:

1. Create booking with passenger details and selected offers
2. Create order: pre-books tickets (can take up to 30 seconds)
3. Finalize order: completes purchase, triggers ticket issuance
4. Wait for tickets: usually available within 15 minutes
5. Retrieve tickets: download PDFs or get collection references

For payment gateway users, step 2 is the same; instead of calling finalizeOrder in step 3, you pass the order's id to createPayment and the order is finalized automatically after payment.

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 message. You may need to create a new booking if the original expired.

• Monitor status: Poll order status after finalization to know when tickets are ready. Most tickets are available within 15 minutes.

• Check wallet balance: If using wallet credits, ensure sufficient balance before finalizing orders. Low balance will cause finalization to fail.

Next Steps ​

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