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 ​

There are two ways to create orders, depending on your payment method:

Wallet Credits or Invoice Billing ​

If you're using wallet credits or invoice billing, create orders manually using createOrder. This is the standard flow for most API integrations.

Creating an order pre-books the tickets with train operators. This can take up to 30 seconds depending on the operator, so use WebSocket connections to avoid timeouts.

mutation CreateOrder {
  createOrder(booking: "ea4efb12-0199-44bd-8012-1b4444875a02") {
    id
    status
    reference
  }
}

mutation CreateOrder {
  createOrder(booking: "69fb7d3c-2d63-4c36-a19a-d9f900384b38") {
    id
    status
    reference
  }
}

Payment Gateway ​

If you're using the payment gateway, orders are created automatically when you call createPayment. You don't need to call createOrder separately; the hosted payment flow handles it.

See 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 created via the payment gateway are automatically finalized after successful payment. You don't need to call finalizeOrder; the hosted payment flow handles it.

mutation FinalizeOrder {
  finalizeOrder(order: "8ac0e0ca-0e4b-42f2-844a-caca06eac8bb") {
    id
    status
    reference
  }
}

mutation FinalizeOrder {
  finalizeOrder(order: "cbdd3c8d-94b6-4bd8-a1fd-fec569e5f9a9") {
    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, steps 2-3 happen 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.