---
title: "POST /subscription/link/merchant/generate-link"
method: POST
path: "/subscription/link/merchant/generate-link"
---

# POST /subscription/link/merchant/generate-link

`POST /subscription/link/merchant/generate-link`

This API can be used to generate subscription links programmatically. Subscription links are basically standalone webpages where your customer can make a subscription payment.

## Headers

- `Idempotency-Key` string

## Request body

- SubscriptionLink
  - `amount` integer, required — The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)
  - `currency` string, required — Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported)
  - `receiptId` string — Your identifier of the order
  - `customerDetails` BillingDetails, required — Billing details for the customer.
    - `name` string, required — Customer's name
    - `email` string, required — Customer's email address
    - `contactNumber` string, required — Customer's contact number ([E.164 format](https://en.wikipedia.org/wiki/E.164)), including the country code (e.g., +1 for US, +44 for UK, +91 for India).
    - `customerAddress` CustomerAddress
      - `addressLine1` string — Line 1 of the customer's address
      - `addressLine2` string — Line 2 of the customer's address
      - `city` string — City of the customer's address
      - `state` string — State of the customer's address
      - `country` string — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `postalCode` string — Postal code
  - `description` string — The description of the order, if any
  - `expiryDate` integer, required — Timestamp in epoch milliseconds, indicating the expiration time of the link
  - `callbackUrl` string — The URL we will callback to with the subscriptionId once it finishes.
  - `cancelUrl` string — The URL to redirect the customer to when they cancel the subscription. If not provided, the callbackUrl will be used as fallback.
  - `interval` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — The interval group between subscriptions.
  - `intervalCount` integer, required — The number of intervals between subscription billings. For example, `interval = MONTH` and `intervalCount = 3` bills every 3 months.
  - `cycleCount` integer, required — The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.
  - `upfrontAmount` integer — An optional amount that merchants can set to be charged to the customer at the time the subscription is activated. This amount replaces the first billing cycle charge — the regular subscription amount is not added on top of it. Regular billing resumes from the next cycle. The amount is in the lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (minimum amount should be greater than 1 USD). **Validation Rules:** - Not compatible with `trialPeriodCount` and `trialPeriodInterval` — cannot be provided simultaneously
  - `trialPeriodCount` integer — The number of trial periods before the first billing cycle. Must be greater than or equal to 0 if provided. **Validation Rules:** - If `trialPeriodCount` is provided, `trialPeriodInterval` must also be provided - `trialPeriodCount` is not compatible with `upfrontAmount` - both cannot be provided simultaneously
  - `trialPeriodInterval` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The interval for the trial period. **Validation Rules:** - Required when `trialPeriodCount` is provided
  - `multiUseLimit` integer — The maximum number of times this subscription link can be used. If null, the link can be used only once. Must be greater than 0 if provided.
  - `productPage` ProductPage
    - `name` string, required — Product name. Must be between 2 and 100 characters long.
    - `description` string — Product description. Must be less than 500 characters long.
  - `phoneNumberRequired` boolean — Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.

## Response `200`

Generate Subscription Link

- SubscriptionLinkResponse
  - `shortUrl` string — The shortened URL generated by the xPay API. This link can be shared with customers for completing payments.
  - `disclaimer` string — A message highlighting unsupported currency and payment method pairs. You may use this information to communicate these limitations to your users and set expectations.

## Other responses

- `400` — unexpected error

---

[API](https://skmtc.net/xpaycheckout/apis/xpay-api-store.md) · [All operations](https://skmtc.net/xpaycheckout/apis/xpay-api-store/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xpaycheckout/xpay-api-store/versions/6329a7c694bc/schema)