1. Billing
  2. Subscriptions

Subscriptions

subscriptions
copy
Click to Copy

A Chargebee subscription links a customer to products or services, defining what they have signed up for and how often they are charged.
Key components of a subscription:

  • A plan-item price.
  • Any addon and charge-item prices applied to the subscription.
  • Any coupons applied.
  • Any discounts applied.

The charges in a subscription are billed via invoices.

Related Tables

Tables referencing subscriptions.id
invoices subscription_discounts quotes subscription_mrr_changes contract_terms credit_notes subscription_charged_items quote_line_items subscription_item_tiers subscription_mrr_daily_summary subscription_coupons subscription_items invoice_line_items payment_source_mandates orders subscription_mrr_monthly_summary credit_note_line_items ramps transactions subscription_custom_fields

Columns

No match found
id string, not null
Primary Key
The unique identifier of the subscription table. You can specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.
payment_source_id string, null
Foreign Key payment_sources.id
The payment source attached to this subscription. If present, the customer's payment sources will not be used to collect any payment for this subscription.
customer_id string, not null
Foreign Key customers.id
The identifier of the customer associated with this subscription.
business_entity_id string, null
Foreign Key business_entities.id
The unique ID of the business entity for this subscription. This is always the same as the business entity of the customer.
activated_at timestamp, null
The time when the subscription's status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates.
active_id string, null
auto_close_invoices boolean, null
Set to false to override the site-level setting for auto-closing invoices for this subscription. This is only applicable when auto-closing invoices has been enabled for the site. This field has a higher precedence than the same field at the customer level.
cancel_reason string, null
The reason for canceling the subscription, automatically set by Chargebee.
cancel_reason_code string, null
The reason code for canceling the subscription. This value comes from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation.
cancel_schedule_created_at timestamp, null
This is the date/time when the most recent cancellation schedule for the subscription was created in Chargebee. This is applicable only for cancelled subscriptions or subscriptions scheduled for cancellation.
cancelled_at timestamp, null
The time when the subscription was canceled or is set to be canceled.
changes_scheduled_at timestamp, null
If a subscription change has been scheduled, this is the date/time when the change is set to take effect.
channel string, null
The subscription channel this object originated from and is maintained in.
contract_term_billing_cycle_on_renewal null
The number of billing cycles the new contract term runs for on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration.
create_pending_invoices boolean, null

Indicates whether the invoices for this subscription are generated with a pending status. This field is set to true automatically when the subscription has item prices that belong to metered items.

This is useful in the following scenarios:

  • When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
  • When you need to inspect all charges before closing invoices for this subscription.

Applicable only when Metered Billing is enabled for the site

created_at timestamp, null
The time when the subscription was created.
created_from_ip string, null
The IP address of the user. This is primarily used in Refersion integration for tracking/logging affiliate subscriptions.
currency_code string, not null
The currency code (ISO 4217 format) of the subscription.
current_term_end timestamp, null
The end of the current billing period for the subscription. The subscription is renewed immediately after this.
current_term_start timestamp, null
The start of the current billing period of the subscription.
free_period null
The period that extends the first term of the subscription free-of-charge. The value is a multiple of free_period_unit.
free_period_unit string, null
Defines the additional free period in association with the billing period.
has_scheduled_advance_invoices boolean, not null, default=false
Indicates whether the subscription has an advance invoicing schedule.
has_scheduled_changes boolean, not null, default=false

Indicates whether there are subscription changes scheduled for the next renewal.

invoice_notes string, null
A customer-facing note added to all invoices associated with this subscription. This note is among all the notes displayed on the invoice PDF.
meta_data string, null
net_term_days null
The Net D value explicitly set for this subscription. Net D is the number of days within which any invoice raised for the subscription must be paid. If this value is unavailable when an invoice is raised, the net_term_days defined at the customer level is considered.
next_billing_at timestamp, null
The date/time when the next billing for the subscription occurs. This is usually right after current_term_end unless multiple subscription terms were invoiced in advance using the terms_to_charge parameter.
override_relationship boolean, null
If true, the system ignores the hierarchy relationship and uses the customer as the payment and invoice owner.
pause_date timestamp, null
When a pause has been scheduled, it is the date/time of the scheduled pause. When the subscription is in the paused state, it is the date/time when the subscription was paused.
plan_amount_in_decimal string, null
The decimal representation of the total amount for the plan, in major units of the currency. This is always returned when multi-decimal pricing is enabled.
plan_free_quantity_in_decimal string, null
The free_quantity_in_decimal as set for the plan. This is returned for quantity-based plans when multi-decimal pricing is enabled.
plan_quantity_in_decimal string, null
The decimal representation of the quantity of the plan purchased. This is returned for quantity-based plans when multi-decimal pricing is enabled.
plan_unit_price_in_decimal string, null
The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. This is always returned when multi-decimal pricing is enabled.
po_number string, null
The purchase order number for this subscription.
referral_info_account_id string, null
The referral account ID.
referral_info_campaign_id string, null
The referral campaign ID.
referral_info_coupon_code string, null
The referral coupon code if available for the subscription.
referral_info_destination_url string, null
The destination URL for the referral campaign.
referral_info_external_campaign_id string, null
The referral external campaign ID.
referral_info_external_reference_id string, null
The external reference ID in the referral system for the subscription.
referral_info_friend_offer_type string, null
The friend offer type for the referral campaign.
referral_info_notify_referral_system string, null
Indicates whether to notify the referral system of purchases.
referral_info_post_purchase_widget_enabled boolean, null, default=true
Indicates whether the post-purchase widget is enabled for this campaign.
referral_info_referral_code string, null
The referral code if available for the subscription.
referral_info_referral_system string, null
The source referral system for the referral subscription.
referral_info_referrer_id string, null
The referrer ID if available for the subscription.
referral_info_referrer_reward_type string, null
The referrer reward type for the referral campaign.
referral_info_reward_status string, null, default=pending
The reward status for the referral subscription.
remaining_billing_cycles null
  • When the subscription is not on a contract term, this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
  • When the subscription is on a contract term, this value is the number of billing cycles remaining in the contract term after the current billing cycle.
resource_version long, null
The version number of this table. The resource_version is updated with a new timestamp in milliseconds for every change made to the table. This field is present only if the table was updated after 2016-09-28.
resume_date timestamp, null
For a paused subscription, this is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.
shipping_address_city string, null
The name of the city.
shipping_address_company string, null
The company name.
shipping_address_country string, null
The billing address country of the customer. This must be one of ISO 3166 alpha-2 country code.
shipping_address_email string, null
The email address.
shipping_address_first_name string, null
The first name of the contact.
shipping_address_index null
The index number of the subscription to which the item price is added. This is a unique number between 0 and 4 (inclusive) for each subscription that is created.
shipping_address_last_name string, null
The last name of the contact.
shipping_address_line1 string, null
Address line 1
shipping_address_line2 string, null
Address line 2
shipping_address_line3 string, null
Address line 3.
shipping_address_phone string, null
The phone number.
shipping_address_state string, null
The state/province name.
shipping_address_state_code string, null
The ISO 3166-2 state/province code without the country prefix. This is currently supported for USA, Canada, and India. For example, for Arizona (USA), state_code is AZ (not US-AZ). For Tamil Nadu (India), it is TN (not IN-TN). For British Columbia (Canada), it is BC (not CA-BC).
shipping_address_validation_status string, null, default=not_validated
The address verification status.
shipping_address_zip string, null
The zip or postal code. The number of characters is validated according to the rules specified here.
start_date timestamp, null
Applicable only for 'future' subscriptions. This is the scheduled start time of the subscription.
started_at timestamp, null
The time when the subscription was started. This is null for future subscriptions as they have not yet started.
status string, not null
The current state of the subscription.
trial_end timestamp, null
The end of the trial period for the subscription. If this value is present for a 'future' subscription, the subscription enters the 'in_trial' state when it starts.
trial_end_action string, null
Applicable only when End-of-trial Action has been enabled for the site. Whenever the subscription has a trial period, this field is returned and specifies the operation to be carried out for the subscription once the trial ends.
trial_start timestamp, null
The start of the trial period for the subscription. If this value is present for a future subscription, the subscription enters the in_trial state when it starts.
updated_at timestamp, null
The timestamp indicating when the item was last updated.
record_extracted_at timestamp
The column represents the timestamp when the updated data became available in Chargebee's data lakehouse.
record_exported_at timestamp
The column represents the timestamp when the data was exported to the configured destination.
change_type string
The column indicates the type of change [create, update, delete, read] and can be used to load data into the warehouse accordingly.

Sample Queries

List Transactions Needing Attention

This query retrieves all transactions with a status of needs_attention along with relevant details from the customers and subscriptions tables.

copy
Click to Copy
      SELECT
  t.id AS transaction_id,
  t.currency_code,
  t.amount,
  t.id_at_gateway,
  t.status AS transaction_status,
  c.id AS customer_id,
  c.name AS customer_name,
  c.email AS customer_email,
  s.id AS subscription_id,
  s.status AS subscription_status
FROM
  transactions t
  LEFT JOIN customers c ON t.customer_id = c.id
  LEFT JOIN subscriptions s ON t.subscription_id = s.id
WHERE
  t.status = 'needs_attention';
Paused Subscriptions

Retrieves a list of paused subscriptions along with customer info. pause_date is the date/time when the subscription was paused. resume_date is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

copy
Click to Copy
      SELECT
  s.id AS subscription_id,
  s.status AS subscription_status,
  s.pause_date AS subscription_pause_date,
  s.resume_date AS subscription_pause_date,
  c.first_name AS customer_first_name,
  c.last_name AS customer_last_name,
  c.email AS customer_email,
  c.phone AS customer_phone
FROM
  subscriptions s
  JOIN customers c ON s.customer_id = c.id
WHERE
  s.status = 'paused';
Subscriptions with Coupons Applied

Finds the list of subscriptions that have coupons applied, along with coupon details.

copy
Click to Copy
      SELECT
  s.id as subs_id,
  s.status as subs_status,
  c.name AS coupon_name,
  c.redemptions,
  sc.coupon_code
FROM
  subscriptions s
  JOIN subscription_coupons sc ON s.id = sc.subscription_id
  JOIN coupons c ON sc.coupon_id = c.id;