Chargebee integration summary

Stitch’s Chargebee integration replicates data using the Chargebee API . Refer to the Schema section for a list of objects available for replication.

Chargebee feature snapshot

A high-level look at Stitch's Chargebee integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release Status

Open Beta

Supported By

Singer Community

Stitch Plan

Free

Singer GitHub Repository

Chargebee Repository

DATA SELECTION
Table Selection

Supported

Column Selection

Supported

REPLICATION SETTINGS
Anchor Scheduling

Supported

Advanced Scheduling

Unsupported

Table-level Reset

Unsupported

Configurable Replication Methods

Unsupported

TRANSPARENCY
Extraction Logs

Supported

Loading Reports

Supported

Connecting Chargebee

Step 1: Generate an API Key

First, you’ll generate a Chargebee API Key for Stitch. This will allow Stitch to read data from your Chargebee account using the Chargebee API.

  1. Sign into your Chargebee account.
  2. In the left sidenav, click Settings > Configure Chargebee.
  3. Click the API keys and webhooks button.
  4. On the API Keys page, click the + Add API Key button. The Create an API Key modal will display.
  5. Select Read-Only Key as the API key type.
  6. Select All to define the API key’s access. This will grant read-only access to your Chargebee site.
  7. In the Name the API key field, enter Stitch.
  8. Click Create Key.

Chargebee will create the API key and redirect you back to the API Keys page:

Copy the API key somwhere handy - you’ll need it to complete the setup in Stitch.

Step 2: Add Chargebee as a Stitch data source

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the Chargebee icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch Chargebee” would create a schema called stitch_chargebee in the destination. Note: Schema names cannot be changed after you save the integration.

  5. In the API Key field, paste the API key you generated in Step 1.
  6. In the Site field, enter the name of your Chargebee site. This can be found in the URL of your Chargebee site. For example: If the URL was https://stitch.chargebee.com, only stitch would be entered into this field.

Step 3: Define the historical sync

The Sync Historical Data setting will define the starting date for your Chargebee integration. This means that data equal to or newer than this date will be replicated to your data warehouse.

Change this setting if you want to replicate data beyond Chargebee’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 4: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Chargebee integrations support the following replication scheduling methods:

To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Step 5: Set tables and columns to replicate

To complete the setup, you’ll need to select the tables and columns you want to replicate to your data warehouse.

Check out the Schema section to learn more about the available tables in Chargebee and how they replicate.

  1. In the list of tables that displays - or in the Tables to Replicate tab, if you skipped this step during setup - locate a table you want to replicate.
  2. To track a table, click the checkbox next to the table’s name. A green checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A green checkmark means the column is set to replicate.

  4. Repeat this process for all the tables and columns you want to replicate.
  5. When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.

Note: If you change these settings while a replication job is still in progress, they will not be used until the next job starts.

Initial and historical replication jobs

After you finish setting up Chargebee, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.


Chargebee table schemas

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List addons

The addons table contains info about the addons in your Chargebee account. Addons are additional charges applied to subscriptions apart from base charges.

id
STRING

The addon ID.

Reference:

updated_at
DATE-TIME

The time the addon was last updated. Note: This attribute will be present only if the resource has been updated after 2016-09-28.

accounting_code
STRING

The accounting code used by the addon.

accouting_category1
STRING

The name of the category of your product in Xero. If you’ve integrated with QuickBooks, this will be the Class.

accouting_category2
STRING

The name of the category of your product in Xero.

archived_at
DATE-TIME

The time at which the plan was moved to archived status.

charge_type
STRING

The type of charge. Possible values are:

  • recurring: Charges are automatically applied in sync with the billing frequency of the subscription.
  • non_recurring: Charged immediately and only once every time it’s applied.

currency_code
STRING

The currency code (ISO 4217 format) of the addon.

description
STRING

Description about the addon to show in the hosted pages and customer portal.

enabled_in_portal
BOOLEAN

Indicates if the addon is available to customers to add in the ‘Change Subscription’ option in the customer portal.

invoice_name
STRING

The display name used in invoices.

invoice_notes
STRING

The invoice notes for the addon.

is_shippable
BOOLEAN

Indicates whether the addon can be added to orders.

meta_data
STRING

Additional info about the addon.

name
STRING

The display name used in web interface for identifying the addon.

object
STRING

period
INTEGER

Applicable only for charge_type: recurring. Along with period_unit, this determines the term-price of the addon.

period_unit
STRING

Applicable only for charge_type: recurring. Along with period, this determines the term-price of the addon. Possible values are:

  • week: Charge based on week(s)
  • month: Charge based on month(s)
  • year: Charge based on year(s)
  • not_applicable: Not applicable for the addon

price
INTEGER

The addon price. Addon price is calculated based on the addon type and charge type.

pricing_model
STRING

Indicates how the charges for the addon are calculated. Possible values are:

  • flat_fee: Charges single price on a recurring basis.
  • per_unit: Charges the price for each unit of the plan for the subscription on a recurring basis.
  • tiered: Charges different per unit price for the quantity purchased from every tier.
  • volume: Charges the per unit price for the total quantity purchased based on the tier under which it falls.
  • stairstep: Charges a price for a range.

resource_version
INTEGER

The version number of the addon. Each update of the addon results in an incremental change of this value. Note: This attribute will be present only if the resource has been updated after 2016-09-28.

shipping_frequency_period
INTEGER

Defines the shipping frequency in conjunction with shipping_frequency_period_unit. For example: If shipping_frequency_period_unit: week and this value is 2, the customer would be billed every two weeks.

shipping_frequency_period_unit
STRING

Defines the shipping frequency in conjunction with shipping_frequency_period. Possible values are:

  • year
  • month
  • week

sku
STRING

The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application

status
STRING

The status of the addon. Possible values are:

  • active
  • archived

tax_code
STRING

The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee’s AvaTax for Sales integration.

tax_profile_id
STRING

The tax profile of the addon.

taxable
BOOLEAN

Indicates whether the addon is taxable or not.

tiers
ARRAY

Applicable only if the addon uses tiered, volume, or stairstep pricing. The list of tiers for the addon.

ending_unit
INTEGER

The upper limit of a range of units for the tier.

price
INTEGER

The price of the tier if the charge model is stairstep pricing, or the price of each unit in the tier if the charge model is tiered/volume pricing.

starting_unit
INTEGER

The lower limit of a range of units for the tier.

addons (table), tiers (attribute)

type
STRING

unit
STRING

Applicable only for quantity type addons. This specifies the type of quantity. For example: If the addon price is $10 and agent is the unit, it will be displayed as $10/agent.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List coupons

The coupons table contains info about the coupons in your Chargebee account.

id
STRING

The coupon ID.

Reference:

updated_at
DATE-TIME

The time the coupon was last updated.

addon_constraint
STRING

The addons the coupon can be applied to. Possible values are:

  • none
  • all
  • specific
  • not_applicable

apply_discount_on
STRING

apply_on
STRING

The invoice items for which this coupon needs to be applied. Possible values are:

  • invoice_amount: The coupon will be applied to the total invoice amount.
  • each_specified_item: the discount will be applied to each specified plan and addon item.

archived_at
DATE-TIME

The time when the coupon was archived.

created_at
DATE-TIME

The time when the coupon was created.

discount_amount
NUMBER

When discount_type: fixed_amount, this value will be the discount value in cents.

discount_percentage
NUMBER

When discount_type: percentage, this value will be the discount value percentage.

discount_type
STRING

The type of discount. Possible values are:

  • fixed_amount
  • percentage

duration_month
INTEGER

When duration_type: limited_period, this value will be the duration in months the coupon can be applied.

duration_type
STRING

The duration the coupon is applicable. Possible values are:

  • one_time
  • forever
  • limited_period

max_redemptions
INTEGER

The maximum number of times the coupon can be redeemed.

name
STRING

The display name used in web interface for identifying the coupon.

object
STRING

plan_constraint
STRING

The plans the coupon can be applied to. Possible values are:

  • none
  • all
  • specific
  • not_applicable

redemptions
INTEGER

The number of times the coupon has been redeemed.

resource_version
INTEGER

The version number of the coupon. Each update of the coupon results in an incremental change of this value. Note: This attribute will be present only if the coupon has been updated after 2016-09-28.

status
STRING

The status of the coupon. Possible values are:

  • active
  • expired
  • archived
  • deleted

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List credit notes

The credit_notes table contains info about the credit notes in your Chargebee account. A credit note is a document that specifies the money owed by a business to a customer.

id
STRING

The credit note ID.

Reference:

updated_at
DATE-TIME

The time the credit note was last updated.

allocations
ARRAY

Details about invoice allocations made from the credit note.

allocated_amount
INTEGER

The amount of the allocation, in cents.

allocated_at
DATE-TIME

The time the allocation occurred.

invoice_date
DATE-TIME

The closing date of the invoice.

invoice_id
STRING

The invoice ID.

Reference:

invoice_status
STRING

The current status of the invoice. Possible values are:

  • paid
  • posted
  • payment_due
  • not_paid
  • voided
  • pending
credit_notes (table), allocations (attribute)

amount_allocated
INTEGER

The amount allocated to invoices.

amount_available
INTEGER

The yet to be used credits of this credit note.

amount_refunded
INTEGER

The refunds issued from this credit note.

currency_code
STRING

The currency code (ISO 4217 format) for the credit note.

customer_id
STRING

The ID of the customer associated with the credit note.

Reference:

date
DATE-TIME

The date the credit note was issued.

deleted
BOOLEAN

Indicates whether the credit note was deleted or not.

discounts
ARRAY

Details about the discounts applied to the credit note.

amount
INTEGER

The discount amount, in cents.

description
STRING

The description of the discount line item.

entity_id
STRING

The ID of the entity the discount amount is based on. This value will only be present if entity_type is item_level_coupon or document_level_coupon.

Reference:

entity_type
STRING

The type of the discount line item. Possible values are:

  • item_level_coupon: Represents item-level coupons applied to the invoice.
  • document_level_coupon: Represents document-level coupons applied to the document.
  • promotional_credits: Represents promotional credits in the invoice.
  • prorated_credits: Represents credit adjustments in the invoice.
credit_notes (table), discounts (attribute)

line_item_discounts
ARRAY

The list of discount(s) applied for each line item of the invoice.

coupon_id
STRING

The coupon ID.

Reference:

discount_amount
INTEGER

The discount amount, in cents.

discount_type
STRING

The type of the discount line item. Possible values are:

  • item_level_coupon: Represents item-level coupons applied to the invoice.
  • document_level_coupon: Represents document-level coupons applied to the document.
  • promotional_credits: Represents promotional credits in the invoice.
  • prorated_credits: Represents credit adjustments in the invoice.

line_item_id
STRING

The ID of the line item for which the discount is applicable.

Reference:

credit_notes (table), line_item_discounts (attribute)

line_item_taxes
ARRAY

The list of taxes applied on line items.

is_non_compliance_tax
BOOLEAN

Indicates the non-compliance tax should not be reported to the tax jurisdiction.

is_partial_tax_applied
BOOLEAN

Indicates whether tax is applied only on a portion of the line item or not.

line_item_id
STRING

The ID of the line item for which the tax is applicable.

Reference:

tax_amount
INTEGER

The tax amount, in cents.

tax_juris_code
STRING

The tax jurisdiction code.

tax_juris_name
STRING

The name of the tax jurisdiction.

tax_juris_type
STRING

The type of tax jurisdiction. Possible values are:

  • country
  • federal
  • state
  • county
  • city
  • special
  • unincorporated (Combined tax of state and country)
  • other

tax_name
STRING

The name of the tax applied.

tax_rate
NUMBER

The rate of tax used to calculate the tax amount.

taxable_amount
INTEGER

The actual portion of the line item that is taxable, in cents.

credit_notes (table), line_item_taxes (attribute)

line_item_tiers
ARRAY

The list of tiers applicable for the line item.

ending_unit
INTEGER

The upper limit of a range of units for the tier.

line_item_id
STRING

The line item ID.

Reference:

quantity_used
INTEGER

The number of units purchased in a range.

starting_unit
INTEGER

The lower limit of a range of units for the tier.

unit_amount
INTEGER

The price of the tier if the charge model is stairstep, or the price of each unit in the tier if the charge model is tiered or volume.

credit_notes (table), line_item_tiers (attribute)

line_items
ARRAY

The line items in the credit note.

amount
INTEGER

The total amount of the line item, calculated as unit_amount x quantity.

date_from
DATE-TIME

The start date of the line item.

date_to
DATE-TIME

The end date of the line item.

description
STRING

The description of the line item.

discount_amount
INTEGER

The discount amount applied to the line item, in cents.

entity_id
STRING

The ID of the entity the line item is based on.

entity_type
STRING

The modelled entity (plan, addon, etc.) this line item is based on. Possible values are:

  • plan_setup: The line item is based on a plan setup charge. The entity_id will specify the plan ID (plans: id).
  • plan: The line item is based on a plan entity. The entity_id will specify the plan ID (plans: id).
  • addon: The line item is based on an addon entity. The entity_id will specify the addon ID (addons: id).
  • adhoc: The line item is not modelled. The entity_id attribute will be null.

id
STRING

The line item ID.

Reference:

is_taxed
BOOLEAN

Indicates whether the line item is taxed or not.

item_level_discount_amount
INTEGER

The item level discount amount for the line item, in cents.

pricing_model
STRING

Indicates how the charges for the line item are calculated. Possible values are:

  • flat_fee: Charges single price on a recurring basis.
  • per_unit: Charges the price for each unit of the plan for the subscription on a recurring basis.
  • tiered: Charges different per unit price for the quantity purchased from every tier.
  • volume: Charges the per unit price for the total quantity purchased based on the tier under which it falls.
  • stairstep: Charges a price for a range.

quantity
INTEGER

The quantity of the recurring item, represented by the line item.

subscription_id
STRING

The ID of the subscription associated with the line item.

Reference:

tax_amount
INTEGER

The tax amount of the line item, in cents.

tax_exempt_reason
STRING

The reason or category for why the line item is excluded from the taxable amount. Possible values are:

  • tax_not_configured
  • region_non_taxable
  • export
  • customer_exempt
  • zero_rated
  • reverse_charge
  • high_value_physical_good

tax_rate
NUMBER

The rate of tax used to calculate tax for the line item.

unit_amount
INTEGER

The unit amount of the line item, in cents.

credit_notes (table), line_items (attribute)

linked_refunds
ARRAY

Details about refunds issued from the credit note.

applied_amount
INTEGER

The transaction amount applied to the invoice.

applied_at
DATE-TIME

The time the amount was applied.

txn_amount
INTEGER

The total amount of the transaction.

txn_date
DATE-TIME

The date the transaction occured.

txn_id
STRING

the transaction ID.

Reference:

txn_status
STRING

The status of the transaction. Possible values are:

  • in_progress
  • success
  • voided
  • failure
  • timeout
  • needs_attention
credit_notes (table), linked_refunds (attribute)

price_type
STRING

The price type of the credit note. Possible values are:

  • tax_exclusive
  • tax_inclusive

reason_code
STRING

The reason for issuing the credit note. Possible values include:

  • write_off
  • subscription_change
  • subscription_cancellation
  • subscription_pause
  • chargeback
  • product_unsatisfactory
  • service_unsatisfactory
  • order_change
  • order_cancellation
  • waiver
  • other
  • fraudulent

reference_invoice_id
STRING

The ID of the invoice against which the credit note is issued.

Reference:

refunded_at
DATE-TIME

The time when the credit note was fully used.

resource_version
INTEGER

The version number of the credit note. Each update of the credit note results in an incremental change of this value. Note: This attribute will be present only if the credit note has been updated after 2016-09-28.

round_off_amount
INTEGER

The credit note rounded-off amount, in cents.

status
STRING

The status of the credit note. Possible values include:

  • adjusted
  • refunded
  • refund_due
  • voided

sub_total
INTEGER

The credit note subtotal, in cents.

subscription_id
STRING

The ID of the subscription associated with the credit note.

Reference:

taxes
ARRAY

The tax lines of the credit note.

amount
INTEGER

The tax amount, in cents.

description
STRING

The description of the tax item.

name
STRING

The name of the tax applied. For example: GST

credit_notes (table), taxes (attribute)

total
INTEGER

The total credit amount in cents.

type
STRING

The credit note type. Possible values are:

  • adjustment
  • refundable

vat_number
STRING

The VAT number of the customer for whom the credit note is raised.

voided_at
DATE-TIME

The time when the credit note was voided.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List customers

The customers table contains info about the customers in your Chargebee account.

id
STRING

The customer ID.

Reference:

updated_at
DATE-TIME

The time the customer was last updated.

allow_direct_debit
BOOLEAN

Indicates whether the customer can pay via direct debit or not.

auto_collection
STRING

Indicates whether payments need to be automatically collected for the customer. Possible values are:

  • on: When an invoice is created, an automatic attempt to charge the customer’s payment method is made.
  • off: Automatic collection of charges will not be made.

balances
ARRAY

The list of balances for the customer.

currency_code
STRING

The currency code in ISO 4217 for the balance.

excess_payments
INTEGER

The total unused payments associated with the customer.

promotional_credits
INTEGER

The promotional credits balance for the customer.

refundable_credits
INTEGER

The refundable credits balance for the customer.

unbilled_charges
INTEGER

The total unbilled charges for the customer.

customers (table), balances (attribute)

billing_address
OBJECT

The billing address for the customer.

city
STRING

The city.

company
STRING

The company.

country
STRING

The country.

email
STRING

The email.

first_name
STRING

The first name.

last_name
STRING

The last name.

line1
STRING

The first line of the address.

line2
STRING

The second line of the address.

line3
STRING

The third line of the address.

phone
STRING

The phone number.

state
STRING

The state or province.

state_code
STRING

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India.

validation_status
STRING

The address verification status. Possible values are:

  • not_validated
  • valid
  • partially_valid
  • invalid

zip
STRING

The zip or postal code.

customers (table), billing_address (attribute)

billing_date
BOOLEAN

Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the monthly and yearly subscriptions of this customer will be aligned to this date.

billing_date_mode
STRING

Indicates whether this customer’s billing_date value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_date will not be reset even when all of the monthly/yearly subscriptions are cancelled.

Possible values are:

  • using_defaults: The billing_date value is set based on configured defaults.
  • manually_set: The billing_date is specifically set.

billing_day_of_week
BOOLEAN

Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the weekly subscriptions of this customer will be aligned to this week day.

Possible values are:

  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday
  • sunday

billing_day_of_week_mode
STRING

Indicates whether this customer’s billing_day_of_week value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_day_of_week will not be reset even when all of the weekly subscriptions are cancelled.

Possible values are:

  • using_defaults: The billing_day_of_week value is set based on configured defaults.
  • manually_set: The billing_day_of_week is specifically set.

card_status
STRING

cf_company_id
INTEGER

company
STRING

The name of the company associated with the customer.

consolidated_invoicing
BOOLEAN

Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.

contacts
ARRAY

A list of contacts associated with the customer.

email
STRING

The contact’s email.

enabled
BOOLEAN

Indicates whether the contacted is enabled (true) or disabled (false).

first_name
STRING

The first name of the contact.

id
STRING

The contact ID.

label
STRING

The label/tag provided for the contact.

last_name
STRING

The last name of the contact.

object
STRING

phone
STRING

The phone number of the contact.

send_account_email
STRING

Indicates whether account emails are enabled for the contact.

send_billing_email
STRING

Indicates whether billing emails are enabled for the contact.

customers (table), contacts (attribute)

created_at
DATE-TIME

The time the customer was created.

deleted
BOOLEAN

Indicates whether the customer has been deleted or not.

email
STRING

The customer’s email address.

excess_payments
INTEGER

The total unused payments associated with the customer.

first_name
STRING

The first name of the customer.

invoice_notes
STRING

Invoice notes associated with the customer.

last_name
STRING

The last name of the customer.

locale
STRING

Determines which region-specific language Chargebee uses to communicate with the customer.

net_term_days
INTEGER

The number of days within which the customer has to make payment for invoices.

object
STRING

payment_method
OBJECT

The primary payment source for the customer.

gateway
STRING

The name of the gateway the payment is associated with. Refer to Chargebee’s documentation for a full list of possible values.

gateway_account_id
STRING

The gateway account the payment method is stored with.

object
STRING

reference_id
STRING

The reference ID.

  • For Amazon and PayPal, this will be the billing agreement ID.
  • For GoCardless direct debit, this will be the mandate ID.
  • For card payments, this will be the ID provided by the gateway/card vault for the specific payment method.

status
STRING

The current status of the payment method. Possible values include:

  • valid
  • expiring
  • expired
  • invalid
  • pending_verification

type
STRING

The type of the payment source. Possible values include:

  • card (Includes credit and debit cards)
  • paypal_express_checkout
  • amazon_payments
  • direct_debit
  • generic
  • alipay
  • unionpay
  • apple_pay
  • wechat_pay
customers (table), payment_method (attribute)

phone
STRING

The customer’s phone number.

pii_cleared
STRING

Indicates whether the customer’s personal info has been cleared. Possible values are:

  • active
  • scheduled_for_clear
  • cleared

preferred_currency_code
STRING

Applicable if the Chargebee Multicurrency feature is enabled. The currency code of the customer’s preferred currency (ISO 4217 format).

primary_payment_source_id
STRING

The ID of the primary payment source for the customer.

Reference:

promotional_credits
INTEGER

The promotional credits balance of the customer.

referral_urls
ARRAY

A list of referral URLs for the customer.

created_at
DATE-TIME

The time the referral URL was created.

external_customer_id
STRING

The ID of the external customer in the referral system.

referral_account_id
STRING

The ID of the referral account.

referral_campaign_id
STRING

The ID of the referral campaign.

referral_external_account_id
STRING

The ID of the external referral account.

referral_sharing_url
STRING

The referral sharing URL for the customer.

referral_system
STRING

The URL for the referral system account. Possible values are:

  • referral_candy
  • referral_saasquatch
  • friendbuy

updated_at
DATE-TIME

The time the referral URL was last updated.

customers (table), referral_urls (attribute)

refundable_credits
INTEGER

The refundable credits balance of the customer.

resource_version
INTEGER

The version number of the customer. Each update of the customer results in an incremental change of this value. Note: This attribute will be present only if the customer has been updated after 2016-09-28.

taxability
STRING

Indicates if the customer is liable for tax. Possible values are:

  • taxable
  • exempt

unbilled_charges
INTEGER

The total unbilled charges for the customer.

vat_number
STRING

The VAT number for the customer.


Replication Method :

Key-based Incremental

Replication Key :

occurred_at

Primary Key :

id

API endpoint :

List events

The events table contains info about the events that have occurred on your Chargebee site. Event records contain data about affected resources and additional details, such as when the change occurred. This can be used to create a log of events for a record and analyze how it has changed over time.

id
STRING

The event ID.

occurred_at
DATE-TIME

The time the event occurred.

api_version
STRING

The Chargebee API Version used for rendering this event content. Possible values are v1 or v2.

content
OBJECT

The data associated with the event. The attributes in this object will vary depending on the event type. Refer to Chargebee’s documentation for a list of possible event types.

coupon
OBJECT

Applicable when events.event_type is one of the following:

  • coupon_created
  • coupon_updated
  • coupon_deleted
  • coupon_set_created
  • coupon_set_updated
  • coupon_set_deleted
  • coupon_codes_added
  • coupon_codes_deleted
  • coupon_codes_updated

id
STRING

The coupon ID.

Reference:

addon_constraint
STRING

The addons the coupon can be applied to. Possible values are:

  • none
  • all
  • specific
  • not_applicable

apply_discount_on
STRING

apply_on
STRING

The invoice items for which this coupon needs to be applied. Possible values are:

  • invoice_amount: The coupon will be applied to the total invoice amount.
  • each_specified_item: the discount will be applied to each specified plan and addon item.

archived_at
DATE-TIME

The time when the coupon was archived.

created_at
DATE-TIME

The time when the coupon was created.

discount_amount
NUMBER

When discount_type: fixed_amount, this value will be the discount value in cents.

discount_percentage
NUMBER

When discount_type: percentage, this value will be the discount value percentage.

discount_type
STRING

The type of discount. Possible values are:

  • fixed_amount
  • percentage

duration_month
INTEGER

When duration_type: limited_period, this value will be the duration in months the coupon can be applied.

duration_type
STRING

The duration the coupon is applicable. Possible values are:

  • one_time
  • forever
  • limited_period

max_redemptions
INTEGER

The maximum number of times the coupon can be redeemed.

name
STRING

The display name used in web interface for identifying the coupon.

object
STRING

plan_constraint
STRING

The plans the coupon can be applied to. Possible values are:

  • none
  • all
  • specific
  • not_applicable

redemptions
INTEGER

The number of times the coupon has been redeemed.

resource_version
INTEGER

The version number of the coupon. Each update of the coupon results in an incremental change of this value. Note: This attribute will be present only if the coupon has been updated after 2016-09-28.

status
STRING

The status of the coupon. Possible values are:

  • active
  • expired
  • archived
  • deleted

updated_at
DATE-TIME

The time the coupon was last updated.

events (table), coupon (attribute)

customer
OBJECT

Applicable when events.event_type is one of the following:

  • card_added
  • card_updated
  • card_expiry_reminder
  • card_expired
  • card_deleted
  • customer_created
  • customer_changed
  • customer_deleted
  • customer_moved_out
  • customer_moved_in
  • hierarchy_created
  • hierarchy_deleted
  • promotional_credits_added
  • promotional_credits_deducted
  • subscription_created
  • subscription_started
  • subscription_trial_end_reminder
  • subscription_activated
  • subscription_changed
  • subscription_cancellation_scheduled
  • subscription_cancellation_reminder
  • subscription_cancelled
  • subscription_reactivated
  • subscription_renewed
  • subscription_scheduled_cancellation_removed
  • subscription_changes_scheduled
  • subscription_scheduled_changes_removed
  • subscription_shipping_address_updated
  • subscription_deleted
  • subscription_paused
  • subscription_pause_scheduled
  • subscription_scheduled_pause_removed
  • subscription_resumed
  • subscription_resumption_scheduled
  • subscription_scheduled_resumption_removed
  • subscription_renewal_reminder
  • payment_source_added
  • payment_source_updated
  • payment_source_deleted
  • payment_succeeded
  • payment_failed
  • payment_refunded
  • payment_initiated
  • refund_initiated
  • virtual_bank_account_added
  • virtual_bank_account_updated
  • virtual_bank_account_deleted

id
STRING

The customer ID.

Reference:

allow_direct_debit
BOOLEAN

Indicates whether the customer can pay via direct debit or not.

auto_collection
STRING

Indicates whether payments need to be automatically collected for the customer. Possible values are:

  • on: When an invoice is created, an automatic attempt to charge the customer’s payment method is made.
  • off: Automatic collection of charges will not be made.

balances
ARRAY

The list of balances for the customer.

currency_code
STRING

The currency code in ISO 4217 for the balance.

excess_payments
INTEGER

The total unused payments associated with the customer.

promotional_credits
INTEGER

The promotional credits balance for the customer.

refundable_credits
INTEGER

The refundable credits balance for the customer.

unbilled_charges
INTEGER

The total unbilled charges for the customer.

events (table), balances (attribute)

billing_address
OBJECT

The billing address for the customer.

city
STRING

The city.

company
STRING

The company.

country
STRING

The country.

email
STRING

The email.

first_name
STRING

The first name.

last_name
STRING

The last name.

line1
STRING

The first line of the address.

line2
STRING

The second line of the address.

line3
STRING

The third line of the address.

phone
STRING

The phone number.

state
STRING

The state or province.

state_code
STRING

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India.

validation_status
STRING

The address verification status. Possible values are:

  • not_validated
  • valid
  • partially_valid
  • invalid

zip
STRING

The zip or postal code.

events (table), billing_address (attribute)

billing_date
BOOLEAN

Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the monthly and yearly subscriptions of this customer will be aligned to this date.

billing_date_mode
STRING

Indicates whether this customer’s billing_date value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_date will not be reset even when all of the monthly/yearly subscriptions are cancelled.

Possible values are:

  • using_defaults: The billing_date value is set based on configured defaults.
  • manually_set: The billing_date is specifically set.

billing_day_of_week
BOOLEAN

Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the weekly subscriptions of this customer will be aligned to this week day.

Possible values are:

  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday
  • sunday

billing_day_of_week_mode
STRING

Indicates whether this customer’s billing_day_of_week value is derived as per configurations or its specifically set (overriden). When specifically set, the billing_day_of_week will not be reset even when all of the weekly subscriptions are cancelled.

Possible values are:

  • using_defaults: The billing_day_of_week value is set based on configured defaults.
  • manually_set: The billing_day_of_week is specifically set.

card_status
STRING

cf_company_id
INTEGER

company
STRING

The name of the company associated with the customer.

consolidated_invoicing
BOOLEAN

Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.

contacts
ARRAY

A list of contacts associated with the customer.

email
STRING

The contact’s email.

enabled
BOOLEAN

Indicates whether the contacted is enabled (true) or disabled (false).

first_name
STRING

The first name of the contact.

id
STRING

The contact ID.

label
STRING

The label/tag provided for the contact.

last_name
STRING

The last name of the contact.

object
STRING

phone
STRING

The phone number of the contact.

send_account_email
STRING

Indicates whether account emails are enabled for the contact.

send_billing_email
STRING

Indicates whether billing emails are enabled for the contact.

events (table), contacts (attribute)

created_at
DATE-TIME

The time the customer was created.

deleted
BOOLEAN

Indicates whether the customer has been deleted or not.

email
STRING

The customer’s email address.

excess_payments
INTEGER

The total unused payments associated with the customer.

first_name
STRING

The first name of the customer.

invoice_notes
STRING

Invoice notes associated with the customer.

last_name
STRING

The last name of the customer.

locale
STRING

Determines which region-specific language Chargebee uses to communicate with the customer.

net_term_days
INTEGER

The number of days within which the customer has to make payment for invoices.

object
STRING

payment_method
OBJECT

The primary payment source for the customer.

gateway
STRING

The name of the gateway the payment is associated with. Refer to Chargebee’s documentation for a full list of possible values.

gateway_account_id
STRING

The gateway account the payment method is stored with.

object
STRING

reference_id
STRING

The reference ID.

  • For Amazon and PayPal, this will be the billing agreement ID.
  • For GoCardless direct debit, this will be the mandate ID.
  • For card payments, this will be the ID provided by the gateway/card vault for the specific payment method.

status
STRING

The current status of the payment method. Possible values include:

  • valid
  • expiring
  • expired
  • invalid
  • pending_verification

type
STRING

The type of the payment source. Possible values include:

  • card (Includes credit and debit cards)
  • paypal_express_checkout
  • amazon_payments
  • direct_debit
  • generic
  • alipay
  • unionpay
  • apple_pay
  • wechat_pay
events (table), payment_method (attribute)

phone
STRING

The customer’s phone number.

pii_cleared
STRING

Indicates whether the customer’s personal info has been cleared. Possible values are:

  • active
  • scheduled_for_clear
  • cleared

preferred_currency_code
STRING

Applicable if the Chargebee Multicurrency feature is enabled. The currency code of the customer’s preferred currency (ISO 4217 format).

primary_payment_source_id
STRING

The ID of the primary payment source for the customer.

promotional_credits
INTEGER

The promotional credits balance of the customer.

referral_urls
ARRAY

A list of referral URLs for the customer.

created_at
DATE-TIME

The time the referral URL was created.

external_customer_id
STRING

The ID of the external customer in the referral system.

referral_account_id
STRING

The ID of the referral account.

referral_campaign_id
STRING

The ID of the referral campaign.

referral_external_account_id
STRING

The ID of the external referral account.

referral_sharing_url
STRING

The referral sharing URL for the customer.

referral_system
STRING

The URL for the referral system account. Possible values are:

  • referral_candy
  • referral_saasquatch
  • friendbuy

updated_at
DATE-TIME

The time the referral URL was last updated.

events (table), referral_urls (attribute)

refundable_credits
INTEGER

The refundable credits balance of the customer.

resource_version
INTEGER

The version number of the customer. Each update of the customer results in an incremental change of this value. Note: This attribute will be present only if the customer has been updated after 2016-09-28.

taxability
STRING

Indicates if the customer is liable for tax. Possible values are:

  • taxable
  • exempt

unbilled_charges
INTEGER

The total unbilled charges for the customer.

updated_at
DATE-TIME

The time the customer was last updated.

vat_number
STRING

The VAT number for the customer.

events (table), customer (attribute)

invoice
OBJECT

Applicable when events.event_type is one of the following:

  • invoice_generated
  • invoice_updated
  • invoice_deleted
  • pending_invoice_created
  • pending_invoice_updated
  • payment_failed
  • payment_initiated
  • payment_refunded
  • refund_initiated
  • subscription_created
  • subscription_started
  • subscription_activated
  • subscription_changed
  • subscription_cancelled
  • subscription_reactivated
  • subscription_renewed
  • subscription_paused
  • subscription_resumed

id
STRING

The invoice ID.

Reference:

updated_at
DATE-TIME

The time the invoice was last updated.

adjustment_credit_notes
ARRAY

Details about the adjustments created for the invoice.

cn_date
DATE-TIME

The date at which the credit note was created.

cn_id
STRING

The credit note ID.

Reference:

cn_reason_code
STRING

The reason for the credit note. Possible values are:

  • write_off
  • subscription_change
  • subscription_cancellation
  • subscription_pause
  • chargeback
  • product_unsatisfactory
  • service_unsatisfactory
  • order_change
  • order_cancellation
  • waiver
  • other
  • fraudulent

cn_status
STRING

The status of the credit note. Possible values are:

  • adjusted
  • refunded
  • refund_due
  • voided

cn_total
INTEGER

The total amount of the credit note.

events (table), adjustment_credit_notes (attribute)

amount_adjusted
INTEGER

The total adjusted amount made against the invoice.

amount_due
INTEGER

The total amount to be collected, include the invoice’s payments in progress.

amount_paid
INTEGER

The total payments received for the invoice.

amount_to_collect
INTEGER

The total amount to be collected.

applied_credits
ARRAY

The refundable credits applied on the invoice.

applied_amount
INTEGER

The applied amount, in cents.

applied_at
DATE-TIME

The time the credit was applied.

cn_date
DATE-TIME

The date the credit was created.

cn_id
STRING

The credit ID.

Reference:

cn_reason_code
STRING

The reason for the credit note. Possible values are:

  • write_off
  • subscription_change
  • subscription_cancellation
  • subscription_pause
  • chargeback
  • product_unsatisfactory
  • service_unsatisfactory
  • order_change
  • order_cancellation
  • waiver
  • other
  • fraudulent

cn_status
STRING

The status of the credit note. Possible values are:

  • adjusted
  • refunded
  • refund_due
  • voided
events (table), applied_credits (attribute)

base_currency_code
STRING

billing_address
OBJECT

The billing address for the invoice.

city
STRING

The city.

company
STRING

The company.

country
STRING

The country.

email
STRING

The email.

first_name
STRING

The first name.

last_name
STRING

The last name.

line1
STRING

The first line of the address.

line2
STRING

The second line of the address.

line3
STRING

The third line of the address.

phone
STRING

The phone number.

state
STRING

The state or province.

state_code
STRING

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India.

validation_status
STRING

The address verification status. Possible values are:

  • not_validated
  • valid
  • partially_valid
  • invalid

zip
STRING

The zip or postal code.

events (table), billing_address (attribute)

credits_applied
INTEGER

The total credits applied against the invoice.

currency_code
STRING

The currency code (ISO 4217 format) for the invoice.

customer_id
STRING

The ID of the customer the invoice is for.

Reference:

date
DATE-TIME

Closing date of the invoice. Typically this is the date on which invoice is generated. If “wait & notify to send invoices enabled for usage based billing” is enabled in Chargebee, this will not be the same as date on which invoice was actually sent to customer.

deleted
BOOLEAN

Indicates if the invoice has been deleted or not.

discounts
ARRAY

Details about the discounts applied to the invoice.

amount
INTEGER

The discount amount, in cents.

description
STRING

The description of the discount line item.

entity_id
STRING

The ID of the entity the discount amount is based on. This value will only be present if entity_type is item_level_coupon or document_level_coupon.

Reference:

entity_type
STRING

The type of the discount line item. Possible values are:

  • item_level_coupon: Represents item-level coupons applied to the invoice.
  • document_level_coupon: Represents document-level coupons applied to the document.
  • promotional_credits: Represents promotional credits in the invoice.
  • prorated_credits: Represents credit adjustments in the invoice.
events (table), discounts (attribute)

due_date
DATE-TIME

The due date of the invoice.

dunning_status
STRING

The current dunning status of the invoice. Possible values are:

  • in_progress
  • exhausted
  • stopped
  • success

exchange_rate
NUMBER

expected_payment_date
DATE-TIME

The expected payment date recorded for the invoice.

first_invoice
BOOLEAN

Indicates if this is the first invoice raised for the subscription. If this is a non-recurring invoice, it indicates if this is the first invoice for the customer.

has_advance_charges
BOOLEAN

Indicates if there are any advanced charges present in the invoice.

is_gifted
BOOLEAN

Indicates if the invoice is gifted or not.

issued_credit_notes
ARRAY

A list of credit notes issued for the invoice.

cn_date
DATE-TIME

The date at which the credit note was created.

cn_id
STRING

The credit note ID.

Reference:

cn_reason_code
STRING

The reason for the credit note. Possible values are:

  • write_off
  • subscription_change
  • subscription_cancellation
  • subscription_pause
  • chargeback
  • product_unsatisfactory
  • service_unsatisfactory
  • order_change
  • order_cancellation
  • waiver
  • other
  • fraudulent

cn_status
STRING

The status of the credit note. Possible values are:

  • adjusted
  • refunded
  • refund_due
  • voided

cn_total
INTEGER

The total amount of the credit note.

events (table), issued_credit_notes (attribute)

line_item_discounts
ARRAY

The list of discounts applied for each line item in the invoice.

line_item_taxes
ARRAY

The list of taxes applied on line items.

line_item_id
STRING

The ID of the line item for which the tax is applicable.

Reference:

tax_amount
INTEGER

The tax amount, in cents.

tax_juris_code
STRING

The tax jurisdiction code.

tax_juris_name
STRING

The name of the tax jurisdiction.

tax_juris_type
STRING

The type of tax jurisdiction. Possible values are:

  • country
  • federal
  • state
  • county
  • city
  • special
  • unincorporated (Combined tax of state and country)
  • other

tax_name
STRING

The name of the tax applied.

tax_rate
NUMBER

The rate of tax used to calculate the tax amount.

events (table), line_item_taxes (attribute)

line_items
ARRAY

The line items in the invoice.

amount
INTEGER

The total amount of the line item, calculated as unit_amount x quantity.

date_from
DATE-TIME

The start date of the line item.

date_to
DATE-TIME

The end date of the line item.

description
STRING

The description of the line item.

discount_amount
INTEGER

The discount amount applied to the line item, in cents.

entity_id
STRING

The ID of the entity the line item is based on.

entity_type
STRING

The modelled entity (plan, addon, etc.) this line item is based on. Possible values are:

  • plan_setup: The line item is based on a plan setup charge. The entity_id will specify the plan ID (plans: id).
  • plan: The line item is based on a plan entity. The entity_id will specify the plan ID (plans: id).
  • addon: The line item is based on an addon entity. The entity_id will specify the addon ID (addons: id).
  • adhoc: The line item is not modelled. The entity_id attribute will be null.

id
STRING

The line item ID.

Reference:

is_taxed
BOOLEAN

Indicates whether the line item is taxed or not.

item_level_discount_amount
INTEGER

The item level discount amount for the line item, in cents.

pricing_model
STRING

Indicates how the charges for the line item are calculated. Possible values are:

  • flat_fee: Charges single price on a recurring basis.
  • per_unit: Charges the price for each unit of the plan for the subscription on a recurring basis.
  • tiered: Charges different per unit price for the quantity purchased from every tier.
  • volume: Charges the per unit price for the total quantity purchased based on the tier under which it falls.
  • stairstep: Charges a price for a range.

quantity
INTEGER

The quantity of the recurring item, represented by the line item.

subscription_id
STRING

The ID of the subscription associated with the line item.

Reference:

tax_amount
INTEGER

The tax amount of the line item, in cents.

tax_exempt_reason
STRING

The reason or category for why the line item is excluded from the taxable amount. Possible values are:

  • tax_not_configured
  • region_non_taxable
  • export
  • customer_exempt
  • zero_rated
  • reverse_charge
  • high_value_physical_good

tax_rate
NUMBER

The rate of tax used to calculate tax for the line item.

unit_amount
INTEGER

The unit amount of the line item, in cents.

events (table), line_items (attribute)

linked_orders
ARRAY

A list of orders associated with the invoice.

batch_id
STRING

The batch ID.

created_at
DATE-TIME

the time the order was created.

fulfillment_status
STRING

The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped, Awaiting Shipment, Not fulfilled, etc.

id
STRING

The order ID.

reference_id
STRING

This attribute can be used to map the orders in the shipping/order management application to the orders in Chargebee. The reference_id generally is same as the order id in the third party application.

status
STRING

The status of the order. Possible values include:

  • new
  • processing
  • complete
  • cancelled
  • voided
  • queued
  • awaiting_shipment
  • on_hold
  • delivered
  • shipped
  • partially_delivered
  • returned
events (table), linked_orders (attribute)

linked_payments
ARRAY

The list of payment transactions for the invoice.

applied_amount
INTEGER

The transaction amount applied to the invoice.

applied_at
DATE-TIME

The time the amount was applied.

txn_amount
INTEGER

The total amount of the transaction.

txn_date
DATE-TIME

The date the transaction occured.

txn_id
STRING

the transaction ID.

Reference:

txn_status
STRING

The status of the transaction. Possible values are:

  • in_progress
  • success
  • voided
  • failure
  • timeout
  • needs_attention
events (table), linked_payments (attribute)

net_term_days
INTEGER

The number of days within which the invoice has to be paid.

new_sales_amount
INTEGER

next_retry_at
DATE-TIME

A timestamp indicating when the next attempt to collect payment for this invoice will occur.

notes
ARRAY

The list of notes associated with the invoice. If entity_type & entity_id are not present, then it is general notes (i.e Notes input provided under Customize Invoice action in Chargebee web interface).

entity_id
STRING

The entity ID.

entity_type
STRING

The type of entity the note belongs to. Possible values are:

note
STRING

The content of the note.

events (table), notes (attribute)

object
STRING

paid_at
DATE-TIME

The time the invoice was paid.

po_number
STRING

The number of the purchase order associated with the invoice.

price_type
STRING

The price type of the invoice. Possible values are:

  • tax_exclusive
  • tax_inclusive

recurring
BOOLEAN

Indicates if the invoice belongs to a subscription or not.

resource_version
INTEGER

The version number of the invoice. Each update of the invoice results in an incremental change of this value. Note: This attribute will be present only if the invoice has been updated after 2016-09-28.

round_off_amount
INTEGER

The invoice rounded-off amount, in cents.

shipping_address
OBJECT

The shipping address for the invoice.

city
STRING

The city.

company
STRING

The company.

country
STRING

The country.

email
STRING

The email.

first_name
STRING

The first name.

last_name
STRING

The last name.

line1
STRING

The first line of the address.

line2
STRING

The second line of the address.

line3
STRING

The third line of the address.

phone
STRING

The phone number.

state
STRING

The state or province.

state_code
STRING

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India.

validation_status
STRING

The address verification status. Possible values are:

  • not_validated
  • valid
  • partially_valid
  • invalid

zip
STRING

The zip or postal code.

events (table), shipping_address (attribute)

status
STRING

The status of the invoice. Possible values are:

  • paid
  • posted
  • payment_due
  • not_paid
  • voided
  • pending

sub_total
INTEGER

The subtotal of the invoice, in cents.

subscription_id
STRING

The ID of the subscription associated with the invoice.

Reference:

tax
INTEGER

The total tax amount for the invoice, in cents.

taxes
ARRAY

amount
INTEGER

The tax amount, in cents.

description
STRING

The description of the tax item.

name
STRING

The name of the tax applied. For example: GST

events (table), taxes (attribute)

term_finalized
BOOLEAN

Indicates if the invoice line item terms are finalized or not.

total
INTEGER

The total invoiced amount, in cents.

vat_number
STRING

The VAT number.

voided_at
DATE-TIME

The time the invoice was voided.

write_off_amount
INTEGER

The amount written off against the invoice, in cents.

events (table), invoice (attribute)

plan
OBJECT

Applicable when events.event_type is one of the following:

  • plan_created
  • plan_updated
  • plan_deleted

billing_cycles
INTEGER

The number of billing cycles the subscription is active.

charge_model
STRING

Defines how the recurring charges for the subscription are calculated. Possible values are:

  • flat_fee
  • per_unit
  • tiered
  • volume
  • stairstep

description
STRING

The description of the plan to show in hosted pages and the customer portal.

free_quantity
INTEGER

The free quantity the subscriptions of the plan will have. Only quantities more than this value will be charged for the subscription.

id
STRING

The plan ID.

Reference:

invoice_notes
STRING

Invoice notes associated with the subscription.

name
STRING

The display name of the plan.

period
INTEGER

Defines the billing frequency for the plan. Used with period_unit to create a billing schedule for the plan.

For example: If period_unit: week and period: 3, billing would occur every 3 weeks.

period_unit
STRING

The time unit for the billing period. Used with period to create a billing schedule for the plan.

For example: If period_unit: week and period: 3, billing would occur every 3 weeks.

Possible values are:

  • day
  • week
  • month
  • year

price
INTEGER

The price of the plan.

redirect_url
STRING

The URL to redirect on successful checkout.

setup_cost
INTEGER

The one-time setup fee charged as part of the first invoice for the plan.

sku
STRING

Ssed as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.

status
STRING

The plan state. Possible values are:

  • active
  • archived

tax_profile_id
STRING

The ID of the tax profile for the plan.

taxable
BOOLEAN

Indicates if the plan is taxable or not.

trial_period
INTEGER

The free time window for the customer to try the product. Used with trial_period_unit to create the free trial period.

For example: If trial_period: day and trial_period_unit: 14, the trial period would be 14 days.

trial_period_unit
STRING

The time unit for the trial period. Used with trial_period to create the free trial period.

For example: If trial_period: day and trial_period_unit: 14, the trial period would be 14 days.

Possible values are:

  • day
  • month

updated_at
DATE-TIME

The time the plan was last updated.

events (table), plan (attribute)

subscription
OBJECT

Applicable when events.event_type is one of the following:

  • customer_deleted
  • payment_succeeded
  • payment_failed
  • payment_refunded
  • payment_initiated
  • refund_initiated
  • subscription_created
  • subscription_started
  • subscription_trial_end_reminder
  • subscription_activated
  • subscription_changed
  • subscription_cancellation_scheduled
  • subscription_cancellation_reminder
  • subscription_cancelled
  • subscription_reactivated
  • subscription_renewed
  • subscription_scheduled_cancellation_removed
  • subscription_changes_scheduled
  • subscription_scheduled_changes_removed
  • subscription_shipping_address_updated
  • subscription_deleted
  • subscription_paused
  • subscription_pause_scheduled
  • subscription_scheduled_pause_removed
  • subscription_resumed
  • subscription_resumption_scheduled
  • subscription_scheduled_resumption_removed
  • subscription_renewal_reminder

activated_at
DATE-TIME

The time at which the subscription moved from in_trial to active.

addons
ARRAY

Details about the addon(s) associated with the subscription.

id
STRING

The addon ID.

Reference:

object
STRING

quantity
INTEGER

Applicable only for the quantity based addons. The quantity.

remaining_billing_cycles
INTEGER

The number of billing cycles this addon will be attached to subscription.

trial_end
DATE-TIME

The time at which the trial ends for the addon.

unit_price
INTEGER

The amount that will override the addon’s default price. The plan’s billing frequency will not be considered for overriding. E.g. If the plan’s billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).

events (table), addons (attribute)

affiliate_token
STRING

A unique tracking token for the subscription.

auto_collection
STRING

Defines whether payments need to be collected automatically for this subscription. Possible values are:

  • on
  • off

base_currency_code
STRING

The base currency code for the subscription in ISO 4217 format.

billing_period
INTEGER

Defines the billing frequency for the subscription. Used with billing_period_unit, this determines how the customer is billed for the subscription.

For example: If billing_period_unit: week and billing_period: 3, the customer would be billed every 3 weeks.

billing_period_unit
STRING

Defines the billing period for the subscription. Used with billing_period, this determines how the customer is billed for the subscription.

For example: If billing_period_unit: week and billing_period: 3, the customer would be billed every 3 weeks.

Possible values are:

  • day
  • week
  • month
  • year

cancel_reason
STRING

The possible reason the subscription might be cancelled. Possible values are:

  • not_paid
  • no_card
  • fraud_review_failed
  • non_compliant_eu_customer
  • tax_calculation_failed
  • currency_incompatible_with_gateway
  • non_compliant_customer

cancelled_at
DATE-TIME

The time at which subscription was cancelled or is set to be cancelled.

charged_event_based_addons
ARRAY

A list of event-based addons that have already been charged.

id
STRING

The addon ID.

Reference:

last_charged_at
DATE-TIME

The time when the addon was last charged for the subscription.

object
STRING

events (table), charged_event_based_addons (attribute)

coupon
STRING

coupons
ARRAY

Details about the coupon(s) associated with the subscription.

applied_count
INTEGER

The number of times the coupon has been applied for the subscription.

apply_till
DATE-TIME

Applicable for limited month coupons. The date till the coupon is to be applied.

coupon_code
STRING

The coupon code used to redeem the coupon.

coupon_id
STRING

The coupon ID.

Reference:

object
STRING

events (table), coupons (attribute)

created_at
DATE-TIME

The time the subscription was created.

currency_code
STRING

The currency code for the subscription in ISO 4217 format.

current_term_end
DATE-TIME

The end of the current billing term for the subscription, after which the subscription will be immediately renewed.

current_term_start
DATE-TIME

The start of the current billing term for the subscription.

customer_id
STRING

The ID of the customer associated with the subscription.

Reference:

deleted
BOOLEAN

Indicates if the subscription has been deleted or not.

due_invoices_count
INTEGER

The total number of invoices that are due for payment.

event_based_addons
ARRAY

A list of non-recurring addons associated with the subscription that will be charged on the occurrence of a specified event.

charge_once
BOOLEAN

If enabled, the addon will be charged only at the first occurrence of the event.

id
STRING

The addon ID.

Reference:

object
STRING

on_event
STRING

The event on which the addon will be charged.

quantity
INTEGER

Applicable only for the quantity based addons. The addon quantity.

unit_price
INTEGER

The amount that will override the addon’s default price. The plan’s billing frequency will not be considered for overriding. E.g. If the plan’s billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).

events (table), event_based_addons (attribute)

exchange_rate
NUMBER

The exchange rate used for base currency conversion.

has_scheduled_changes
BOOLEAN

If true, there are subscription changes scheduled on next renewal.

id
STRING

The subscription ID.

Reference:

invoice_notes
STRING

The invoice notes for the subscription.

mrr
INTEGER

The monthly recurring revenue for the subscription, in cents.

next_billing_at
DATE-TIME

The date on which the next billing occurs.

object
STRING

payment_source_id
STRING

The ID of the payment source associated with the subscription.

Reference:

plan_amount
INTEGER

plan_free_quantity
INTEGER

The units of the item that will be free with the plan associated with the subscription.

plan_id
STRING

The ID of the plan associated with the subscription.

Reference:

plan_quantity
INTEGER

The plan quantity for the subscription.

plan_unit_price
INTEGER

The amount that will override the plan’s default price.

po_number
STRING

The purchase order number associated with the subscription.

referral_info
OBJECT

The referral details for the subscription, if applicable.

account_id
STRING

The referral account ID.

campaign_id
STRING

The referral campaign ID.

coupon_code
STRING

The referral coupon code.

destination_url
STRING

The destination URL for the campaign.

external_campaign_id
STRING

The campaign ID in an external reference system.

external_reference_id
STRING

The reference ID in an external reference system.

friend_offer_type
STRING

The friend offer type for the referral campaign. Possible values are:

  • none
  • coupon
  • coupon_code

notify_referral_system
STRING

Indicates whether referral purchases should be notified to the referral system. Possible values are:

  • none
  • first_paid_conversion
  • all_invoices

post_purchase_widget_enabled
BOOLEAN

Indicates if a post purchase widget is enabled for the campaign.

referral_code
STRING

The referral code.

referral_status
STRING

referrer_id
STRING

The referrer ID.

referrer_reward_type
STRING

The referrer reward type for the referral campaign. Possible values are:

  • none
  • referral_direct_reward
  • custom_promotional_credit
  • custom_revenue_percent_based

reward_status
STRING

The reward status for the referral subscription. Possible values are:

  • pending
  • paid
  • invalid
events (table), referral_info (attribute)

remaining_billing_cycles
INTEGER

The number of billing cycles the subscription will run.

resource_version
INTEGER

The version number of the subscription. Each update of the subscription results in an incremental change of this value. Note: This attribute will be present only if the resource has been updated after 2016-09-28.

shipping_address
OBJECT

The shipping address for the subscription.

city
STRING

The city.

company
STRING

The company.

country
STRING

The country.

email
STRING

The email.

first_name
STRING

The first name.

last_name
STRING

The last name.

line1
STRING

The first line of the address.

line2
STRING

The second line of the address.

line3
STRING

The third line of the address.

phone
STRING

The phone number.

state
STRING

The state or province.

state_code
STRING

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India.

validation_status
STRING

The address verification status. Possible values are:

  • not_validated
  • valid
  • partially_valid
  • invalid

zip
STRING

The zip or postal code.

events (table), shipping_address (attribute)

start_date
DATE-TIME

Applicable only when status: future. The scheduled start time of the future subscription.

started_at
DATE-TIME

The time when the subscription started. This value will be null for future subscriptions.

status
STRING

The current status of the subscription. Possible values are:

  • future
  • in_trial
  • active
  • non_renewing
  • paused
  • cancelled

trial_end
DATE-TIME

The end of the trial period for the subscription. The presence of this value for future subscriptions (status: future) implies the subscription will move to in_trial when the subscription starts.

trial_start
DATE-TIME

The start of the trial period for the subscription. The presence of this value for future subscriptions (status: future) implies the subscription will move to in_trial when the subscription starts.

updated_at
DATE-TIME

The time the subscription was last updated.

events (table), subscription (attribute)

transaction
OBJECT

Applicable when events.event_type is one of the following:

  • authorization_succeeded
  • authorization_voided
  • payment_succeeded
  • payment_failed
  • payment_refunded
  • payment_initiated
  • refund_initiated
  • transaction_created
  • transaction_updated
  • transaction_deleted

amount
INTEGER

The amount for the transaction.

amount_unused
INTEGER

Applicable only for payments. The unused amount present for the transaction.

base_currency_code
STRING

currency_code
STRING

The currency code for the transaction, in ISO 4217 format.

customer_id
STRING

The ID of the customer associated with the transaction.

Reference:

date
DATE-TIME

The date the transaction occurred.

deleted
BOOLEAN

Indicates if the transaction has been deleted.

error_code
STRING

The error code received from the payment gateway on failure.

error_text
STRING

The error message received from the payment gateway on failure.

exchange_rate
NUMBER

fraud_flag
STRING

Indicates whether or not the transaction has been identified as fraudulent. Possible values are:

  • safe
  • suspicious
  • fraudulent

fraud_reason
STRING

A short description why the transaction was marked as fraudulent or suspicious.

gateway
STRING

The name of the gateway used to process the transaction.

gateway_account_id
STRING

The account ID of the gateway used to process the transaction.

id
STRING

The transaction ID.

Reference:

id_at_gateway
STRING

The ID with which the transaction is referred in the gateway.

linked_credit_notes
ARRAY

Applicable only for refund transactions. The list of credit notes the transaction is associated with.

applied_amount
INTEGER

The transaction amount applied to the invoice.

applied_at
DATE-TIME

The time the credit note was applied.

cn_date
DATE-TIME

The date the credit note was created.

cn_id
STRING

The credit note ID.

Reference:

cn_reason_code
STRING

The reason for the credit note. Possible values are:

  • write_off
  • subscription_change
  • subscription_cancellation
  • subscription_pause
  • chargeback
  • product_unsatisfactory
  • service_unsatisfactory
  • order_change
  • order_cancellation
  • waiver
  • other
  • fraudulent

cn_reference_invoice_id
STRING

The invoice ID.

Reference:

cn_status
STRING

The status of the credit note. Possible values are:

  • adjusted
  • refunded
  • refund_due
  • voided

cn_total
INTEGER

The total amount of the credit note.

events (table), linked_credit_notes (attribute)

linked_invoices
ARRAY

Applicable only for payment transactions. The list of invoices the transaction has been applied to.

applied_amount
INTEGER

The transaction amount applied to the invoice.

applied_at
DATE-TIME

The time at which the transaction was applied.

invoice_date
DATE-TIMES

The date the invoice was issued.

invoice_id
STRING

The invoice ID.

Reference:

invoice_status
STRING

The current status of the invoice. Possible values are:

  • paid
  • posted
  • payment_due
  • not_paid
  • voided
  • pending

invoice_total
INTEGER

The total amount of the invoice.

events (table), linked_invoices (attribute)

linked_refunds
ARRAY

Applicable only for payment transactions. The list of refunds issued for the payment transaction.

txn_amount
INTEGER

The total amount of the transaction.

txn_date
DATE-TIME

The date the transaction occured.

txn_id
STRING

the transaction ID.

Reference:

txn_status
STRING

The status of the transaction. Possible values are:

  • in_progress
  • success
  • voided
  • failure
  • timeout
  • needs_attention
events (table), linked_refunds (attribute)

masked_card_number