> ## Documentation Index > Fetch the complete documentation index at: https://developer.transactbridge.com/llms.txt > Use this file to discover all available pages before exploring further. # Add Subscription > This API is used to create a unique payment link for a subscription, that can be shared with a customer. Once the user pays the requested amount through the selected payment channel, the partner gets a webhook call for a successful credit and subscription. At the start, the subscription is in PENDING state, which means the customer can pay to activate the subscription. If the customer fails to make payment before the date derived from pendingExpire then the subscription is moved into PENDING_EXPIRED which is a terminal state after which no payment can be made on the same subscription. ## OpenAPI ````yaml /api-reference/subscriptions/subs.json post /subscription/v1.0/addSubscription openapi: 3.0.3 info: title: Subscription API description: API for creating and managing subscription sessions and payments. version: 1.0.0 servers: - url: https://sandbox-api.transactbridge.com description: Sandbox Environment - url: https://api.transactbridge.com description: Production Environment security: - ApiKeyAuth: [] SignatureAuth: [] paths: /subscription/v1.0/addSubscription: post: tags: - Subscription summary: Add Subscription description: >- This API is used to create a unique payment link for a subscription, that can be shared with a customer. Once the user pays the requested amount through the selected payment channel, the partner gets a webhook call for a successful credit and subscription. At the start, the subscription is in PENDING state, which means the customer can pay to activate the subscription. If the customer fails to make payment before the date derived from pendingExpire then the subscription is moved into PENDING_EXPIRED which is a terminal state after which no payment can be made on the same subscription. operationId: addSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscription' example: customerId: 67a1b2c3d4e5f67890123456 email: customer@example.com clientReferenceId: CUST-REF-10001 phoneNo: +91-9876543210 taxIdentity: ABCDE1234F gstIdentity: 27ABCDE1234F1Z5 name: John Doe quoteCurrCode: INR maxQuoteAmount: '15000' returnUrl: https://example.com/payment/return referenceId: SUB-2026-00001 userTaxId: GST-18-PERCENT payMethod: - UPI - CC redirectionType: NEW_PAGE frequency: MNTH description: Monthly Premium Subscription collectionMechanism: AUTOPAY billAtStart: true couponDetails: name: WELCOME10 type: PERCENTAGE value: 10 pendingExpire: '30' maxUnpaidInvoices: '2' postMaxUnpaidInvoices: PAUSED dayUntillDue: '1' billingDateAnchor: '2' trialSettings: duration: 14 unit: DAY maxUnpausedInvoiceDueCount: count: 2 reAttemptConfig: - attemptType: try_again attemptCount: 3 shipTo: name: John Doe addressLine1: 123 Main Street city: Mumbai state: Maharashtra postalCode: '400001' country: IN billTo: name: John Doe addressLine1: 123 Main Street city: Mumbai state: Maharashtra postalCode: '400001' country: IN sameAsBilling: true items: - name: Premium Plan quantity: 1 unitPrice: 2000 meta: orderId: ORDER-10001 source: website dropIn: enabled: true responses: '200': description: Payment session created successfully. content: application/json: schema: $ref: '#/components/schemas/subscription' components: schemas: CreateSubscription: type: object required: - quoteCurrCode - maxQuoteAmount - returnUrl - frequency - items - billTo properties: customerId: type: string description: >- If the customer is already created use customerId and then email is optional parameter. format: MongoId email: type: string description: |- Customer's email. Require this to send an invoice. This parameter is mandatory if clientReferenceId is not passed. clientReferenceId: type: string description: >- Customer's reference id that the partner can pass to map it to the customer on Transact Bridge panel. If email is not passed in the request body, the customer must enter the email on the product checkout page. This parameter is mandatory if email is not passed. phoneNo: type: string description: The customer's Indian phone number in the format of +91-XXXXXXXX example: +91-9876543210 taxIdentity: type: string description: PAN number of the customer gstIdentity: type: string description: >- If the customer is business type then GST can be used so that the business can get input credits. name: type: string description: Name of the customer quoteCurrCode: type: string enum: - USD - EURO - INR description: Fiat currency for which request needs to be initiated. maxQuoteAmount: type: string description: >- This is the amount in the same denomination as quoteCurrCode. This is the maximum value for which we can use the mandate for auto debit the amount. This amount will be inclusive of GST/VAT. Please configure it accordingly. Note: UPI has a maximum limit of ₹15,000 per mandate. Cards have a limit of ₹500,000 per mandate. returnUrl: type: string description: >- This URL is needed to redirect the user after the session is completed.This url will be a redirection with status, subscriptionId, and referenceId values passed in the query parameters. referenceId: type: string format: referenceId maxLength: 128 description: >- This is a partner-generated ID to map a subscription. Partners can use this to query the subscriptions as well. This cannot be the same for two subscriptions. Reference ID that was passed by the partner during the generation of the session. userTaxId: type: string description: >- We will create a userTaxId for the partner. This allows us to tax the product correctly. For example: Partners can have two different userTaxId one for 18% GST and the other for 5% GST. payMethod: type: array description: >- If payMethod parameter is sent by the partner then on the payment page for the customer only that payment method will be visible to user. items: type: string enum: - UPI - NB - CC - DC redirectionType: type: string enum: - SAME_PAGE - NEW_PAGE default: SAME_PAGE description: >- Depending on the redirection type value, the user will either be redirected to a new page for payment or to the same window of the product page. Default value is NEW_PAGE. frequency: type: string description: Frequency of the subscription renewal period. enum: - DAIL - WEEK - MNTH - BIMN - QURT - MIAN - YEAR - ONDM description: type: string description: To set the subscription view collectionMechanism: type: string enum: - AUTOPAY description: Only AUTOPAY is allowed right now. billAtStart: type: boolean default: true description: >- If this is true, then the subscription is prepaid based subscription and allows to deduction of money before providing the product to the end customer and generating the invoice at the start of the subscription period. If this is false then it is a postpaid subscription which creates an invoice at the end of the subscription period. couponDetails: type: object description: >- To pass the coupon object and apply different coupons on the subscription. properties: coupon: type: string description: String with max length of 256 characters. applicable: type: boolean description: Always send true discountType: type: string description: Discount can be percentage based on the invoice value or flat. enum: - PCNT - FIX discountPcnt: type: string description: If discountType is PCNT then this parameter is Mandatory discountQuoteAmount: type: string description: If discountType is FIX then this parameter is Mandatory durationType: type: string description: >- The duration for which this coupon will be applicable on the subscription. enum: - LIMITED_PERIOD - FOREVER - ONETIME periodUnit: type: string description: >- If durationType is LIMITED_PERIOD then this parameter is Mandatory enum: - DAIL - WEEK - MNTH - BIMN - QURT - MIAN - YEAR - ONDM period: type: number description: >- If durationType is LIMITED_PERIOD then this parameter is Mandatory required: - coupon - applicable - discountType - durationType pendingExpire: type: string description: >- Number of minutes after which the status of the subscription if PENDING (Customer did not pay) it becomes PENDING_EXPIRED which is a terminal state and now customers cannot pay on the same subscription. maxUnpaidInvoices: type: string default: '0' description: >- Max unpaid invoices allowed for the subscription. For example, if maxUnpaidInvoices is set to 2 then after 2 unpaid invoices the subscription status will be converted from ACTIVE to the status based on postMaxUnpaidInvoices. postMaxUnpaidInvoices: type: string enum: - PENDING - PENDING_EXPIRED - PAUSED - EXPIRED - CANCELLED default: PAUSED description: >- Subscription status after maxUnpaidInvoices threshold is crossed by the customer. Default Value: PAUSED dayUntillDue: type: string default: '1' description: >- Period of time from the issue date after which DUE invoice is converted into OVERDUE status billingDateAnchor: type: string description: >- It allows the partner to configure the billing cycle from a fixed date. If not passed then the subscription period will start from the day the customer pays for it. For Example: if the frequency is MNTH (monthly) and billingDateAnchor is set to 2, this means that the invoice will be created on every 2nd day of each month. trialSettings: type: object description: Configuration of the trial mechanism properties: freeTrialExpire: type: string format: date description: Date in the future at which the trial should expire. needPayMethod: type: boolean description: >- If a valid payment method with the mandate is required to activate the trial. reminderBeforeTrialEnd: type: string description: >- Number of days before the freeTrialExpire to send an email to remind the customer of the upcoming debit to convert trial to active subscription. The default value is 2. required: - freeTrialExpire maxUnpausedInvoiceDueCount: type: object description: >- Maximum number of unpaid invoices count allowed after that the subscription is PAUSED by the system. For example, if a subscription has been paused due to 3 non payment of invoices and this parameter is set to be 2 then once the customer pays 1 invoice the subscription will be re activated. reAttemptConfig: type: array description: To configure how the reattempt for failed invoices be processed. items: type: object properties: days: type: string description: Number of days after which the reattempt is to be made. example: '3' attemptType: type: string description: >- Depending on the enum passed, the post-reattempt flow is configured. `try_again` configures the system to make a reattempt. Other values are terminal states that change the status of the subscription and invoice according to the configured enum. enum: - try_again - subscription_active-invoice_unpaid - subscription_paused-invoice_unpaid - subscription_expire-invoice_unpaid - subscription_expire-invoice_cancelled example: try_again required: - days - attemptType shipTo: type: object description: Shipping Details of the Customer properties: name: type: string description: Name of the customer line1: type: string description: Address Line 1 of the customer line2: type: string description: Address Line 2 of the customer city: type: string description: City of the customer state: type: string description: State of the customer address country: type: string description: Country of the customer. postalCode: type: string description: Pin code of the customer. billTo: type: object description: Billing Details of the customer required: - country properties: name: type: string description: Name of the customer line1: type: string description: Address Line 1 of the customer line2: type: string description: Address Line 2 of the customer city: type: string description: City of the customer state: type: string description: State of the customer address country: type: string description: >- Country of the customer.[Enum for country](/api-reference/validators-and-enum) postalCode: type: string description: 'Pin code of the customer. ' sameAsBilling: type: boolean description: |- To make the shipping address the same as the billing address. If sameAsBilling parameter value is set as true then shipTo is not mandatory, and the invoice will have the same shipping and billing address. items: type: array description: Items the customer wants to buy. items: type: object properties: productReferenceId: type: string format: referenceId description: >- If the product is already created use the refereneId of that product. If productReferenceId is passed then name is not mandatory name: type: string description: Name of the product the customer wants to buy. quantity: type: number description: Number of products the customer wants to buy. amount: type: number description: Price of the product. prorate: type: number description: >- If the invoice needs to be partially paid the total amount will be calculated using prorate on day consumed basis. description: type: string description: >- Description of the product. Description in the items object allows HTML syntax for customer view. Use so that the description on the product page is better from a UI perspective. We break and show the description like unlisted items. required: - productReferenceId - name - quantity - amount meta: type: object description: >- To add meta params in the subscription. They will be passed in the webhook and query API as well. properties: param1: type: string maxLength: 256 param2: type: string maxLength: 256 param3: type: string maxLength: 256 dropIn: type: object description: >- If this is set to be true then the response will contain token that can be used in the drop-in module. This can only be sent in the request if DropIn module has been enabled for the Partner Account. subscription: type: object properties: status: type: string description: The response from the API sub_status: type: string description: Used for internal purposes only data: type: object description: Contains the subscription ID and URL properties: subscriptionId: type: string description: The unique ID of the created subscription url: type: string format: uri description: |- The URL used to access the checkout session. returnUrl will be a GET redirection with status, subscriptionId, and referenceId values passed in the query parameters. Partners can then use the Get Subscription API to get the full details of that session. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Merchant API Key SignatureAuth: type: apiKey in: header name: x-signature description: Generated request signature ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.