--- 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` 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.net/clover/apis/platform-api.md) · [All operations](https://skmtc.net/clover/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clover/platform-api/revisions/08da265101a3/schema)