Orders

This is the core of the integration — converting brand selections into gift card vouchers. This page covers the order lifecycle from placement through all response states.

The Order Object

Field	Type	Description
`id`	string	Unique identifier for the order
`referenceId`	string	Your idempotency key
`status`	string	`SUCCESS`, `FAILED`, `PROCESSING`, `CANCELLED`, `REVERSED`
`vouchers`	Voucher[] \| null	Voucher list (empty while processing)
`failureReason`	string \| null	Populated when status is `FAILED`

The Voucher Object

Field	Type	Description
`id`	string	Unique voucher id
`cardType`	string	`CARD_NUMBER_SECURED`, `PIN_NO_SECURED`, `CARD_AND_PIN_NO_SECURED`
`cardPin`	string \| null	PIN
`cardNumber`	string \| null	Card number
`validTill`	date \| null	Expiry `YYYY-MM-DD`
`amount`	number	Voucher amount

Place an Order

POST /v1/partners/orders

SUCCESS — vouchers present in vouchers[]
PROCESSING — generation in progress; poll or wait for webhook (vouchers[] empty)
FAILED — see failureReason; retry with a new referenceId

Request Body

Field	Type	Required	Description
`productId`	string	Required	Brand/product ID from catalog
`referenceId`	string	Required	Idempotency key (max 40 chars, globally unique)
`amount`	number	Required	Must equal sum of denomination × quantity
`denominationDetails[]`	array	Required	`{ denomination, quantity }` pairs
`customerDetails`	object	Conditional	Required for B2C; nullable for B2B
`deliveryDetails`	object	Optional	When RewardOS delivers vouchers for you

customerDetails: name, phoneNumber, email
deliveryDetails: recipientName, recipientType (SELF|OTHER), recipientPhoneNumber, senderName, wishMessage

Example Request

curl -X POST "https://api.staging.rewardos.in/v1/partners/orders" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "X-REQUEST-ID: 239774a8-f59c-496c-bb52-ceb683d60af3" \
  -d '{
    "productId": "01GMAW822RPDJ5C50XK24QC2C4",
    "referenceId": "ORD-2026-001",
    "amount": 1000,
    "denominationDetails": [
      { "denomination": 500, "quantity": 2 }
    ],
    "customerDetails": {
      "name": "John Doe",
      "phoneNumber": "9876543212",
      "email": "john@example.com"
    }
  }'

Example SUCCESS Response

{
  "id": "01KJA7HBZAPKDN0VVXTVN6R41H",
  "referenceId": "ORD-2026-001",
  "status": "SUCCESS",
  "vouchers": [
    {
      "id": "voucher_id",
      "cardType": "CARD_AND_PIN_NO_SECURED",
      "cardPin": "112233",
      "cardNumber": "2359481287412",
      "validTill": "2027-02-25",
      "amount": 500
    }
  ],
  "failureReason": null
}

Order Response States

Status	Meaning	Your Action
`SUCCESS`	Vouchers ready	Display vouchers
`PROCESSING`	Still generating	Webhook or poll
`FAILED`	Generation failed	Show error; new referenceId on retry
`CANCELLED`	Cancelled by client	Confirm to user
`REVERSED`	Reversed by client	Process refund if applicable

Display by cardType

CARD_AND_PIN_NO_SECURED — show both cardNumber and cardPin
CARD_NUMBER_SECURED — show cardNumber only
PIN_NO_SECURED — show cardPin only

Handling FAILED

HTTP status may still be 200; inspect the body status field.

Read failureReason
Do not reuse referenceId
Re-check brand via Get Brand before retrying
Log RewardOS id, your referenceId, and the reason

Reason	Resolution
Brand not available	Brand inactive / no providers
Voucher generation failed	Provider-side (`E200`); retry after 1–2 min
Insufficient balance	Top up wallet (`E300`)
Denomination not available	Refresh catalog (`E150`)

Handling PROCESSING

Start polling Get Order ~1 minute after placement
Cap at ~5 attempts at reasonable intervals
Prefer the Order Reached Terminal State webhook
If still PROCESSING after 15 minutes, mark failed locally and contact support

Timeout on Place Order

Call GET /v1/partners/orders/by-reference/:referenceId
404 → order was not created; safe to retry with same referenceId
Otherwise process the returned status

Get an Order

GET /v1/partners/orders/:orderId
or
GET /v1/partners/orders/by-reference/:referenceId

Returns the Order object.

Get a Voucher

GET /v1/partners/orders/vouchers/:id

Returns the Voucher object.