Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-142008071.1 MB
Subscriptions

CreateSubscription

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.

post/v2/subscriptions

Request body

canceled_datestring

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_idstring

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.

customer_idstring required

The ID of the customer profile.

idempotency_keystring

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_idstring required

The ID of the location the subscription is associated with.

plan_idstring 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.

start_datestring

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_percentagestring

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%.

timezonestring

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.

Example request

{
  "request_body": {
    "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
    "location_id": "S8GWD5R9QB376",
    "plan_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "price_override_money": {
      "amount": 100,
      "currency": "USD"
    },
    "start_date": "2020-08-01",
    "tax_percentage": "5",
    "timezone": "America/Los_Angeles"
  }
}

Response

Success

Example response

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