Subscriptions represent a relationship between a customer and your pricing plans. The subscription allows to bill and charge a customer on a recurring basis.
Attributes
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.
collection_scheme
string
Defines how the subscription should be processed, whether it should first create the invoice or first attempt to charge the customer's card. This is useful when you don't want to have outstanding invoices, as if the field is set to charge_payment and the charge fails, the invoice will not be created until a successful retry is made.
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 objects for this subscription.
addons
array
The list of objects for this subscription.
coupon
string
The ID of the 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
Reference list
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.
Object sample
{
"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"
}