Orders Overview
Create, track, and manage digital product orders with real-time status and voucher delivery
Orders Overview
The Orders API enables complete order lifecycle management for digital products, from creation through fulfillment with secure voucher delivery.
Order Ecosystem
Order Creation Initiate purchases for gift cards, mobile top-ups, and digital services with multi-currency support and real-time inventory validation.
Order Tracking Monitor order status from placement through delivery with detailed transaction history and status updates.
Voucher Delivery Secure delivery of digital vouchers with encrypted codes, PINs, and redemption instructions upon successful order completion.
API Documentation
Create Order API
Submit new orders for digital products with customer information and payment processing.
Key Operations:
- Submit order with product selection
- Provide customer information
- Specify payment method
- Receive order confirmation
→ Create Order API Documentation
List Orders API
Search and filter order history with comprehensive pagination and filtering options.
Key Operations:
- View order history with pagination
- Filter by status, product, or date
- Access order summaries
- Monitor order pipeline
→ List Orders API Documentation
Get Order Details API
Retrieve complete order information including decrypted voucher codes for delivered orders.
Key Operations:
- Get detailed order information
- Access decrypted voucher codes
- View delivery status
- Track fulfillment progress
→ Get Order Details API Documentation
Quick Start
- Authenticate - Get your access token via the Authentication API
- Browse Products - Use the Products API to find products
- Calculate Pricing - Use the Charges API to get pricing
- Create Order - Submit order using the Create Order API
- Track Status - Monitor orders with List Orders API
- Deliver Vouchers - Retrieve codes via Get Order Details API
Order Status Flow
PLACED
Order has been accepted by the API and recorded. No fulfillment has started yet.
PENDING
Order is queued for fulfillment. Inventory lookup is in progress or the order is awaiting admin action (for multi-vendor or out-of-stock cases). No vouchers yet.
DELIVERED
Order has been fulfilled. Voucher codes, PINs, and redemption URLs are available via Get Order Details.
PARTIALLY_DELIVERED
Some order items are delivered; others are still pending or failed. Retrieve the per-item status from Get Order Details.
CANCELLED / FAILED
Order could not be fulfilled — cancellation, vendor failure, or validation failure. No vouchers were generated.
Enum Conventions
Case handling. All enum values in this reference are the canonical UPPERCASE form returned by the API. The API accepts input values in any case (instant, Instant, INSTANT all parse the same), and always responds with the canonical UPPERCASE form. Write integrations against UPPERCASE and you will be forward-compatible.
Exposure column. Each enum table below shows whether the value appears in client-facing /api/v1/* responses or is internal only (used by admin/vendor backchannels). Do not write client logic that depends on enum values marked Internal — they may change without notice.
Order Status Values
Primary Status
| Status | Description | Vouchers Available | Exposure |
|---|---|---|---|
PLACED | Order accepted, not yet processed | No | Public |
PENDING | Queued, awaiting inventory or admin action | No | Public |
DELIVERED | Order completed successfully | Yes | Public |
PARTIALLY_DELIVERED | Some items delivered, others pending/failed | Partial | Public |
CANCELLED | Order was cancelled | No | Public |
FAILED | Order processing failed | No | Public |
Sub Status
Orders carry a detailed sub-status for granular lifecycle tracking. New sub-status values may be added over time — treat unknown values as informational, not fatal.
| Sub Status | Description |
|---|---|
INITIAL | Initial state after order creation |
PROCESSING | Order is being processed |
PARTIAL | Partial completion of order items |
COMPLETED | Order fully completed |
VENDOR_ORDER_PENDING | Waiting for vendor order creation |
VENDOR_ORDER_CREATED | Vendor order has been created |
VENDOR_ORDER_FAILED | Vendor rejected or failed the order |
VENDOR_VOUCHER_FETCHED | Vouchers fetched from vendor |
INVENTORY_FULFILLED | Order fulfilled from inventory cache (no vendor call) |
PENDING_REPROCESS | Order queued for retry after a transient failure |
REPROCESS_EXPIRED | Retry window expired without success |
GV_LINK_PENDING | Gift voucher link creation pending |
GV_LINK_CLAIMED | Gift voucher link has been claimed |
GV_LINK_UNCLAIMED | Gift voucher link not yet claimed |
BULK_LIMIT_EXCEEDED | Bulk order limit exceeded |
REFUNDED | Order has been refunded |
NOT_REFUNDED | Failed order not yet refunded |
RECONCILED | Order reconciled with vendor |
Product Attribute Enums
These enums describe products, not orders — you will encounter them in Products API responses and order line items.
Delivery Timing — delivery_time
Indicates how quickly a voucher is expected to be available after the order is placed. This is the field you should use to decide whether to poll for voucher codes or wait on a webhook. It is computed live at response time based on current inventory availability, so a product's delivery_time can change between requests.
| Value | Description | Integration hint | Exposure |
|---|---|---|---|
INSTANT | Inventory is ready; order is expected to fulfill synchronously | Expect DELIVERED status on first GET /orders/:id, or immediately on the webhook | Public |
DELAYED | No inventory ready; order will go through vendor processing | Subscribe to the order.delivered webhook, or poll every 30–60 s | Public |
Legacy note. Older documentation referred to these values as REALTIME / DELAYED. The canonical values are now INSTANT / DELAYED. The API accepts both on input; responses use the canonical form. Historic pre-normalization responses may have emitted lowercase instant / delayed — treat enum comparisons case-insensitively in your client.
Delivery Format — delivery_type
The format in which a voucher is delivered. Reflects the product's underlying medium and is carried on product responses for display/routing logic.
| Value | Description | Exposure |
|---|---|---|
CODE_WITH_PIN | Voucher consists of a card number plus a PIN | Public |
URL | Voucher is a redemption URL (typically a gift-card microsite) | Public |
Heads up. The field is historically named delivery_type even though it describes the delivery format (the delivery timing lives in delivery_time). This naming is preserved for backwards compatibility.
Classification
Indicates where a voucher can be redeemed. Used in product search and catalog UIs, but not returned on every product response — check the specific endpoint's response schema.
| Value | Description | Exposure |
|---|---|---|
OPEN_LOOP | Can be used at multiple merchants (e.g., Visa gift card) | Internal |
CLOSED_LOOP | Can only be used at a specific merchant | Internal |
SEMI_OPEN | Restricted to a merchant group or category | Internal |
SEMI_CLOSE | Restricted but broader than closed loop | Internal |
Link Type
For products that deliver vouchers via a URL, indicates the access-control model of that URL.
| Value | Description | Exposure |
|---|---|---|
PUBLIC | Unauthenticated URL — anyone with the link can redeem | Internal |
PROTECTED | URL requires a password or additional authentication to redeem | Internal |
Fulfillment & Inventory Enums
Inventory Status
The state of a single voucher unit in Starship's inventory cache.
| Status | Description | Exposure |
|---|---|---|
AVAILABLE | In the pool, eligible for allocation | Internal |
ALLOCATED | Reserved against an order, not yet delivered | Internal |
DELIVERED | Released to the ordering client | Internal |
COMPLETED | Lifecycle closed (delivered + reconciled) | Internal |
BLOCKED | Temporarily ineligible (e.g., expired, flagged) | Internal |
REVOKED | Permanently invalid (e.g., vendor recall) | Internal |
Recharge Status
For mobile-topup and utility-recharge products, the fulfillment status of the recharge itself (separate from order status).
| Status | Description | Exposure |
|---|---|---|
PENDING | Recharge request queued | Public |
DELIVERED | Recharge submitted to operator | Public |
RECHARGED | Operator confirmed the balance was credited | Public |
FAILED | Recharge was rejected by the operator | Public |
CANCELLED | Recharge cancelled before submission | Public |
Security Features
Encryption
All sensitive voucher data is encrypted at rest using AES-256 encryption:
- Card/voucher numbers
- PIN codes
- Reference numbers
- Redemption URLs
Access Control
- JWT authentication required for all endpoints
- Client-specific order visibility
- Audit logging for all order operations
Data Protection
- Vouchers only decrypted when order is delivered
- Secure transmission over HTTPS
- PCI compliance for payment card data
Common Integration Patterns
Validate Product Availability
Before creating an order, verify the product is available for the desired denomination and quantity using the Product Availability API. This prevents order failures due to availability issues.
Calculate Total Cost
Use the Charges API to calculate the exact cost including discounts, fees, and taxes. Display this transparent pricing to customers before order creation.
Create Order
Submit the order with customer details and payment information. The order will be validated and processed asynchronously. Store the returned order ID for tracking.
Poll for Completion
Check the order status periodically using the Get Order Details endpoint. When status changes to "delivered", voucher codes become available.
Retrieve Vouchers
Once delivered, fetch the complete order details to access decrypted voucher codes, PINs, and redemption instructions. Deliver these securely to your customer.
Best Practices
- Idempotency - Include unique reference codes to prevent duplicate orders
- Error Handling - Implement robust retry logic for transient failures
- Status Monitoring - Poll order status at reasonable intervals (e.g., every 30 seconds)
- Secure Storage - Never log or store decrypted voucher codes
- Customer Communication - Send status updates via email/SMS during processing
Next Steps
- Create Orders - Submit new orders
- List Orders - View order history
- Get Order Details - Retrieve vouchers
- Authentication - Secure API access