• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Create subscription

POST /v2/subscriptions

Creates a subscription to a subscription plan by a customer.

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

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.
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 created using the Catalog API. For more information, see Set Up and Manage a Subscription Plan and Subscriptions Walkthrough.

Min Length 1
customer_id
string
Required

The ID of the customer subscribing to the subscription plan.

Min Length 1
start_date
string

The YYYY-MM-DD-formatted date to start the subscription. If it is unspecified, the subscription starts immediately.
canceled_date
string

The YYYY-MM-DD-formatted date when the newly created subscription is scheduled for cancellation.

This date overrides the cancellation date set in the plan configuration. If the cancellation date is earlier than the end date of a subscription cycle, the subscription stops at the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle.

When the subscription plan of the newly created subscription has a fixed number of cycles and the canceled_date occurs before the subscription plan expires, the specified canceled_date sets the date when the subscription stops through the end of the last cycle.
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 subscriber's card to charge. If it is not specified, the subscriber receives an invoice via email. For an example to create a customer profile for a subscriber 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.
source
SubscriptionSource
Beta

The origination details of the subscription.

Response Fields
Name Description
errors
Error [ ]

Errors encountered during the request.
subscription
Subscription

The newly created subscription.

For more information, see Subscription object.

Examples

You are viewing an old version of the API
POST /v2/subscriptions
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/subscriptions \
  -X POST \
  -H 'Square-Version: 2022-09-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": "2021-10-20",
    "tax_percentage": "5",
    "price_override_money": {
      "amount": 100,
      "currency": "USD"
    },
    "timezone": "America/Los_Angeles",
    "source": {
      "name": "My App"
    }
  }'
Response JSON 
{
  "subscription": {
    "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f",
    "location_id": "S8GWD5R9QB376",
    "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "start_date": "2021-10-20",
    "status": "PENDING",
    "tax_percentage": "5",
    "price_override_money": {
      "amount": 100,
      "currency": "USD"
    },
    "version": 1594155459464,
    "created_at": "2021-10-20T21:53:10Z",
    "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
    "timezone": "America/Los_Angeles",
    "source": {
      "name": "My App"
    }
  }
}

Error Descriptions
400 Bad request CUSTOMER_NOT_FOUND

The provided customer id can't be found in the merchant's customers list.

 >
400 Bad request CUSTOMER_MISSING_NAME

The provided customer does not have a recorded name.

 >
400 Bad request CUSTOMER_MISSING_EMAIL

The provided customer does not have a recorded email.

 >
400 Bad request INVALID_DATE

The subscription cannot be paused/resumed on the given date.

 >
403 Forbidden CARD_PROCESSING_NOT_ENABLED

The location provided in the API call is not enabled for credit card processing.

 >
403 Forbidden 
{
  "errors": [
    {
      "code": "CARD_PROCESSING_NOT_ENABLED",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}