Create subscription
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.
Name | Description |
---|---|
idempotency_
|
A unique string that identifies this For more information, see Idempotency keys. |
location_
Required
|
The ID of the location the subscription is associated with. |
plan_
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. |
customer_
Required
|
The ID of the customer subscribing to the subscription plan. |
start_
|
The |
canceled_
|
The 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 |
tax_
|
The tax to add when billing the subscription.
The percentage is expressed in decimal form, using a |
price_
|
A custom price to apply for the subscription. If specified, it overrides the price configured by the subscription plan. |
card_
|
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
|
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
Beta
|
The origination details of the subscription. |
Response Fields
Name | Description |
---|---|
errors
|
Errors encountered during the request. |
subscription
|
The newly created subscription. For more information, see Subscription object. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/subscriptions \
-X POST \
-H 'Square-Version: 2023-01-19' \
-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"
}
}'
{
"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_ The provided customer id can't be found in the merchant's customers list. |
> |
400 Bad request |
CUSTOMER_ The provided customer does not have a recorded name. |
> |
400 Bad request |
CUSTOMER_ The provided customer does not have a recorded email. |
> |
400 Bad request |
INVALID_ The subscription cannot be paused/resumed on the given date. |
> |
403 Forbidden |
CARD_ The location provided in the API call is not enabled for credit card processing. |
> |
{
"errors": [
{
"code": "CARD_PROCESSING_NOT_ENABLED",
"category": "INVALID_REQUEST_ERROR"
}
]
}