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
Attributes
Subscription object
Attribute
id string
The unique object identifier.
customer string
The ID of the customer who will be billed with this subscription.
document string
The ID of the document type for this subscription.
​
Learn more about document types.
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.
1
{
2
    "id": "sub_OaZp2cDQ7ph1y7Mxzn",
3
    "document": "US1",
4
    "customer": {
5
        "id": "cus_APxT9s7X12ilP9Zx9O",
6
        "name": "Acme Nation LLC",
7
        "address": "17st, National Sub",
8
        "state": "IL",
9
        "country": "US",
10
        "phone": null,
11
        "email": "[email protected]",
12
        "website": "https://www.stark.com",
13
        "aggregations": {
14
          "balance": 5756.00,
15
          "sales": 14324.36,
16
          "sales_current_period": 1873.00
17
        },
18
        "tax_settings": {},
19
        "metadata": {},
20
        "created": "2020-05-12 15:42:09",
21
        "updated": "2020-05-12 21:16:12"
22
    },
23
    "test_mode": false,
24
    "date_start": "2021-01-28",
25
    "end_date": null,
26
    "billing_cycles": null,
27
    "next_billing": "2021-02-28",
28
    "next_billing_cycle": 1,
29
    "previous_billing": null,
30
    "lines": [
31
        {
32
            "id": "lin_c7I7JP8I1W2axLybt8",
33
            "plan": {
34
                "id": "pla_kfRahy05LQ7MjtqZj8",
35
                "tiers": [],
36
                "sku": null,
37
                "name": "Awesome APP",
38
                "description": "Monthly charge subscription",
39
                "product": "pro_nZsj9TeVwHmvbnL8iE",
40
                "amount": 75.0,
41
                "tiers_mode": null,
42
                "exempt": false,
43
                "usage_scheme": "licensed",
44
                "usage_aggregation": null,
45
                "frequency": {
46
                    "id": "monthly",
47
                    "name": "Mensual"
48
                },
49
                "currency": {
50
                    "id": "USD",
51
                    "conversion": null,
52
                    "name": "American Dollar",
53
                    "name_en": "American Dollar",
54
                    "default": true,
55
                    "is_chargeable": true,
56
                    "available": true,
57
                    "rounded": false,
58
                    "country": "US"
59
                },
60
                "status": "active",
61
                "archived": null,
62
                "created": "2021-01-28T17:32:00.250476-03:00",
63
                "updated": "2021-01-28T17:32:00.250501-03:00",
64
            },
65
            "quantity": 1,
66
            "coupon": null,
67
            "coupon_redemptions": 0,
68
            "created": "2021-01-28T17:35:00.546879-03:00",
69
            "updated": "2021-01-28T17:35:00.546900-03:00"
70
        }
71
    ],
72
    "addons": [
73
        {
74
            "addon": {
75
                "id": "add_zA83APXQDm2tQZL7uo",
76
                "apply_scheme": "one_time",
77
                "duration_times": null,
78
                "sku": null,
79
                "name": "Setup",
80
                "description": "Setup service",
81
                "amount": 30.8,
82
                "currency": {
83
                    "id": "USD",
84
                    "conversion": false,
85
                    "name": "American Dollar",
86
                    "name_en": "American Dollar",
87
                    "default": true,
88
                    "is_chargeable": true,
89
                    "available": true,
90
                    "rounded": false,
91
                    "country": "US"
92
                },
93
                "metadata": {},
94
                "archived": null,
95
                "status": "active",
96
                "created": "2020-05-15T12:53:44.599408-04:00",
97
                "updated": "2020-06-11T07:54:15.463443-04:00",
98
            },
99
            "addon_redemptions": 0,
100
            "quantity": 1,
101
            "rates": []
102
        }
103
    ],
104
    "coupon": {
105
        "id": "cou_A93FUF5oJ89EwI0jOV",
106
        "discount_scheme": "%",
107
        "duration_scheme": "limited",
108
        "duration_times": 3,
109
        "name": "COVID-19 Discount campaign",
110
        "amount": 30.0,
111
        "valid_until": null,
112
        "apply_on": "invoice",
113
        "currency": {
114
            "id": "USD",
115
            "conversion": false,
116
            "name": "American Dollar",
117
            "name_en": "American Dollar",
118
            "default": true,
119
            "is_chargeable": true,
120
            "available": true,
121
            "rounded": false,
122
            "country": "US"
123
        },
124
        "metadata": {},
125
        "archived": null,
126
        "status": "active",
127
        "created": "2020-05-15T12:54:31.846353-04:00",
128
        "updated": "2020-05-15T12:54:31.846375-04:00",
129
    }
130
    "coupon_redemptions": 0,
131
    "expiration_days": 15,
132
    "references": [],
133
    "note": "",
134
    "metadata": {},
135
    "tax_settings": {},
136
    "status": "active",
137
    "paused": null,
138
    "paused_reason": null,
139
    "cancelled": null,
140
    "cancel_reason": null,
141
    "created": "2021-01-28T17:35:00.522129-03:00",
142
    "updated": "2021-01-28T19:02:05.771129-03:00"
143
}
Copied!
Subscription line object
Attributes
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.
1
{
2
    "id": "lin_c7I7JP8I1W2axLybt8",
3
    "plan": {
4
        "id": "pla_kfRahy05LQ7MjtqZj8",
5
        "tiers": [],
6
        "sku": null,
7
        "name": "Awesome APP",
8
        "description": "Monthly charge subscription",
9
        "product": "pro_nZsj9TeVwHmvbnL8iE",
10
        "amount": 75.0,
11
        "tiers_mode": null,
12
        "exempt": false,
13
        "usage_scheme": "licensed",
14
        "usage_aggregation": null,
15
        "frequency": {
16
            "id": "monthly",
17
            "name": "Mensual"
18
        },
19
        "currency": {
20
            "id": "USD",
21
            "conversion": null,
22
            "name": "American Dollar",
23
            "name_en": "American Dollar",
24
            "default": true,
25
            "is_chargeable": true,
26
            "available": true,
27
            "rounded": false,
28
            "country": "US"
29
        },
30
        "status": "active",
31
        "archived": null,
32
        "created": "2021-01-28T17:32:00.250476-03:00",
33
        "updated": "2021-01-28T17:32:00.250501-03:00",
34
    },
35
    "quantity": 1,
36
    "coupon": null,
37
    "coupon_redemptions": 0,
38
    "created": "2021-01-28T17:35:00.546879-03:00",
39
    "updated": "2021-01-28T17:35:00.546900-03:00"
40
}
Copied!
Subscription addon object
Attributes
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.
1
{
2
    "addon": {
3
        "id": "add_zA83APXQDm2tQZL7uo",
4
        "apply_scheme": "one_time",
5
        "duration_times": null,
6
        "sku": null,
7
        "name": "Setup",
8
        "description": "Setup service",
9
        "amount": 30.8,
10
        "currency": {
11
            "id": "USD",
12
            "conversion": false,
13
            "name": "American Dollar",
14
            "name_en": "American Dollar",
15
            "default": true,
16
            "is_chargeable": true,
17
            "available": true,
18
            "rounded": false,
19
            "country": "US"
20
        },
21
        "metadata": {},
22
        "archived": null,
23
        "status": "active",
24
        "created": "2020-05-15T12:53:44.599408-04:00",
25
        "updated": "2020-06-11T07:54:15.463443-04:00",
26
    },
27
    "addon_redemptions": 0,
28
    "quantity": 1,
29
    "rates": []
30
}
Copied!
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.
Attributes
Subscription addon rate object
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.
1
{
2
    "billing_cycle": 1,
3
    "percentage": 50.0,
4
    "description": "First share payment"
5
}
Copied!
post
https://api.piriod.com
/subscriptions/
Create a subscription
get
https://api.piriod.com
/subscriptions/{id}/
Retrieve a subscription
patch
https://api.piriod.com
/subscriptions/{id}/
Update a subscription
delete
https://api.piriod.com
/subscriptions/{id}/
Destroy a subscription
Subscriptions - Previous
Coupons
Next - Subscriptions
Usages
Last modified 1yr ago
Copy link
Contents
Subscription object
Subscription line object
Subscription addon object
Subscription addon rate object
post
Create a subscription
get
Retrieve a subscription
patch
Update a subscription
delete
Destroy a subscription