Place Subscription Order

Place a new order for a subscription product (e.g., specific software licenses or services). This endpoint handles starting trials, activating paid subscriptions, and renewing existing ones.

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 starting a trial, activating, or renewing a subscription.

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 — amount and currency, exactly as returned by the catalog API	✅ Yes
externalRefID	String	Unique reference ID provided by client	✅ Yes
action	String	Action: TRIAL, ACTIVATE, RENEW	✅ Yes
subscriberID	String	The unique ID of the user (e.g., your internal userId) for whom the order is being placed.	✅ Yes

:::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 with PRODUCT_VARIANT_MISMATCH or DENOMINATION_MISMATCH and nothing is charged. Copy both values straight from the product catalog response and send them back verbatim; the denomination is compared in the variant's own currency and is never FX-converted. See Place Voucher Order for details.

:::

:::info Understanding Subscriber ID The subscriberID MUST be the userId of the specific user for whom the order is being placed. If you are integrating this as a company, use the unique internal userId of your user who will consume this subscription. :::

Subscription Actions Explained

Action	Description	Dependencies
TRIAL	Start a new trial subscription	subscriberID IS required
ACTIVATE	Start a new paid subscription	subscriberID IS required
RENEW	Renew an existing subscription	subscriberID IS required

Subscription Lifecycle and Billing

Wallet Deduction

• TRIAL: No wallet balance is deducted when starting a trial.
• ACTIVATE & RENEW: The required amount will be deducted from your wallet immediately upon placing the order.

Trial Duration and Notifications

• The duration of a TRIAL subscription depends on the configuration of the specific product variant.
• Subscription expiry notifications will be sent to the Delivery Partner (DP) when only 7 days are remaining before the subscription expires.

Post-Trial Behavior

Once the trial period ends, the system automatically attempts to renew the subscription:

1. Successful Renewal: If your wallet has sufficient balance, the subscription is automatically renewed, and the balance is deducted.
2. Cancellation: If there is insufficient balance in your wallet at the end of the trial, the subscription will be automatically cancelled.

:::warning Trial Limitation A trial is applicable only once per user across all subscription products. This means if a user has already used a trial for any subscription product, they cannot initiate another trial for any other product. :::

:::info Subscription Cancellation To manually cancel a TRIAL subscription before it ends, use the Cancel Subscription endpoint. :::

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-SUBS-4f2b1c8d9e07",
    "variantID": "VAR-SUBS-123",
    "denomination": {
      "amount": 499,
      "currency": "INR"
    },
    "externalRefID": "sub-order-001",
    "action": "ACTIVATE",
    "subscriberID": "user-12345"
  }'

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

Response

Successful Response

{
  "orderID": "ORDIN123456789",
  "externalRefID": "sub-order-001",
  "status": "COMPLETED",
  "fulfillmentStatus": "FULFILLED",
  "type": "DIRECT_CHECKOUT",
  "lineItems": [
    {
      "variantID": "VAR-SUBS-123",
      "productID": "PROD-SUBS-001",
      "productName": "Premium Subscription Service",
      "subscription": {
          "subscriptionID": "SUBS-123456789",
          "subscriberID": "SUBR-987654321",
          "state": "ACTIVE",
          "startTime": "2025-12-09T07:40:30.72Z",
          "endTime": "2026-01-09T07:40:30.72Z",
          "action": "ACTIVATE"
      }
    }
  ]
}

:::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
status	String	Order status
fulfillmentStatus	String	Fulfillment status
type	String	Order type
lineItems	Array	Array of ordered items with details

Cancel Trial Subscription

Cancel an active trial subscription.

Endpoint

POST /v1/subscriptions/cancel

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

Field	Type	Description	Required
subscriberID	String	The ID of the subscription to cancel (must be a trial request)	✅ Yes

{
  "subscriberID": "SUBR-123456789"
}

Response

Successful Response

{
  "message": "Subscription cancelled successfully"
}

Error Responses

Subscription Not Found

{
  "error": "subscription not found for subscriberID: SUBR-123456789",
  "errCode": "RECORD_NOT_FOUND"
}

Not a Trial Subscription

{
  "error": "subscription is not in trial state, cannot cancel",
  "errCode": "UNPROCESSABLE_ENTITY"
}

Related Endpoints

• Place Voucher Order - Create new voucher orders
• Get Orders - List all orders
• Get Order by ID - Monitor order status
• Get Order by External Ref - Track using your reference
• Get Available Products - Browse available products