You are viewing an old version of the API

All Versions

Create subscription BETA

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.

Permissions

CUSTOMERS_READ

PAYMENTS_WRITE

SUBSCRIPTIONS_WRITE

ITEMS_READ

ORDERS_WRITE

INVOICES_WRITE

Guide

Subscriptions Guide Try in API Explorer

Request Body

Example code

Name	Description
`idempotency_key string` Required	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. Min Length 1
`location_id string` Required	The ID of the location the subscription is associated with. Min Length 1
`plan_id string` Required	The ID of the subscription plan. For more information, see Subscription Plan Overview. Min Length 1
`customer_id string` Required	The ID of the customer profile. Min Length 1
`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.
`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.
`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%. Max Length 10
`price_override_money Money`	A custom price to apply for the subscription. If specified, it overrides the price configured by the subscription plan.
`card_id string`	The ID of the customer 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.
`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.

Response Fields

Name	Description
`errors Error [ ]`	Information about errors encountered during the request.
`subscription Subscription`	The newly created subscription. For more information, see Subscription object.

Examples

curl https://connect.squareup.com/v2/subscriptions \
  -X POST \
  -H 'Square-Version: 2021-01-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
    "location_id": "S8GWD5R9QB376",
    "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
    "start_date": "2020-08-01",
    "tax_percentage": "5",
    "price_override_money": {
      "amount": 100,
      "currency": "USD"
    },
    "timezone": "America/Los_Angeles"
  }'

{
  "subscription": {
    "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f",
    "location_id": "S8GWD5R9QB376",
    "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "start_date": "2020-08-01",
    "status": "PENDING",
    "tax_percentage": "5",
    "price_override_money": {
      "amount": 100,
      "currency": "USD"
    },
    "version": 1594155459464,
    "created_at": "2020-08-03T21:53:10Z",
    "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
    "timezone": "America/Los_Angeles"
  }
}

Subscriptions API You are viewing an old version of the API 2021-01-21 Version 2021-01-21 All Versions Subscriptions API Create subscription BETA

Request Body

Response Fields

Examples

Share Feedback

You are viewing an old version of the API

All Versions

Create subscription BETA