Place Voucher Order

Place a new order for a standard product (e.g., gift cards, vouchers) using a unique external reference and product variant.

Endpoint

POST /v1/orders/b2b/direct-checkout

Headers

Header	Type	Description	Required
x-client-id	String	Your clientID	✅ Yes
x-client-secret	String	Your clientSecret	✅ Yes
Content-Type	String	Must be application/json	✅ Yes

Request Body

Use this format when purchasing standard products (e.g., gift cards, vouchers).

Field	Type	Description	Required
dpID	String	Your delivery partner ID (same as clientID)	✅ Yes
productID	String	Product identifier the variant belongs to	✅ Yes
variantID	String	Product variant identifier	✅ Yes
denomination	Object	Face value of the variant. See below.	✅ Yes
externalRefID	String	Unique reference ID provided by client	❌ No

denomination

Field	Type	Description	Required
amount	Number	Face value amount, exactly as returned by the product catalog API	✅ Yes
currency	String	Currency of that amount, exactly as returned by the catalog API	✅ Yes

:::warning Unique External Reference The externalRefID must be unique for each order. This is your reference for tracking the order in your system. :::

:::danger Product and denomination are safety checks

productID and denomination are cross-checked against variantID before the order is placed. If they do not describe the same variant, the order is rejected and nothing is charged — this is what stops a misplaced variantID from fulfilling a voucher of the wrong brand or the wrong value.

Copy both values straight from the product catalog response (Get Product by ID):

• productID — the product the variant is listed under.
• denomination — the variant's denomination object, sent back verbatim (amount and currency).

The denomination is compared in the variant's own currency and is never FX-converted. Sending the right amount in your wallet currency instead of the product currency is a mismatch and will be rejected.

:::

Example Request

curl --location 'https://stage-platform-exlr8.exlr8now.com/v1/orders/b2b/direct-checkout' \
  --header 'x-client-id: YOUR_CLIENT_ID' \
  --header 'x-client-secret: YOUR_CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "dpID": "{YOUR_DP_ID}",
    "productID": "PROD-cd250a2a-2b27-40e0",
    "variantID": "VAR-23c2a475-06cb-4118",
    "denomination": {
      "amount": 100,
      "currency": "AED"
    },
    "externalRefID": "order-07-09-2025"
  }'

Response

Successful Response

{
  "orderID": "ORDIN0912202528cce89",
  "externalRefID": "order-07-09-2025",
  "dpUserEmail": "johndoe@gmail.com",
  "dpUserName": "Demo Intl Test Dp",
  "dpID": "daa30819-8150-4490-b20f-65b75cb148ba",
  "totalOrderMRP": 2448.44,
  "totalAmount": 2448.44,
  "totalCostPrice": 0,
  "dpSellingPrice": 0,
  "subDpSellingPrice": 0,
  "currency": "INR",
  "status": "COMPLETED",
  "fulfillmentStatus": "FULFILLED",
  "createdAt": "2025-12-09T07:40:30.72Z",
  "updatedAt": "2025-12-09T07:40:30.777Z",
  "assetURL": "",
  "type": "DIRECT_CHECKOUT",
  "lineItems": [
    {
      "variantID": "VAR-23c2a475-06cb-4118",
      "productID": "PROD-cd250a2a-2b27-40e0",
      "quantity": 1,
      "mrp": 100,
      "price": 100,
      "totalMRP": 100,
      "totalPrice": 100,
      "totalConvertedPrice": 2448.44,
      "totalItemCostPrice": 0,
      "currency": "AED",
      "fxRate": 24.4844,
      "markUpPercentage": 0,
      "variantName": "TEST_PRODUCT_1_DP_APIS INR 100",
      "productName": "TEST_PRODUCT_1_DP_APIS",
      "variantDisplayName": "₹ 100",
      "productDisplayName": "TEST_PRODUCT_1_DP_APIS",
      "attachments": [
        "https://storage.googleapis.com/exlr8-assets/voucher_bulk_uploads/default_voucher.jpg"
      ],
      "mobileNumbers": null,
      "vouchers": [
        {
          "voucherCode": "89868092",
          "voucherPin": "T5R9-Q2M8-C6V2748",
          "expirationDate": "2028-01-01T00:00:00Z"
        }
      ],
      "fulfillmentStatus": "FULFILLED",
      "allocatedQty": 1,
      "fulfilledQty": 1
    }
  ]
}

:::warning Order Currency Conversion

In the order response, the line item currency is AED, and the totalConvertedPrice (2448.44) is calculated by converting the totalPrice (100) using the fxRate (24.4844) to your selected wallet currency (INR). This ensures the order amount deducted from your wallet is in your selected currency.

:::

Response Fields

Field	Type	Description
orderID	String	System-generated unique order identifier
externalRefID	String	Your provided external reference
dpUserEmail	String	Email of the DP user
dpUserName	String	Name of the DP user
dpID	String	Your delivery partner ID
totalOrderMRP	Number	Total MRP of the order in the selected wallet currency
totalAmount	Number	Total amount charged in the selected wallet currency
totalCostPrice	Number	Total cost price
dpSellingPrice	Number	DP selling price
subDpSellingPrice	Number	Sub-DP selling price
currency	String	Order currency
status	String	Order status (see Status Codes)
fulfillmentStatus	String	Fulfillment status
createdAt	String	Order creation timestamp (ISO 8601)
updatedAt	String	Last update timestamp (ISO 8601)
assetURL	String	URL to download order details (when fulfilled)
type	String	Order type
lineItems	Array	Array of ordered items with details

Line Item Fields

Field	Type	Description
variantID	String	Product variant identifier
productID	String	Product identifier
quantity	Number	Quantity ordered
mrp	Number	Maximum retail price per unit
price	Number	Actual price charged per unit
totalMRP	Number	Total maximum retail price for the line item
totalPrice	Number	Total actual price charged for the line item
totalConvertedPrice	Number	Total converted price for the line item in the selected DP wallet currency
totalItemCostPrice	Number	Total cost price for the line item
currency	String	Line item currency
fxRate	Number	Foreign exchange rate used
markUpPercentage	Number	Markup percentage applied
variantName	String	Variant name
productName	String	Product name
variantDisplayName	String	Display name for the variant
productDisplayName	String	Display name for the product
attachments	Array	Array of attachment URLs (e.g., images or documents)
mobileNumbers	Array	Array of mobile numbers (if applicable, e.g., for SIM cards)
vouchers	Array	Voucher details (when fulfilled) - see Voucher Fields
fulfillmentStatus	String	Item fulfillment status
allocatedQty	Number	Quantity allocated
fulfilledQty	Number	Quantity fulfilled

Voucher Fields

When vouchers are available (order status is COMPLETED and fulfillment status is FULFILLED), each voucher object contains:

Field	Type	Description
voucherCode	String	The voucher code to be used by the customer
voucherPin	String	The voucher PIN for activation
expirationDate	String	Voucher expiration date (ISO 8601 format)

Example voucher object:

{
  "voucherCode": "78776667",
  "voucherPin": "T6R9-Q3M8-C4VVB1200",
  "expirationDate": "2028-01-02T00:00:00Z"
}

Order Status Codes

The order will have one of two final statuses:

Status	Description	Next Steps
COMPLETED	Order successfully completed	Download vouchers if available
FAILED	Order failed during processing	Check error details and retry

Asset Download

When order status is COMPLETED and fulfillmentStatus is FULFILLED:

1. Download the file from assetURL.
2. Use the password sent over email to open the file.
3. Extract voucher information for delivery to your customers.

Error Responses

Insufficient Balance

{
  "error": "insufficient wallet balance",
  "errCode": "INSUFFICIENT_BALANCE"
}

Product Not Available

{
  "error": "insufficient stock for variant VARIANT_ID. Available: AVAILABLE_STOCK_COUNT, Requested: REQUESTED_STOCK_COUNT",
  "errCode": "OUT_OF_STOCK"
}

Invalid Request

{
  "error": "invalid variant ID",
  "errCode": "BAD_REQUEST"
}

Product Does Not Match the Variant

The productID you sent is not the product the variant belongs to. Nothing was charged.

{
  "error": "product mismatch for variantID=VAR-23c2a475-06cb-4118: variant belongs to productID=PROD-cd250a2a-2b27-40e0, received productID=PROD-0000aaaa-1111",
  "errCode": "PRODUCT_VARIANT_MISMATCH"
}

Denomination Does Not Match the Variant

The denomination you sent is not the variant's face value. Nothing was charged. Re-read the variant from the catalog and send its denomination back verbatim.

{
  "error": "denomination mismatch for variantID=VAR-23c2a475-06cb-4118: expected 100 AED (source=VARIANT_MRP), received 500 INR",
  "errCode": "DENOMINATION_MISMATCH"
}

Denomination Could Not Be Resolved

The variant has no usable face value in the catalog. This is a data issue on our side — contact support with the variantID.

{
  "error": "denomination could not be resolved for variantID=VAR-23c2a475-06cb-4118: variant has neither a denomination nor a usable mrp",
  "errCode": "DENOMINATION_UNRESOLVED"
}

Best Practices

1. Unique External References: Always use unique externalRefID values
2. Echo the Catalog: Send productID and denomination exactly as the catalog returned them — do not recompute, round, or convert them
3. Error Handling: Implement proper error handling for all response codes
4. Status Check: Check order status to see if it's COMPLETED or FAILED
5. Asset Download: Download and securely store voucher files when status is COMPLETED

Related Endpoints

• Place Subscription Order - Place a subscription order
• Get Order by ID - Monitor order status
• Get Order by External Ref - Track using your reference
• Get Available Products - Browse available products