Subscriptions
Subscriptions represent a relationship between a customer and your pricing plans. The subscription allows to bill and charge a customer on a recurring basis.
Subscription object
Attribute
id string
The unique object identifier.
customer string
The ID of the customer who will be billed with this subscription.
test_mode boolean
Has the value true if the object exists in production mode or the value false if the object exists in test mode.
date_start date
Subscription start date. It can be a present or future date.
end_date date
Subscription termination date computed based on billing cycles.
billing_cycles number
Number of billing cycles for this subscription. If you want to bill a monthly plan for 12 months, billing cycles must be 12. Leave this field null so that the subscription is billed in unlimited cycles.
next_billing date
Date of the next billing cycle.
next_billing_cycle number
Number of the next billing cycle.
previous_billing date
Date of the last billing cycle already billed.
lines array
The list of subscription line objects for this subscription.
addons array
The list of subscription addon objects for this subscription.
coupon string
The ID of the coupon object to discount the total invoiced of this subscription. Only coupons with apply_on: invoice are applicable.
coupon_redemptions number
Number of times the coupon has been applied to the subscription.
expiration_days number
Days after billing to wait for payment before starting to send automatic payment reminders.
references array
note string
Free note to indicate something on the invoice.
metadata object
An object with key pairs for store custom information about this subscription.
status string
Status of this subscription, one of active, paused, cancelled, finalized.
paused datetime
Subscription pause datetime if the subscription status is paused.
paused_reason string
Subscription pause reason if the subscription status is paused, one of tax_agency_failed.
cancelled datetime
Subscription cancelled datetime if the subscription status is cancelled.
cancel_reason string
Subscription cancel reason if the subscription status is cancelled, one of not_specified, not_paid, no_card, fraud_review_failed, non_compliant_customer.
created datetime
Date and time of the creation of this subscription.
updated datetime
Date and time of the last update of this subscription.
Subscription line object
Attribute
id string
The unique object identifier.
plan string
The ID of the plan object for this subscription line.
quantity decimal
Quantity of the plan to be billed.
coupon string
The ID of the coupon object to discount the plan for this subscription line. Only coupons with apply_on: line are applicable.
coupon_redemptions number
Number of times the coupon has been applied to the subscription line.
created datetime
Date and time of the creation of this subscription line.
updated datetime
Date and time of the last update of this subscription line.
Subscription addon object
Attribute
id string
The unique object identifier.
addon string
The ID of the addon object for this subscription line.
addon_redemptions number
Number of times the addon has been applied to the subscription.
quantity decimal
Quantity of the addon to be billed.
rates array
The list of subscription addon rate objects for this subscription addon. Only applicable for addons with apply_scheme: one_time.
Subscription addon rate object
Subscription addon rates allows to divide the billing of a addon in multiple shares and determine its billing in specific cycles.
Attribute
billing_cycle number
Number of the billing cycle in which this rate must be invoiced.
percentage decimal
Percentage of the amount of the addon that must be invoiced with this rate.
description string
Free description about the rate to indicate to the customer.
Create a subscription
POST https://api.piriod.com/subscriptions/
Creates a new Subscription object.
Request Body
customer
string
ID of related Customer object.
date_start
string
Date for the start of the subscription. Format YYYY-DD-MM.
document
string
The ID of the document type this subscription should create.
expiration_days
number
Limit days to wait for subscription payment before starting to send payment reminders. Default is 10.
lines
array
A list of Subscription Line objects.
addons
array
A list of Subscription Addon objects.
coupon
string
ID of related Coupon object. Must be compatible with apply_on=subscription.
note
string
A simple text with a 100 characters as max length.
test_mode
boolean
True or false if the subscription is to be created to account test environment. Default is false.
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "[email protected]",
"website": "https://www.stark.com",
"aggregations": {
"balance": 5756.00,
"sales": 14324.36,
"sales_current_period": 1873.00
},
"tax_settings": {},
"metadata": {},
"created": "2020-05-12 15:42:09",
"updated": "2020-05-12 21:16:12"
},
"test_mode": false,
"date_start": "2021-01-28",
"end_date": null,
"billing_cycles": null,
"next_billing": "2021-02-28",
"next_billing_cycle": 1,
"previous_billing": null,
"lines": [
{
"id": "lin_c7I7JP8I1W2axLybt8",
"plan": {
"id": "pla_kfRahy05LQ7MjtqZj8",
"tiers": [],
"sku": null,
"name": "Awesome APP",
"description": "Monthly charge subscription",
"product": "pro_nZsj9TeVwHmvbnL8iE",
"amount": 75.0,
"tiers_mode": null,
"exempt": false,
"usage_scheme": "licensed",
"usage_aggregation": null,
"frequency": {
"id": "monthly",
"name": "Mensual"
},
"currency": {
"id": "USD",
"conversion": null,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"status": "active",
"archived": null,
"created": "2021-01-28T17:32:00.250476-03:00",
"updated": "2021-01-28T17:32:00.250501-03:00",
},
"quantity": 1,
"coupon": null,
"coupon_redemptions": 0,
"created": "2021-01-28T17:35:00.546879-03:00",
"updated": "2021-01-28T17:35:00.546900-03:00"
}
],
"addons": [
{
"addon": {
"id": "add_zA83APXQDm2tQZL7uo",
"apply_scheme": "one_time",
"duration_times": null,
"sku": null,
"name": "Setup",
"description": "Setup service",
"amount": 30.8,
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:53:44.599408-04:00",
"updated": "2020-06-11T07:54:15.463443-04:00",
},
"addon_redemptions": 0,
"quantity": 1,
"rates": []
}
],
"coupon": {
"id": "cou_A93FUF5oJ89EwI0jOV",
"discount_scheme": "%",
"duration_scheme": "limited",
"duration_times": 3,
"name": "COVID-19 Discount campaign",
"amount": 30.0,
"valid_until": null,
"apply_on": "invoice",
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:54:31.846353-04:00",
"updated": "2020-05-15T12:54:31.846375-04:00",
}
"coupon_redemptions": 0,
"expiration_days": 15,
"references": [],
"note": "",
"metadata": {},
"tax_settings": {},
"status": "active",
"paused": null,
"paused_reason": null,
"cancelled": null,
"cancel_reason": null,
"created": "2021-01-28T17:35:00.522129-03:00",
"updated": "2021-01-28T19:02:05.771129-03:00"
}Retrieve a subscription
GET https://api.piriod.com/subscriptions/{id}/
This endpoint retrieves a subscription.
Path Parameters
id
string
The ID of the subscription object.
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "[email protected]",
"website": "https://www.stark.com",
"aggregations": {
"balance": 5756.00,
"sales": 14324.36,
"sales_current_period": 1873.00
},
"tax_settings": {},
"metadata": {},
"created": "2020-05-12 15:42:09",
"updated": "2020-05-12 21:16:12"
},
"test_mode": false,
"date_start": "2021-01-28",
"end_date": null,
"billing_cycles": null,
"next_billing": "2021-02-28",
"next_billing_cycle": 1,
"previous_billing": null,
"lines": [
{
"id": "lin_c7I7JP8I1W2axLybt8",
"plan": {
"id": "pla_kfRahy05LQ7MjtqZj8",
"tiers": [],
"sku": null,
"name": "Awesome APP",
"description": "Monthly charge subscription",
"product": "pro_nZsj9TeVwHmvbnL8iE",
"amount": 75.0,
"tiers_mode": null,
"exempt": false,
"usage_scheme": "licensed",
"usage_aggregation": null,
"frequency": {
"id": "monthly",
"name": "Mensual"
},
"currency": {
"id": "USD",
"conversion": null,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"status": "active",
"archived": null,
"created": "2021-01-28T17:32:00.250476-03:00",
"updated": "2021-01-28T17:32:00.250501-03:00",
},
"quantity": 1,
"coupon": null,
"coupon_redemptions": 0,
"created": "2021-01-28T17:35:00.546879-03:00",
"updated": "2021-01-28T17:35:00.546900-03:00"
}
],
"addons": [
{
"addon": {
"id": "add_zA83APXQDm2tQZL7uo",
"apply_scheme": "one_time",
"duration_times": null,
"sku": null,
"name": "Setup",
"description": "Setup service",
"amount": 30.8,
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:53:44.599408-04:00",
"updated": "2020-06-11T07:54:15.463443-04:00",
},
"addon_redemptions": 0,
"quantity": 1,
"rates": []
}
],
"coupon": {
"id": "cou_A93FUF5oJ89EwI0jOV",
"discount_scheme": "%",
"duration_scheme": "limited",
"duration_times": 3,
"name": "COVID-19 Discount campaign",
"amount": 30.0,
"valid_until": null,
"apply_on": "invoice",
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:54:31.846353-04:00",
"updated": "2020-05-15T12:54:31.846375-04:00",
}
"coupon_redemptions": 0,
"expiration_days": 15,
"references": [],
"note": "",
"metadata": {},
"tax_settings": {},
"status": "active",
"paused": null,
"paused_reason": null,
"cancelled": null,
"cancel_reason": null,
"created": "2021-01-28T17:35:00.522129-03:00",
"updated": "2021-01-28T19:02:05.771129-03:00"
}Update a subscription
PATCH https://api.piriod.com/subscriptions/{id}/
This endpoint updates a subscription.
Path Parameters
id
string
The ID of the subscription object.
Request Body
coupon
string
The ID of the coupon to this subscription.
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "[email protected]",
"website": "https://www.stark.com",
"aggregations": {
"balance": 5756.00,
"sales": 14324.36,
"sales_current_period": 1873.00
},
"tax_settings": {},
"metadata": {},
"created": "2020-05-12 15:42:09",
"updated": "2020-05-12 21:16:12"
},
"test_mode": false,
"date_start": "2021-02-28",
"end_date": null,
"billing_cycles": null,
"next_billing": "2021-02-28",
"next_billing_cycle": 1,
"previous_billing": null,
"lines": [
{
"id": "lin_c7I7JP8I1W2axLybt8",
"plan": {
"id": "pla_kfRahy05LQ7MjtqZj8",
"tiers": [],
"sku": null,
"name": "Awesome APP",
"description": "Monthly charge subscription",
"product": "pro_nZsj9TeVwHmvbnL8iE",
"amount": 75.0,
"tiers_mode": null,
"exempt": false,
"usage_scheme": "licensed",
"usage_aggregation": null,
"frequency": {
"id": "monthly",
"name": "Mensual"
},
"currency": {
"id": "USD",
"conversion": null,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"status": "active",
"archived": null,
"created": "2021-01-28T17:32:00.250476-03:00",
"updated": "2021-01-28T17:32:00.250501-03:00",
},
"quantity": 1,
"coupon": null,
"coupon_redemptions": 0,
"created": "2021-01-28T17:35:00.546879-03:00",
"updated": "2021-01-28T17:35:00.546900-03:00"
}
],
"addons": [
{
"addon": {
"id": "add_zA83APXQDm2tQZL7uo",
"apply_scheme": "one_time",
"duration_times": null,
"sku": null,
"name": "Setup",
"description": "Setup service",
"amount": 30.8,
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:53:44.599408-04:00",
"updated": "2020-06-11T07:54:15.463443-04:00",
},
"addon_redemptions": 0,
"quantity": 1,
"rates": []
}
],
"coupon": null,
"coupon_redemptions": 0,
"expiration_days": 15,
"references": [],
"note": "",
"metadata": {},
"tax_settings": {},
"status": "active",
"paused": null,
"paused_reason": null,
"cancelled": null,
"cancel_reason": null,
"created": "2021-01-28T17:35:00.522129-03:00",
"updated": "2021-01-28T19:02:05.771129-03:00"
}Destroy a subscription
DELETE https://api.piriod.com/subscriptions/{id}/
Cancel a subscription.
Path Parameters
id
string
The ID of the subscription object.
Query Parameters
cancel_reason_description
string
Reason for cancellation, one of not_specified, not_paid, no_card, fraud_review_failed, non_compliant_customer
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "[email protected]",
"website": "https://www.stark.com",
"aggregations": {
"balance": 5756.00,
"sales": 14324.36,
"sales_current_period": 1873.00
},
"tax_settings": {},
"metadata": {},
"created": "2020-05-12 15:42:09",
"updated": "2020-05-12 21:16:12"
},
"test_mode": false,
"date_start": "2021-01-28",
"end_date": null,
"billing_cycles": null,
"next_billing": "2021-02-28",
"next_billing_cycle": 1,
"previous_billing": null,
"lines": [
{
"id": "lin_c7I7JP8I1W2axLybt8",
"plan": {
"id": "pla_kfRahy05LQ7MjtqZj8",
"tiers": [],
"sku": null,
"name": "Awesome APP",
"description": "Monthly charge subscription",
"product": "pro_nZsj9TeVwHmvbnL8iE",
"amount": 75.0,
"tiers_mode": null,
"exempt": false,
"usage_scheme": "licensed",
"usage_aggregation": null,
"frequency": {
"id": "monthly",
"name": "Mensual"
},
"currency": {
"id": "USD",
"conversion": null,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"status": "active",
"archived": null,
"created": "2021-01-28T17:32:00.250476-03:00",
"updated": "2021-01-28T17:32:00.250501-03:00",
},
"quantity": 1,
"coupon": null,
"coupon_redemptions": 0,
"created": "2021-01-28T17:35:00.546879-03:00",
"updated": "2021-01-28T17:35:00.546900-03:00"
}
],
"addons": [
{
"addon": {
"id": "add_zA83APXQDm2tQZL7uo",
"apply_scheme": "one_time",
"duration_times": null,
"sku": null,
"name": "Setup",
"description": "Setup service",
"amount": 30.8,
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:53:44.599408-04:00",
"updated": "2020-06-11T07:54:15.463443-04:00",
},
"addon_redemptions": 0,
"quantity": 1,
"rates": []
}
],
"coupon": {
"id": "cou_A93FUF5oJ89EwI0jOV",
"discount_scheme": "%",
"duration_scheme": "limited",
"duration_times": 3,
"name": "COVID-19 Discount campaign",
"amount": 30.0,
"valid_until": null,
"apply_on": "invoice",
"currency": {
"id": "USD",
"conversion": false,
"name": "American Dollar",
"name_en": "American Dollar",
"default": true,
"is_chargeable": true,
"available": true,
"rounded": false,
"country": "US"
},
"metadata": {},
"archived": null,
"status": "active",
"created": "2020-05-15T12:54:31.846353-04:00",
"updated": "2020-05-15T12:54:31.846375-04:00",
}
"coupon_redemptions": 0,
"expiration_days": 15,
"references": [],
"note": "",
"metadata": {},
"tax_settings": {},
"status": "active",
"paused": null,
"paused_reason": null,
"cancelled": "2021-01-20T18:33:16.522129-03:00",
"cancel_reason": "no_card",
"created": "2021-01-28T17:35:00.522129-03:00",
"updated": "2021-01-28T19:02:05.771129-03:00"
}Last updated
Was this helpful?