Attributes

id int

Unique identifier of the object.

address int

Unique identifier of the associated shipping Address. expandable

plan int

Unique identifier of the associated Plan. expandable

coupon int

Unique identifier of the associated Coupon. expandable

default_source int

Unique identifier of the default Source used to pay for this specific subscription. If not set, the default payment method set on Customer will be used instead. expandable

latest_invoice int

Unique identifier of the most recent Invoice. expandable

address_required bool

Based on current product configuration or if taxes module is enabled, this will either be true or false. See the Address documentation for more information.

billing string

The collection method of this subscription. Possible values are either charge_automatically, or send_invoice. When set to charge_automatically payment for this subscription will be automatically attempted using the default source specified on subscription level or else, on the default source attached to the Customer.

cancel_at timestamp

If non-null, this is the Unix timestamp at which the subscription was requested to be cancelled.

cancel_at_period_end bool

A boolean on whether the subscription will be canceled or not at the end of the current period. For subscriptions with multiple phases, please refer to the auto_renew attribute which denotes the final autorenewal behavior for the subscription, considering all future phases.

canceled_at timestamp

If non-null, this is the Unix timestamp at which the subscription was requested to be canceled.

canceled_by int

If non-null, this will either contain the customer id or the collaborator id who requested the cancellation.

canceled_by_type string

Depending on how the cancellation was initiated, this will contain either:
'System' - In case of organic expiry
'Customer' - In case of customer-initiated cancellation
'Publisher' - In case of collaborator-initiated cancellation
'Agency' - In case of agency collaborator-initiated cancellation

created timestamp

The Unix timestamp at which the subscription was created in the system.

current_period_end timestamp

The end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

current_period_start timestamp

Unix timestamp representing the start of the current period that the subscription has been invoiced for.

days_until_due int

Number of days a customer has to pay invoices generated by this subscription. This value will be null for subscriptions where billing=charge_automatically.

ended_at timestamp

If non-null, this is the Unix timestamp at which the subscription has ended.

quantity int

status string

Indicates the current status of the subscription. Possible values are active, incomplete, incomplete_expired, trialing, past_due, canceled, or unpaid.

incomplete and incomplete_expired

For billing=charge_automatically only, a subscription moves into incomplete if the initial payment attempt fails.

Once the first invoice is paid, the subscription moves into an active state. If the first invoice is not paid within 23 hours, the subscription status transitions to incomplete_expired. This is a terminal state, the open invoice will be voided and no further invoices will be generated.

trialing

A subscription having this status moves to active when the trial period is over.

past_due

If subscription billing=send_invoice it becomes past_due when its invoice is not paid by the due date, and canceled or unpaid (depending on your subscriptions settings) if it is still not paid by an additional deadline after that.
If subscription billing=charge_automatically it becomes past_due when payment to renew it fails and canceled or unpaid (depending on your subscriptions settings) when all payment retry attempts are exhausted.

trial_end timestamp

If non-null, this is the Unix timestamp at which the subscription's trial period will end.

trial_start timestamp

If non-null, this is the Unix timestamp at which the subscription's trial period started.

is_gift_donor bool

A boolean on whether this subscription related to a gift donor.

is_gift_recipient bool

A boolean on whether this subscription related to a gift recipient.

gift_code string

The gift code.

is_redeemed bool

A boolean on whether the recipient's gift was redeemed or not.

cancel_reason string

If non-null, the reason provided when the cancellation request was received.

shipments_remaining int

The number of shipments remaining on this subscription. This value is initiated with a 0 amount. Once an invoice is created, the shipments_per_interval from the plan is added to the shipments_remaining amount, this occurs on the first invoice of the plan but also on all subsequent invoices that are created automatically by the subscription. For more information, please read the Shipments guide.

schedule Schedule

Always expanded, this represents the active Schedule object related to that subscription.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

expires_at timestamp

If non-null, this is the Unix timestamp at which the subscription will expire. This also takes into account any active schedule in place.

renews_at timestamp

If non-null, this is the Unix timestamp at which the subscription will renew. This also takes into account any active schedule in place.

shipments_undeliverable bool

A boolean on whether shipments is undeliverable or deliverable.

shipments_suspended_until timestamp

Unix timestamp representing the exact time until the subscription's shipments are suspended.

auto_renew bool

A boolean that determines whether the subscription will auto-renew or not at the end of the last phase. (overrides the plan configuration when set)

source string

Subscription source (Phone, Email, Web).

start_date timestamp

Unix timestamp representing the exact time when the subscription was first created. This date might differ from the creation date due to backdating.

is_imported bool

Define if the subscription is imported or not.