API Version
Product Catalog
Library

API V2 Upgradation Guide

As all of our future development will happen in API V2, the latest version of Chargebee API, you might want to upgrade to V2 to benefit from the new functionality.


Note: If you are processing Webhooks, you also need to transition those Webhook(s) to API V2. More details here

What's changed in API V2 ?

The changes made in V2 that are not V1-compatible, are listed in this section. You may want to change your existing code appropriately as part of the upgradation process.

Refunds-related changes to Invoice and Transaction resources:

In API V1, refunds were directly linked to Invoices. In V2, refunds are not directly linked to Invoices; instead they are linked to Credit Notes, which in turn are linked to their respective invoices.

Changes to Estimate Resource:

The Estimate resource has been revamped in V2: in V1 it had both subscription and invoice related attributes without any segregation at the top level. Whereas in V2, all the subscription related attributes are grouped under subscription_estimate sub-resource and all the invoice related attributes are grouped under invoice_estimate sub-resource. Additionally, the following changes have been made:

  • The attribute collect_now has been removed. The invoice_estimate returned by the 'Create Subscription' and 'Change Subscription' Estimates, will represent the estimate of the invoice that will get generated immediately.
  • If no invoice gets generated during Estimate invocations ('Create Subscription Estimate', etc.), the invoice_estimate sub-resource will not be returned.
  • The invoice_estimate returned by Estimate operations (such as 'Change Subscription Estimate') will include the existing customer balances - Promotional Credits, Refundable Credits, and Excess Payments - by default. This is not the default behavior in API V1.

Country input parameters - strict validation done:

For the 'country' input parameters - card[billing_country], billing_address[country], shipping_address[country], address[country] - in the operations like 'Create Subscription' etc, the 2-letter ISO 3166 alpha-2 code is expected. But in V1, for few sites, we were allowing values in other formats too (like full country names). In V2, only the 2-letter ISO 3166 codes are allowed. For other formats, error will be thrown.

Invoice subtotal:

In API V1 the sub_total attribute is the sum of all the line items and discounts. Whereas in V2, this is sum of line items and item-level discount amounts alone. So in V2, document-level discounts are not part of the sub_total.

Void and Delete Invoice operations:

With V2, when an invoice is voided/deleted, and 'Prorated credits' have been applied to the invoice, they will be reclaimed and added back to the subscription.

Attributes and operations that have been renamed/removed:

This section provides the complete listing of the attributes and operations that have been renamed/removed in API V2 for a more streamlined functionality:

Customer Resource:

Account Credits are now called Promotional Credits. We have renamed the related attributes and operations to reflect the same:

Invoice Resource:
  • Operation Collect (which is used for closing a pending invoice) is renamed to 'Close'
  • The following Invoice attributes are renamed:
    • end_date is renamed to date.
    • amount is renamed to total.
    • paid_on is renamed to paid_at.
    • next_retry is renamed to next_retry_at.
    • line_items[].tax is renamed to line_items[].tax_amount.
    • discounts[].type is renamed to discounts[].entity_type.
  • The attribute start_date is removed.
  • The attribute line_items[].type is removed (line_items[].entity_type captures all the required details in API V2).
  • The attribute linked_transactions[] is removed. More details here
Transaction Resource:
  • The attribute linked_invoices[].invoice_amount is renamed to linked_invoices[].invoice_total.
  • The attribute linked_invoices[] is not applicable for 'refund' type in V2. More details here.
  • The operation List transactions for an invoice is removed. More details here.
  • The operation Record payment for an invoice is moved under Invoice resource in V2.
Estimate Resource:

Estimate resource is completely revamped in V2. More details here.

Event Resource:

The following event types are renamed in API V2:

  • subscription_trial_ending is renamed to subscription_trial_end_reminder.
  • subscription_cancelling is renamed to subscription_cancellation_reminder.
  • invoice_created is renamed to pending_invoice_created.
  • card_expiring is renamed to card_expiry_reminder.

Transitioning Webhooks from V1 to V2

As part of the upgradation process, you need to move your webhooks too, from V1 to V2.

Note: If you have configured webhooks for third party apps/plug-ins such as Zapier, WordPress, Salesforce, etc., you might want to check with the app/plug-in developer before transitioning to V2.

To transition webhooks to API version V2:

  1. Designate a different URL endpoint (different from that of your V1 based webhook URL) for processing the API V2 based events.
  2. Follow these step during your deployment process:
    1. Just before starting the deployment, create a webhook for the new URL. Specify its API Version as 'V2'.
    2. Immediately remove the V1 based webhook.
    3. Deploy the API V2 client library in your webhook server(s). During this deployment time, few webhook notifications (till your webhook servers are completely up) may fail. However, Chargebee will do automatic retries, so the missed events will get processed once your webhook servers are up.

If you require assistance for transitioning your webhooks to API version V2, reach out to support.