Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB
Subscriptions

CreateSubscription

Enrolls a customer in a subscription.

If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square sends 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.

For more information, see Create a subscription.

post/v2/subscriptions

Request body

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_variation_idstring

The ID of the subscription plan variation created using the Catalog API.

customer_idstring required

The ID of the customer subscribing to the subscription plan variation.

start_datestring

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

canceled_datestring

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 variation 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 completes, the specified canceled_date sets the date when the subscription stops through the end of the last cycle.

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

card_idstring

The ID of the subscriber's card to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription.

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.

monthly_billing_anchor_dateinteger

The day-of-the-month to change the billing date to.

Example request

{
  "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
  "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
  "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
  "location_id": "S8GWD5R9QB376",
  "phases": [
    {
      "order_template_id": "U2NaowWxzXwpsZU697x7ZHOAnCNZY",
      "ordinal": 0
    }
  ],
  "plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H",
  "source": {
    "name": "My Application"
  },
  "start_date": "2023-06-20",
  "timezone": "America/Los_Angeles"
}

Response

Success

Example response

{
  "subscription": {
    "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
    "created_at": "2023-06-20T21:53:10Z",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f",
    "location_id": "S8GWD5R9QB376",
    "phases": [
      {
        "order_template_id": "U2NaowWxzXwpsZU697x7ZHOAnCNZY",
        "ordinal": 0,
        "plan_phase_uid": "X2Q2AONPB3RB64Y27S25QCZP",
        "uid": "873451e0-745b-4e87-ab0b-c574933fe616"
      }
    ],
    "plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "source": {
      "name": "My Application"
    },
    "start_date": "2023-06-20",
    "status": "ACTIVE",
    "timezone": "America/Los_Angeles",
    "version": 1
  }
}