Place Order

Place a new order 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

For Product Orders

Field	Type	Description	Required
dpID	String	Your delivery partner ID (same as clientID)	✅ Yes
variantID	String	Product variant identifier	✅ Yes
externalRefID	String	Unique reference ID provided by client	❌ No

{
  "dpID": "{YOUR_DP_ID}",
  "variantID": "VAR-23c2a475-06cb-4118",
  "externalRefID": "{uniqueRefIDToBeProvidedByClient}"
}

Unique External Reference

The externalRefID must be unique for each order. This is your reference for tracking the order in your system.

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}",
    "variantID": "VAR-23c2a475-06cb-4118",
    "externalRefID": "order-07-09-2025"
  }'

Response

Successful Response

{
  "orderID": "ORDIN0912202528cce89",
  "externalRefID": "order-07-09-2025",
  "dpUserEmail": "[email protected]",
  "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
    }
  ]
}

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 (see Status Codes)
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 (see Status Codes)
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"
}

Best Practices

1. Unique External References: Always use unique externalRefID values
2. Error Handling: Implement proper error handling for all response codes
3. Status Check: Check order status to see if it's COMPLETED or FAILED
4. Asset Download: Download and securely store voucher files when status is COMPLETED

Related Endpoints

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