--- title: "Create Subscription" method: POST path: "/v5/subscriptions" tags: ["Subscriptions"] --- # Create Subscription `POST /v5/subscriptions` Create a new subscription. A subscription can be associated with an existing plan or created as a custom subscription. ## Request body - union - object — Subscription associated with an existing plan - `paused_subscription` boolean — If set to true, the subscription will be paused - `customer_vault_id` string — Customer vault ID to use for the subscription - `payment_details` union — Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, Apple Pay encrypted payload, or Google Pay encrypted payload. Do not combine fields from different variants. - object — Non-tokenized credit card data. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `card_cvv` string — The card security code. - object — Bank account (ACH) details for this transaction. - `check_name` string, required — The name on the customer's ACH account - `check_aba` number, required — The customer's bank routing number - `check_account` number, required — The customer's bank account number - `account_type` 'checking' | 'savings', required — The type of ACH account the customer has - `account_holder_type` 'personal' | 'business', required — The type of ACH account the customer has - `sec_code` 'PPD' | 'WEB' | 'TEL' | 'CCD' | 'POP' | 'RCK', required — The Standard Entry Class code of the ACH transaction - `check_number` string — Check number - object — Single-use or vault token from Payment Component or Collect.js (not Apple Pay / Google Pay). - `payment_token` string, required — The tokenized version of the customer's card or check information - object — Encrypted payment data from the Apple Pay SDK. - `applepay_payment_data` string, required — The encrypted token created when integration directly to the Apple Pay SDK - object — Encrypted payment data from the Google Pay SDK. - `googlepay_payment_data` string, required — The encrypted token created when integration directly to the Google Pay SDK - object — Merchant-decrypted Apple Pay payment data. - `decrypted_applepay_data` true, required — Merchant-decrypted Apple Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - object — Merchant-decrypted Google Pay payment data. - `decrypted_googlepay_data` true, required — Merchant-decrypted Google Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `billing_address` BillingAddressRest — Billing address and information - `method` 'initial_recurring' | 'recurring' | 'installment' — Recurring or installment classification for the processor. - `initial_recurring`: First transaction in a recurring sequence only. - `recurring`: Later charges in that sequence. - `installment`: Installment transactions; use `number` and `total` on supported processors. Which values apply depends on the processor. - `number` integer — Specify installment billing number, on supported processors. For use when `billing.method` is set to "installment" - `total` number — Specify installment billing total on supported processors. For use when `billing.method` is set to "installment" - `first_name` string — Cardholder's first name - `last_name` string — Cardholder's last name - `company` string — Cardholder's company - `address1` string — Card billing address - `address2` string — Card billing address, line 2 - `city` string — Card billing city - `state` string — Card billing state. Format: `CC` - `zip` string — Card billing zip code - `country` string — Card billing country. Country codes are as shown in ISO 3166-1 alpha-2. Format: `CC` - `phone` string — Billing phone number - `email` string, email — Billing email address - `fax` string — Billing fax number - `cell_phone` string — Billing cell phone number - `website` string — Website (invoice-specific field) - `drivers_license_number` string — Driver's license number - `drivers_license_dob` string — Driver's license date of birth. Format: `YYYY-MM-DD` - `drivers_license_state` string — Driver's license state. Format: `CC` - `payment_details` union — Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, Apple Pay encrypted payload, or Google Pay encrypted payload. Do not combine fields from different variants. - object — Non-tokenized credit card data. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `card_cvv` string — The card security code. - object — Bank account (ACH) details for this transaction. - `check_name` string, required — The name on the customer's ACH account - `check_aba` number, required — The customer's bank routing number - `check_account` number, required — The customer's bank account number - `account_type` 'checking' | 'savings', required — The type of ACH account the customer has - `account_holder_type` 'personal' | 'business', required — The type of ACH account the customer has - `sec_code` 'PPD' | 'WEB' | 'TEL' | 'CCD' | 'POP' | 'RCK', required — The Standard Entry Class code of the ACH transaction - `check_number` string — Check number - object — Single-use or vault token from Payment Component or Collect.js (not Apple Pay / Google Pay). - `payment_token` string, required — The tokenized version of the customer's card or check information - object — Encrypted payment data from the Apple Pay SDK. - `applepay_payment_data` string, required — The encrypted token created when integration directly to the Apple Pay SDK - object — Encrypted payment data from the Google Pay SDK. - `googlepay_payment_data` string, required — The encrypted token created when integration directly to the Google Pay SDK - object — Merchant-decrypted Apple Pay payment data. - `decrypted_applepay_data` true, required — Merchant-decrypted Apple Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - object — Merchant-decrypted Google Pay payment data. - `decrypted_googlepay_data` true, required — Merchant-decrypted Google Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `cardholder_auth` union — Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields. - object — EMV 3-D Secure authentication result fields. - `status` 'verified' | 'attempted', required — Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). - `cavv` string, required — Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. - `xid` string — Cardholder authentication transaction id. Format: base64 encoded. - `three_ds_version` string — 3DSecure version (for example `2.1.0` or `2.2.0`). - `directory_server_id` string — Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - object — Wallet authentication for decrypted Apple Pay or Google Pay payments. - `cavv` string, required — Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). - `eci` string — Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). - `shipping_address` ShippingAddressRest — Shipping address and information - `first_name` string — Shipping first name - `last_name` string — Shipping last name - `company` string — Shipping company - `address1` string — Shipping address - `address2` string — Shipping address, line 2 - `city` string — Shipping city - `state` string — Shipping state. - `zip` string — Shipping zip code - `country` string — ISO 3166-1 alpha-2 country code. Example: `US` - `email` string, email — Shipping email address - `carrier` 'ups' | 'fedex' | 'dhl' | 'usps' — Shipping carrier - `order_details` OrderDetailsRest — Order details and line items - `template_id` string — Order template ID - `description` string — Order description - `id` string — Order ID (for payment requests) - `order_id` string — Order ID (for invoice requests and responses) - `customer_id` string — Customer ID (invoice-specific) - `customer_tax_id` string — Customer tax ID (invoice-specific) - `tax` number — Tax amount - `shipping` number — Shipping amount - `po_number` string — Purchase order number (maxLength 50 for payments, 255 for invoices) - `shipping_postal_code` string — Shipping postal code - `ship_from_postal_code` string — Ship from postal code - `summary_commodity_code` string — Summary commodity code - `duty_amount` number — Duty amount - `discount_amount` number — Discount amount - `national_tax_amount` number — National tax amount - `alternate_tax_amount` number — Alternate tax amount - `alternate_tax_id` string — Alternate tax ID - `vat_tax_amount` number — VAT tax amount - `vat_tax_rate` number — VAT tax rate - `vat_invoice_reference_number` string — VAT invoice reference number - `customer_vat_registration` string — Customer VAT registration - `merchant_vat_registration` string — Merchant VAT registration - `order_date` string, date — Order date - `order_description` string — Order description (maxLength 255 for both payments and invoices) - `ip_address` string — IP address of cardholder (IPv4 or IPv6). Format validated as IP address - `line_items` LineItem[] - `product_code` string — Product code - `description` string — Line item description - `commodity_code` string — Commodity code - `unit_of_measure` string — Unit of measure - `unit_cost` number — Unit cost - `quantity` integer — Quantity - `total_amount` number — Total amount - `tax_amount` number — Tax amount - `tax_rate` number — Tax rate - `discount_amount` number — Discount amount - `discount_rate` number — Discount rate - `tax_type` string — Tax type - `alternate_tax_id` string — Alternate tax ID - `merchant_defined_fields` MerchantDefinedFields — Custom fields that can be set up in merchant control panel under Settings->Merchant Defined Fields - `field_1` string — Merchant defined field 1 - `field_2` string — Merchant defined field 2 - `field_3` string — Merchant defined field 3 - `field_4` string — Merchant defined field 4 - `field_5` string — Merchant defined field 5 - `field_6` string — Merchant defined field 6 - `field_7` string — Merchant defined field 7 - `field_8` string — Merchant defined field 8 - `field_9` string — Merchant defined field 9 - `field_10` string — Merchant defined field 10 - `field_11` string — Merchant defined field 11 - `field_12` string — Merchant defined field 12 - `field_13` string — Merchant defined field 13 - `field_14` string — Merchant defined field 14 - `field_15` string — Merchant defined field 15 - `field_16` string — Merchant defined field 16 - `field_17` string — Merchant defined field 17 - `field_18` string — Merchant defined field 18 - `field_19` string — Merchant defined field 19 - `field_20` string — Merchant defined field 20 - `customer_vault` CustomerVault — Customer vault information for storing payment methods - `add_to_vault` boolean — Add customer to vault - `id` string — Customer vault ID - `cardholder_auth` union — Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields. - object — EMV 3-D Secure authentication result fields. - `status` 'verified' | 'attempted', required — Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). - `cavv` string, required — Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. - `xid` string — Cardholder authentication transaction id. Format: base64 encoded. - `three_ds_version` string — 3DSecure version (for example `2.1.0` or `2.2.0`). - `directory_server_id` string — Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - object — Wallet authentication for decrypted Apple Pay or Google Pay payments. - `cavv` string, required — Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). - `eci` string — Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). - `plan_id` string, required — Plan ID to use for the subscription - object — Custom subscription with plan details - `paused_subscription` boolean — If set to true, the subscription will be paused - `customer_vault_id` string — Customer vault ID to use for the subscription - `payment_details` union — Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, Apple Pay encrypted payload, or Google Pay encrypted payload. Do not combine fields from different variants. - object — Non-tokenized credit card data. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `card_cvv` string — The card security code. - object — Bank account (ACH) details for this transaction. - `check_name` string, required — The name on the customer's ACH account - `check_aba` number, required — The customer's bank routing number - `check_account` number, required — The customer's bank account number - `account_type` 'checking' | 'savings', required — The type of ACH account the customer has - `account_holder_type` 'personal' | 'business', required — The type of ACH account the customer has - `sec_code` 'PPD' | 'WEB' | 'TEL' | 'CCD' | 'POP' | 'RCK', required — The Standard Entry Class code of the ACH transaction - `check_number` string — Check number - object — Single-use or vault token from Payment Component or Collect.js (not Apple Pay / Google Pay). - `payment_token` string, required — The tokenized version of the customer's card or check information - object — Encrypted payment data from the Apple Pay SDK. - `applepay_payment_data` string, required — The encrypted token created when integration directly to the Apple Pay SDK - object — Encrypted payment data from the Google Pay SDK. - `googlepay_payment_data` string, required — The encrypted token created when integration directly to the Google Pay SDK - object — Merchant-decrypted Apple Pay payment data. - `decrypted_applepay_data` true, required — Merchant-decrypted Apple Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - object — Merchant-decrypted Google Pay payment data. - `decrypted_googlepay_data` true, required — Merchant-decrypted Google Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `billing_address` BillingAddressRest — Billing address and information - `method` 'initial_recurring' | 'recurring' | 'installment' — Recurring or installment classification for the processor. - `initial_recurring`: First transaction in a recurring sequence only. - `recurring`: Later charges in that sequence. - `installment`: Installment transactions; use `number` and `total` on supported processors. Which values apply depends on the processor. - `number` integer — Specify installment billing number, on supported processors. For use when `billing.method` is set to "installment" - `total` number — Specify installment billing total on supported processors. For use when `billing.method` is set to "installment" - `first_name` string — Cardholder's first name - `last_name` string — Cardholder's last name - `company` string — Cardholder's company - `address1` string — Card billing address - `address2` string — Card billing address, line 2 - `city` string — Card billing city - `state` string — Card billing state. Format: `CC` - `zip` string — Card billing zip code - `country` string — Card billing country. Country codes are as shown in ISO 3166-1 alpha-2. Format: `CC` - `phone` string — Billing phone number - `email` string, email — Billing email address - `fax` string — Billing fax number - `cell_phone` string — Billing cell phone number - `website` string — Website (invoice-specific field) - `drivers_license_number` string — Driver's license number - `drivers_license_dob` string — Driver's license date of birth. Format: `YYYY-MM-DD` - `drivers_license_state` string — Driver's license state. Format: `CC` - `payment_details` union — Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, Apple Pay encrypted payload, or Google Pay encrypted payload. Do not combine fields from different variants. - object — Non-tokenized credit card data. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `card_cvv` string — The card security code. - object — Bank account (ACH) details for this transaction. - `check_name` string, required — The name on the customer's ACH account - `check_aba` number, required — The customer's bank routing number - `check_account` number, required — The customer's bank account number - `account_type` 'checking' | 'savings', required — The type of ACH account the customer has - `account_holder_type` 'personal' | 'business', required — The type of ACH account the customer has - `sec_code` 'PPD' | 'WEB' | 'TEL' | 'CCD' | 'POP' | 'RCK', required — The Standard Entry Class code of the ACH transaction - `check_number` string — Check number - object — Single-use or vault token from Payment Component or Collect.js (not Apple Pay / Google Pay). - `payment_token` string, required — The tokenized version of the customer's card or check information - object — Encrypted payment data from the Apple Pay SDK. - `applepay_payment_data` string, required — The encrypted token created when integration directly to the Apple Pay SDK - object — Encrypted payment data from the Google Pay SDK. - `googlepay_payment_data` string, required — The encrypted token created when integration directly to the Google Pay SDK - object — Merchant-decrypted Apple Pay payment data. - `decrypted_applepay_data` true, required — Merchant-decrypted Apple Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - object — Merchant-decrypted Google Pay payment data. - `decrypted_googlepay_data` true, required — Merchant-decrypted Google Pay flag. - `card_number` string, required — Credit card number - `card_exp` string, required — Credit card expiration date. Format: `MMYY` - `cardholder_auth` union — Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields. - object — EMV 3-D Secure authentication result fields. - `status` 'verified' | 'attempted', required — Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). - `cavv` string, required — Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. - `xid` string — Cardholder authentication transaction id. Format: base64 encoded. - `three_ds_version` string — 3DSecure version (for example `2.1.0` or `2.2.0`). - `directory_server_id` string — Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - object — Wallet authentication for decrypted Apple Pay or Google Pay payments. - `cavv` string, required — Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). - `eci` string — Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). - `shipping_address` ShippingAddressRest — Shipping address and information - `first_name` string — Shipping first name - `last_name` string — Shipping last name - `company` string — Shipping company - `address1` string — Shipping address - `address2` string — Shipping address, line 2 - `city` string — Shipping city - `state` string — Shipping state. - `zip` string — Shipping zip code - `country` string — ISO 3166-1 alpha-2 country code. Example: `US` - `email` string, email — Shipping email address - `carrier` 'ups' | 'fedex' | 'dhl' | 'usps' — Shipping carrier - `order_details` OrderDetailsRest — Order details and line items - `template_id` string — Order template ID - `description` string — Order description - `id` string — Order ID (for payment requests) - `order_id` string — Order ID (for invoice requests and responses) - `customer_id` string — Customer ID (invoice-specific) - `customer_tax_id` string — Customer tax ID (invoice-specific) - `tax` number — Tax amount - `shipping` number — Shipping amount - `po_number` string — Purchase order number (maxLength 50 for payments, 255 for invoices) - `shipping_postal_code` string — Shipping postal code - `ship_from_postal_code` string — Ship from postal code - `summary_commodity_code` string — Summary commodity code - `duty_amount` number — Duty amount - `discount_amount` number — Discount amount - `national_tax_amount` number — National tax amount - `alternate_tax_amount` number — Alternate tax amount - `alternate_tax_id` string — Alternate tax ID - `vat_tax_amount` number — VAT tax amount - `vat_tax_rate` number — VAT tax rate - `vat_invoice_reference_number` string — VAT invoice reference number - `customer_vat_registration` string — Customer VAT registration - `merchant_vat_registration` string — Merchant VAT registration - `order_date` string, date — Order date - `order_description` string — Order description (maxLength 255 for both payments and invoices) - `ip_address` string — IP address of cardholder (IPv4 or IPv6). Format validated as IP address - `line_items` LineItem[] - `product_code` string — Product code - `description` string — Line item description - `commodity_code` string — Commodity code - `unit_of_measure` string — Unit of measure - `unit_cost` number — Unit cost - `quantity` integer — Quantity - `total_amount` number — Total amount - `tax_amount` number — Tax amount - `tax_rate` number — Tax rate - `discount_amount` number — Discount amount - `discount_rate` number — Discount rate - `tax_type` string — Tax type - `alternate_tax_id` string — Alternate tax ID - `merchant_defined_fields` MerchantDefinedFields — Custom fields that can be set up in merchant control panel under Settings->Merchant Defined Fields - `field_1` string — Merchant defined field 1 - `field_2` string — Merchant defined field 2 - `field_3` string — Merchant defined field 3 - `field_4` string — Merchant defined field 4 - `field_5` string — Merchant defined field 5 - `field_6` string — Merchant defined field 6 - `field_7` string — Merchant defined field 7 - `field_8` string — Merchant defined field 8 - `field_9` string — Merchant defined field 9 - `field_10` string — Merchant defined field 10 - `field_11` string — Merchant defined field 11 - `field_12` string — Merchant defined field 12 - `field_13` string — Merchant defined field 13 - `field_14` string — Merchant defined field 14 - `field_15` string — Merchant defined field 15 - `field_16` string — Merchant defined field 16 - `field_17` string — Merchant defined field 17 - `field_18` string — Merchant defined field 18 - `field_19` string — Merchant defined field 19 - `field_20` string — Merchant defined field 20 - `customer_vault` CustomerVault — Customer vault information for storing payment methods - `add_to_vault` boolean — Add customer to vault - `id` string — Customer vault ID - `cardholder_auth` union — Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields. - object — EMV 3-D Secure authentication result fields. - `status` 'verified' | 'attempted', required — Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). - `cavv` string, required — Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. - `xid` string — Cardholder authentication transaction id. Format: base64 encoded. - `three_ds_version` string — 3DSecure version (for example `2.1.0` or `2.2.0`). - `directory_server_id` string — Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - object — Wallet authentication for decrypted Apple Pay or Google Pay payments. - `cavv` string, required — Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). - `eci` string — Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). - `plan_details` union - object - `plan_id` string, required — The unique identifier for the plan - `plan_name` string, required — The display name of the plan - `plan_amount` number, required — The plan amount to be charged each billing cycle. Format: `x.xx` - `plan_payments` integer, required — The number of payments before the recurring plan is complete. Use '0' for until canceled - `start_date` string — The first day that the customer will be charged. Format: `YYYYMMDD` - `month_frequency` integer, required — How often, in months, to charge the customer. - `day_of_month` integer, required — The day of the month that the customer will be charged. For months without 29, 30, or 31 days, the charge will be on the last day. - object - `plan_id` string, required — The unique identifier for the plan - `plan_name` string, required — The display name of the plan - `plan_amount` number, required — The plan amount to be charged each billing cycle. Format: `x.xx` - `plan_payments` integer, required — The number of payments before the recurring plan is complete. Use '0' for until canceled - `start_date` string — The first day that the customer will be charged. Format: `YYYYMMDD` - `day_frequency` integer, required — How often, in days, to charge the customer. ## Response `200` Success - SubscriptionResponse — Subscription response matching SubscriptionRestSerializer structure - `object` 'subscription', required — Resource type identifier - `id` string, required — Subscription ID - `start_date` string, date-time, nullable — Subscription start date in UTC ISO 8601 format - `next_billing_date` string, date-time, nullable — Next billing date in UTC ISO 8601 format - `amount` string — Subscription amount - `customer_vault_id` string — Customer vault ID associated with the subscription - `delayed_condition` string — Delayed condition - `paused_subscription` 0 | 1 — Whether the subscription is paused (0 = active, 1 = paused) - `plan` object, nullable — Associated plan - `id` string — Plan ID - `plan_name` string — Plan name - `plan_amount` string — Plan amount - `plan_payments` string — Number of payments (0 = until canceled) - `day_frequency` string — Day frequency (0 if not applicable) - `month_frequency` string — Month frequency (0 if not applicable) - `day_of_month` string — Day of month (empty if not applicable) ## Other responses - `400` — Bad Request - Validation Error - `401` — Unauthorized --- [API](https://skmtc.net/nmi/apis/embedded-components-api.md) · [All operations](https://skmtc.net/nmi/apis/embedded-components-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nmi/embedded-components-api/revisions/45c2ecda3685/schema)