--- title: "Create a subscription under a plan" method: POST path: "/v1/plans/{planId}/subscriptions" tags: ["SUBSCRIPTIONS"] --- # Create a subscription under a plan `POST /v1/plans/{planId}/subscriptions` ## Request - Base URL: `https://sandbox.dev.clover.com/recurring` - URL: `https://sandbox.dev.clover.com/recurring/v1/plans/{planId}/subscriptions` - Auth: HTTP bearer Creates a subscription under a plan, including details such as customer billing information, card-on-file, scheduled payment amount, start date, and payment intervals. ## Path parameters - `planId` string, required ## Headers - `X-Clover-Merchant-Id` string, required - `User-Agent` string, required ## Request body - object - `startDate` string, date-time: Start date of the subscription plan in ISO-8601 format. For example, September 7, 2023 displays as 20230907 or with delimiters as 2023-09-07. Time displays in hours, minutes, and seconds, as 12:07:22. - `collectionMethod` 'CHARGE_AUTOMATICALLY' | 'AUTHORIZE_AUTOMATICALLY' | 'SEND_INVOICE', required: Method of collecting the subscription. Values: - Charge_automatically - Authorize_automatically - Send_invoice - `endDate` string, date-time: End date of the subscription plan in ISO-8601 format. For example, September 7, 2023 displays as 20230907 or with delimiters as 2023-09-07. Time displays in hours, minutes, and seconds, as 12:07:22. - `softDescriptor` object: Information about the business that processed the charge. - `dbaName` string: Merchant doing business as (DBA) name, product, or service. Length: Maximum 38 alphanumeric characters - `street` string: Merchant's street address. - `city` string: Merchant's city. - `region` string: Merchant's state. Format: 2-character postal abbreviation (US only) - `postalCode` string: Merchant's postal code. - `countryCode` string: Merchant's country code. Format: 3-digit code; see the Country code reference - `merchantContactInfo` string: Merchant's phone number or email address. Format: Maximum 13 characters for Discover and Visa transactions - `level2` object - `taxAmount` integer: Amount of applicable taxes. - `taxIndicator` 'UNKNOWN' | 'TAXABLE' | 'NON_TAXABLE': Indicates whether the amount is taxable. Values: - Unknown - Taxable - Non-taxable - `vatTaxAmount` integer: Amount of applicable value-added taxes (VAT). - `vatTaxRate` integer: Rate of applicable value-added taxes (VAT). - `purchaseIdentifier` string: Identifier, such as stock keeping unit (SKU), code or reference number that the merchant or customer uses to identify the purchase. - `pcOrderNumber` string: Order number or customer reference number reported as part of the purchase card data. - `discountAmount` integer: Discount amount for the transaction. Format: Cents - `freightAmount` integer: Freight amount. Format: Cents - `dutyAmount` integer: Duty amount. Format: Cents - `destinationPostalCode` string: Postal or ZIP code of the delivery location. - `shipFromPostalCode` string: Postal or ZIP code of the shipping location. - `destinationCountryCode` string: Delivery location country code. Format: 3-digit code; see the Country code reference. - `merchantTaxId` string: Only for Mastercard. Identifier (ID) for the tax collected by the merchant for the transaction. - `productDescription` string: Description of the purchased item. - `note` string: Additional information or note related to the subscription. If available, it overrides the plan's subscription. - `tipAmount` integer: Tip amount. If available, it overrides the plan's amount. - `amount` integer: Amount of the subscription. If available, it overrides the plan's amount. - `active` boolean: Indicates whether the subscription is currently active. Values: - True - False - `taxRateUuids` string[]: Universally unique identifiers (UUIDs) of the tax rate. If available, it overrides the plan's subscription. Length: Maximum length of combined UUIDs is more than 255 characters. - `customerId` string, uuid, required: Customer identifier (ID). ## Response `200` Successful response. Subscription is created in a plan. - object - `object` string: Subscription object. - `id` string, UUID: Subscription identifier. - `customerUuid` string, uuid: Customer universally unique identifier (UUID). - `collectionMethod` 'CHARGE_AUTOMATICALLY' | 'AUTHORIZE_AUTOMATICALLY' | 'SEND_INVOICE': Method for collecting payment. Currently, `charge_automatically` is the only method allowed. - `plan` object - `id` string: Subscription plan identifier (ID). - `uuid` string, uuid: Universally unique identifier (UUID) of the subscription plan. - `name` string: Subscription plan name. - `merchantId` string: Merchant identifier (ID) who applied for the subscription plan. - `taxRateUuids` string[]: Tax rate universally unique identifier (UUID) for the plan. - `tipAmount` integer: Tip amount. - `amount` integer: Amount of the subscription plan. - `active` boolean: Indicates whether the subscription plan is active. Values: - True - False - `interval` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR': Interval of the subscription plan. Values: - Day - Week - Month - Year - `intervalCount` integer: Number of intervals in the subscription plan. - `productUuid` string: Universally unique identifier (UUID) of the subscription plan product. - `note` string: Subscription plan note, if any. - `createdTime` string, date-time: Time when the subscription plan was created. - `modifiedTime` string, date-time: Time when the subscription plan was modified. - `deletedTime` string, date-time: Time when the subscription plan was deleted. - `merchantId` string, uuid: Merchant identifier (ID) who applied for the subscription plan. - `active` boolean: Indicates whether the merchant business is active or not. Values: - True - False - `tipAmount` integer: Tip amount. - `amount` integer: Amount of subscription. - `startDate` string, date-time: Start date of the subscription plan in ISO-8601 format. For example, September 7, 2019 displays as 20190907 or expressed with delimiters as 2019-09-07. Time displays in hours, minutes, and seconds, as 12:07:22. - `endDate` string, date-time: End date of the subscription plan in ISO-8601 format. For example, September 7, 2019 displays as 20190907 or expressed with delimiters as 2019-09-07. Time displays in hours, minutes, and seconds, as 12:07:22. - `note` string: Subscription note, if any. - `lastRunDate` string, date-time: Last run date of subscription. - `createdTime` string, date-time: Time when subscription was created. - `modifiedTime` string, date-time: Time when subscription was modified. - `deletedTime` string, date-time: Time when subscription was deleted. - `softDescriptor` object - `dbaName` string: Merchant doing business as (DBA) name, product, or service. Length: Maximum 38 alphanumeric characters - `street` string: Merchant's street address. - `city` string: Merchant's city. - `region` string: Merchant's state. Format: 2-character postal abbreviation (US only) - `postalCode` string: Merchant's postal code. - `countryCode` string: Merchant's country code. Format: 3-digit code; see the Country code reference - `merchantContactInfo` string: Merchant's phone number or email address. Format: Maximum 13 characters for Discover and Visa transactions - `level2` object - `taxAmount` integer: Amount of applicable taxes. - `taxIndicator` 'UNKNOWN' | 'TAXABLE' | 'NON_TAXABLE': Indicates if the amount is taxable. - `vatTaxAmount` integer: Amount of applicable value added taxes (VAT). - `vatTaxRate` integer: Rate of applicable value added taxes (VAT). - `purchaseIdentifier` string: Purchase identifier. - `pcOrderNumber` string: Placed order number. - `discountAmount` integer: Discounted amount. - `freightAmount` integer: Amount spent for freight. - `dutyAmount` integer: Amount of duty charges. - `destinationPostalCode` string: Postal code of the destination. - `shipFromPostalCode` string: Postal code of the origination. - `destinationCountryCode` string: Destination country code. - `merchantTaxId` string: Tax identifier of the merchant. - `productDescription` string: Detailed description of the product. - `taxRateUuids` string[]: Tax rate universally unique identifier (UUID) for the plan. ## Other responses - `default`: Unexpected error. --- [API](https://skmtc.dev/clover/apis/ecommerce-recurring-apis.md) - [All operations](https://skmtc.dev/clover/apis/ecommerce-recurring-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/clover/apis/ecommerce-recurring-apis/revisions/c49bc4a5e5ed?raw)