Orders

This page is the single source of truth for the customer order lifecycle in BD Voucher.

End-to-end lifecycle

1. Customer creates an order with one or more items.
2. Payment is initiated (inline or explicit two-step).
3. Gateway callback is re-verified server-side.
4. Fulfillment runs automatically — voucher codes retrieved from preloaded pool or partner API.
5. One consolidated voucher email is sent for the entire order.

---

Create an order

POST /api/v1/orders
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "items": [
    { "variant_id": 22402, "quantity": 2, "fulfillment_input": { "player_id": "123456789" } },
    { "variant_id": 22405, "quantity": 1 }
  ],
  "payment_method": "paystation",
  "recipient_email": "gift-recipient@example.com"
}

• payment_method must be one of sslcommerz, bkash, paystation, dcb, nagad.
• init_payment defaults to true, so POST /orders usually returns an initialized payment session.
• Set "init_payment": false if you prefer explicit payment initiation later.
• discount_code (optional) — a promo code applied to the order. Validate it first with GET /api/v1/discounts/validate to preview the deduction. See Discount Codes.

---

Two payment patterns

Pattern A: Inline (recommended)

Use default init_payment = true in POST /api/v1/orders and redirect to data.payment.paymentGatewayUrl.

Pattern B: Explicit two-step

1. Create order with "init_payment": false
2. Initiate payment later:

POST /api/v1/payments/initiate/:orderId
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "amount": 500,
  "currency": "BDT",
  "method": "bkash",
  "description": "Order #12345"
}

See Payments for gateway-specific callback and verification details.

---

Retrieve order details

List my orders

GET /api/v1/orders?page=1&limit=10
Authorization: Bearer $TOKEN

Get one order

GET /api/v1/orders/:id
Authorization: Bearer $TOKEN

You can pass the numeric id or the 8-digit order_number.

---

Order response fields

Field	Type	Description
id	integer	Internal numeric order ID.
order_number	string	8-digit human-readable order number (safe to display to customers).
status	string	Machine-readable order state (see Status semantics below).
status_label	string	Compact UI label suitable for badges.
status_message	string	Customer-facing prose safe to render in a confirmation/status screen.
total_amount	number	Total charged amount in BDT after any discount.
currency	string	Always "BDT".
discount_code	string | null	The promo code applied to this order. null if none was used.
discount_amount	number | null	BDT amount deducted by the discount code. null if none was used.
voucher_codes	string[]	Flat list of all codes across all items and all quantities — matches the email the customer received.
dispatched_email	string | null	The email address the consolidated voucher email was sent to.
email_sent_at	ISO 8601 | null	Timestamp of the latest successful voucher-email dispatch.
items[]	array	Per-item details including variant_id, quantity, fulfilled, voucher_codes[], voucher.
payments[]	array	Associated payment records with status, transaction_id, and payment_method.
created_at	ISO 8601	When the order was placed.
updated_at	ISO 8601	Last modification timestamp.

Item-level fields

Field	Type	Description
items[].variant_id	integer	The purchased product variant.
items[].quantity	integer	Number of units purchased.
items[].unit_price	number	Price per unit at time of purchase.
items[].fulfilled	boolean	true once the voucher code has been saved and the delivery email sent successfully.
items[].fulfilled_at	ISO 8601 | null	When fulfillment completed.
items[].fulfillment_status	string | null	Fine-grained fulfillment state: SUCCEEDED, DISPATCH_FAILED, PARTNER_FAILED.
items[].voucher_codes	string[]	All codes for this item (one per unit purchased).
items[].voucher	object | null	Primary voucher record with code, status, serial_number, expires_at.

---

Status semantics

Status	Meaning
INITIATED	Order created, payment not yet confirmed.
PENDING	Payment succeeded, voucher fulfillment in progress.
CARRIER_AUTHORIZED	Payment authorized by carrier (DCB), final confirmation pending.
SUCCEEDED	All items fulfilled and vouchers delivered.
NEEDS_ATTENTION	Customer was charged but delivery failed — operator action required.
FAILED	Payment failed or was declined.
CANCELLED	Customer or gateway cancelled before payment.

Note

NEEDS_ATTENTION is a recovery status for the operations team. The customer was charged; their voucher just hasn’t arrived yet. Admins can retry partner fulfillment or enter codes manually — see Admin fulfillment recovery. The customer’s order view should show a “processing” message, not an error.

---

Multi-item and multi-quantity behavior

• Orders can contain multiple products and quantities in one checkout.
• Fulfillment produces one code per purchased unit (a quantity: 3 item yields 3 voucher codes).
• The customer receives one consolidated email per order, with product and variant labels for each code.
• voucher_codes at order level is the flat union of all per-item codes — the same set the customer email contains.

---

Related references

• Checkout flow — full step-by-step integration guide.
• Discount Codes — promo code validation and application.
• Payments — gateway specifics and callback verification.
• Voucher codes — field reference for code retrieval.
• Admin fulfillment recovery — NEEDS_ATTENTION resolution.
• Error handling — retry strategy and duplicate prevention.