subscriptions_api = client.subscriptionsSubscriptionsApi
- Create Subscription
- Search Subscriptions
- Retrieve Subscription
- Update Subscription
- Delete Subscription Action
- Cancel Subscription
- List Subscription Events
- Pause Subscription
- Resume Subscription
- Swap Plan
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.
def create_subscription(self,
body)| Parameter | Type | Tags | Description |
|---|---|---|---|
body |
Create Subscription Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
body = {}
body['idempotency_key'] = '8193148c-9586-11e6-99f9-28cfe92138cf'
body['location_id'] = 'S8GWD5R9QB376'
body['plan_id'] = '6JHXF3B2CW3YKHDV4XEM674H'
body['customer_id'] = 'CHFGVKYY8RSV93M5KCYTG4PN0G'
body['start_date'] = '2021-10-20'
body['canceled_date'] = 'canceled_date0'
body['tax_percentage'] = '5'
body['price_override_money'] = {}
body['price_override_money']['amount'] = 100
body['price_override_money']['currency'] = 'USD'
body['card_id'] = 'ccof:qy5x8hHGYsgLrp4Q4GB'
body['timezone'] = 'America/Los_Angeles'
body['source'] = {}
body['source']['name'] = 'My App'
result = subscriptions_api.create_subscription(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Searches for subscriptions.
Results are ordered chronologically by subscription creation date. If the request specifies more than one location ID, the endpoint orders the result by location ID, and then by creation date within each location. If no locations are given in the query, all locations are searched.
You can also optionally specify customer_ids to search by customer.
If left unset, all customers
associated with the specified locations are returned.
If the request specifies customer IDs, the endpoint orders results
first by location, within location by customer ID, and within
customer by subscription creation date.
For more information, see Retrieve subscriptions.
def search_subscriptions(self,
body)| Parameter | Type | Tags | Description |
|---|---|---|---|
body |
Search Subscriptions Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
body = {}
body['cursor'] = 'cursor0'
body['limit'] = 164
body['query'] = {}
body['query']['filter'] = {}
body['query']['filter']['customer_ids'] = ['CHFGVKYY8RSV93M5KCYTG4PN0G']
body['query']['filter']['location_ids'] = ['S8GWD5R9QB376']
body['query']['filter']['source_names'] = ['My App']
body['include'] = ['include4', 'include5', 'include6']
result = subscriptions_api.search_subscriptions(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Retrieves a subscription.
def retrieve_subscription(self,
subscription_id,
include=None)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to retrieve. |
include |
string |
Query, Optional | A query parameter to specify related information to be included in the response. The supported query parameter values are: - actions: to include scheduled actions on the targeted subscription. |
Retrieve Subscription Response
subscription_id = 'subscription_id0'
include = 'include2'
result = subscriptions_api.retrieve_subscription(subscription_id, include)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Updates a subscription. You can set, modify, and clear the
subscription field values.
def update_subscription(self,
subscription_id,
body)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to update. |
body |
Update Subscription Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
subscription_id = 'subscription_id0'
body = {}
body['subscription'] = {}
body['subscription']['id'] = 'id8'
body['subscription']['location_id'] = 'location_id2'
body['subscription']['plan_id'] = 'plan_id0'
body['subscription']['customer_id'] = 'customer_id6'
body['subscription']['start_date'] = 'start_date2'
body['subscription']['tax_percentage'] = 'null'
body['subscription']['price_override_money'] = {}
body['subscription']['price_override_money']['amount'] = 2000
body['subscription']['price_override_money']['currency'] = 'USD'
body['subscription']['version'] = 1594155459464
result = subscriptions_api.update_subscription(subscription_id, body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Deletes a scheduled action for a subscription.
def delete_subscription_action(self,
subscription_id,
action_id)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription the targeted action is to act upon. |
action_id |
string |
Template, Required | The ID of the targeted action to be deleted. |
Delete Subscription Action Response
subscription_id = 'subscription_id0'
action_id = 'action_id6'
result = subscriptions_api.delete_subscription_action(subscription_id, action_id)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Schedules a CANCEL action to cancel an active subscription
by setting the canceled_date field to the end of the active billing period
and changing the subscription status from ACTIVE to CANCELED after this date.
def cancel_subscription(self,
subscription_id)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to cancel. |
subscription_id = 'subscription_id0'
result = subscriptions_api.cancel_subscription(subscription_id)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Lists all events for a specific subscription.
In the current implementation, only START_SUBSCRIPTION and STOP_SUBSCRIPTION (when the subscription was canceled) events are returned.
def list_subscription_events(self,
subscription_id,
cursor=None,
limit=None)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to retrieve the events for. |
cursor |
string |
Query, Optional | When the total number of resulting subscription events exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results. For more information, see Pagination. |
limit |
int |
Query, Optional | The upper limit on the number of subscription events to return in a paged response. |
List Subscription Events Response
subscription_id = 'subscription_id0'
cursor = 'cursor6'
limit = 172
result = subscriptions_api.list_subscription_events(subscription_id, cursor, limit)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Schedules a PAUSE action to pause an active subscription.
def pause_subscription(self,
subscription_id,
body)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to pause. |
body |
Pause Subscription Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
subscription_id = 'subscription_id0'
body = {}
body['pause_effective_date'] = 'pause_effective_date6'
body['pause_cycle_duration'] = 94
body['resume_effective_date'] = 'resume_effective_date4'
body['resume_change_timing'] = 'IMMEDIATE'
body['pause_reason'] = 'pause_reason2'
result = subscriptions_api.pause_subscription(subscription_id, body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Schedules a RESUME action to resume a paused or a deactivated subscription.
def resume_subscription(self,
subscription_id,
body)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to resume. |
body |
Resume Subscription Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
subscription_id = 'subscription_id0'
body = {}
body['resume_effective_date'] = 'resume_effective_date4'
body['resume_change_timing'] = 'IMMEDIATE'
result = subscriptions_api.resume_subscription(subscription_id, body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)Schedules a SWAP_PLAN action to swap a subscription plan in an existing subscription.
def swap_plan(self,
subscription_id,
body)| Parameter | Type | Tags | Description |
|---|---|---|---|
subscription_id |
string |
Template, Required | The ID of the subscription to swap the subscription plan for. |
body |
Swap Plan Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
subscription_id = 'subscription_id0'
body = {}
body['new_plan_id'] = 'new_plan_id2'
result = subscriptions_api.swap_plan(subscription_id, body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)