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
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "billing@stark.com",
"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"
}
Subscription line object
{
"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"
}
Subscription addon object
{
"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": []
}
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.
{
"billing_cycle": 1,
"percentage": 50.0,
"description": "First share payment"
}
Create a subscription
POST
https://api.piriod.com/subscriptions/
Creates a new Subscription object.
Request Body
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "billing@stark.com",
"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": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "billing@stark.com",
"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
Request Body
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "billing@stark.com",
"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
Query Parameters
{
"id": "sub_OaZp2cDQ7ph1y7Mxzn",
"document": "US1",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "billing@stark.com",
"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