Skip to main content

Get Order by External Reference

Fetch detailed information for a specific order using your provided external reference ID.

Endpoint​

GET /v1/orders/b2b/delivery-partners/{dpID}/externalref/{externalRefID}

Headers​

HeaderTypeDescriptionRequired
x-client-idStringYour clientID✅ Yes
x-client-secretStringYour clientSecret✅ Yes

Path Parameters​

ParameterTypeDescriptionRequired
dpIDStringYour delivery partner ID✅ Yes
externalRefIDStringYour unique external reference ID✅ Yes
Use Your Reference

This endpoint is perfect when you want to track orders using your own reference system instead of eXlr8's order IDs.

Example Request​

curl --location 'https://stage-platform-exlr8.exlr8now.com/v1/orders/b2b/delivery-partners/YOUR_DP_ID/externalref/order-07-09-2025' \
  --header 'x-client-id: YOUR_CLIENT_ID' \
  --header 'x-client-secret: YOUR_CLIENT_SECRET'

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 Schema​

The response schema is identical to Get Order by ID. See that page for detailed field descriptions.

Error Responses​

Order Not Found​

{
  "error": "order not found for external reference: order-07-09-2025",
  "errCode": "RECORD_NOT_FOUND"
}

Use Cases​

1. Customer Service Integration​

Quickly look up orders when customers provide their reference numbers.

2. Internal System Synchronization​

Sync order status with your internal systems using your own reference IDs.

3. Webhook Processing​

Update order status in your system when receiving webhooks with external references.

Integration Example​

// Example: Check order status by external reference
async function checkOrderStatus(externalRefID) {
  try {
    const response = await fetch(
      `${baseUrl}/orders/b2b/delivery-partners/${dpID}/externalref/${externalRefID}`,
      {
        headers: {
          "x-client-id": clientId,
          "x-client-secret": clientSecret,
        },
      }
    );

    if (!response.ok) {
      const error = await response.json();
      if (error.errCode === "RECORD_NOT_FOUND") {
        console.log("Order not found");
        return null;
      }
      throw new Error(`API Error: ${error.error}`);
    }

    const order = await response.json();

    // Handle different order states
    switch (order.status) {
      case "COMPLETED":
        if (order.fulfillmentStatus === "FULFILLED") {
          await downloadOrderAssets(order);
        }
        break;
      case "FAILED":
        await handleFailedOrder(order);
        break;
      case "PROCESSING":
        // Schedule another check later
        setTimeout(() => checkOrderStatus(externalRefID), 30000);
        break;
    }

    return order;
  } catch (error) {
    console.error("Error checking order status:", error);
    throw error;
  }
}

Best Practices​

  1. Consistent References: Use a consistent format for your external reference IDs
  2. Error Handling: Always handle the case where orders are not found
  3. Status Polling: Implement intelligent polling for pending orders
  4. Logging: Log all order lookups for audit trails