API Reference

Subscription object

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"
}