--- title: "CreateSubscription" method: POST path: "/v2/subscriptions" tags: ["Subscriptions"] --- # CreateSubscription `POST /v2/subscriptions` Creates a subscription for a customer to a subscription plan. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square bills an invoice to the customer's email address. The subscription starts immediately, unless the request includes the optional `start_date`. Each individual subscription is associated with a particular location. ## Request body - CreateSubscriptionRequest — Defines parameters in a [CreateSubscription](https://developer.squareup.com/reference/square_2021-08-18/subscriptions-api/create-subscription) endpoint request. - `canceled_date` string — The date when the subscription should be canceled, in YYYY-MM-DD format (for example, 2025-02-29). This overrides the plan configuration if it comes before the date the subscription would otherwise end. - `card_id` string — The ID of the [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) [card](https://developer.squareup.com/reference/square_2021-08-18/objects/Card) to charge. If not specified, Square sends an invoice via email. For an example to create a customer and add a card on file, see [Subscriptions Walkthrough](https://developer.squareup.com/docs/subscriptions-api/walkthrough). - `customer_id` string, required — The ID of the [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) profile. - `idempotency_key` string — A unique string that identifies this `CreateSubscription` request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency keys](https://developer.squareup.com/docs/working-with-apis/idempotency). - `location_id` string, required — The ID of the location the subscription is associated with. - `plan_id` string, required — The ID of the subscription plan created using the Catalog API. For more information, see [Set Up and Manage a Subscription Plan](https://developer.squareup.com/docs/subscriptions-api/setup-plan) and [Subscriptions Walkthrough](https://developer.squareup.com/docs/subscriptions-api/walkthrough). - `price_override_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `start_date` string — The start date of the subscription, in YYYY-MM-DD format. For example, 2013-01-15. If the start date is left empty, the subscription begins immediately. - `tax_percentage` string — The tax to add when billing the subscription. The percentage is expressed in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign. For example, a value of 7.5 corresponds to 7.5%. - `timezone` string — The timezone that is used in date calculations for the subscription. If unset, defaults to the location timezone. If a timezone is not configured for the location, defaults to "America/New_York". Format: the IANA Timezone Database identifier for the location timezone. For a list of time zones, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). ## Response `200` Success - CreateSubscriptionResponse — Defines the fields that are included in the response from the [CreateSubscription](https://developer.squareup.com/reference/square_2021-08-18/subscriptions-api/create-subscription) endpoint. - `errors` Error[] — Information about errors encountered during the request. - `category` string, required — The high-level category for the error. - `code` string, required — The specific code of the error. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `subscription` Subscription — Represents a customer subscription to a subscription plan. For an overview of the `Subscription` type, see [Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). - `canceled_date` string — The subscription cancellation date, in YYYY-MM-DD format (for example, 2013-01-15). On this date, the subscription status changes to `CANCELED` and the subscription billing stops. If you don't set this field, the subscription plan dictates if and when subscription ends. You cannot update this field, you can only clear it. - `card_id` string — The ID of the [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) [card](https://developer.squareup.com/reference/square_2021-08-18/objects/Card) that is charged for the subscription. - `charged_through_date` string — The date up to which the customer is invoiced for the subscription, in YYYY-MM-DD format (for example, 2013-01-15). After the invoice is sent for a given billing period, this date will be the last day of the billing period. For example, suppose for the month of May a customer gets an invoice (or charged the card) on May 1. For the monthly billing scenario, this date is then set to May 31. - `created_at` string — The timestamp when the subscription was created, in RFC 3339 format. - `customer_id` string — The ID of the associated [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) profile. - `id` string — The Square-assigned ID of the subscription. - `invoice_ids` string[] — The IDs of the [invoices](https://developer.squareup.com/reference/square_2021-08-18/objects/Invoice) created for the subscription, listed in order when the invoices were created (oldest invoices appear first). - `location_id` string — The ID of the location associated with the subscription. - `plan_id` string — The ID of the associated [subscription plan](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogSubscriptionPlan). - `price_override_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `start_date` string — The start date of the subscription, in YYYY-MM-DD format (for example, 2013-01-15). - `status` string — The current status of the subscription. - `tax_percentage` string — The tax amount applied when billing the subscription. The percentage is expressed in decimal form, using a `'.'` as the decimal separator and without a `'%'` sign. For example, a value of `7.5` corresponds to 7.5%. - `timezone` string — Timezone that will be used in date calculations for the subscription. Defaults to the timezone of the location based on `location_id`. Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`). - `version` integer — The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting. --- [API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/versions/8d95e3639487/schema)