Loading Data from Chargebee to Azure Cosmos DB with dlt in Python
tip
We will be using the dlt PostgreSQL destination to connect to Azure Cosmos DB. You can get the connection string for your Azure Cosmos DB database as described in the Azure Cosmos DB Docs.
Need help deploying these pipelines, or figuring out how to run them in your data stack?
Join our Slack community or book a call with our support engineer Violetta.
Chargebee is a subscription management system that handles all aspects of the subscription lifecycle, including recurring billing, invoicing, and trial management. It provides a flexible billing system for running promotions and tools for accurate billing and faster response to billing queries. Chargebee also supports online payment collection through various payment gateways. Azure Cosmos DB is a fully managed NoSQL and relational database designed for modern app development. This documentation will guide you on how to load data from Chargebee to Azure Cosmos DB using the open-source Python library dlt. For more information about Chargebee, visit their website.
dlt Key Features
- Pipeline Metadata:
dltpipelines leverage metadata to provide governance capabilities, including load IDs for incremental transformations and data lineage. Learn more - Schema Enforcement and Curation:
dltempowers users to enforce and curate schemas, ensuring data consistency and quality. Read more - Schema Evolution:
dltalerts users to schema changes, allowing proactive governance and necessary actions. Discover more - Scalability:
dltoffers mechanisms and configuration options to scale up pipelines, including parallel processing and fine-tuning memory buffers. Explore performance - Advanced Topics:
dltis a constantly growing library that supports many features and use cases needed by the community. Join the Slack community
Getting started with your pipeline locally
dlt-init-openapi0. Prerequisites
dlt and dlt-init-openapi requires Python 3.9 or higher. Additionally, you need to have the pip package manager installed, and we recommend using a virtual environment to manage your dependencies. You can learn more about preparing your computer for dlt in our installation reference.
1. Install dlt and dlt-init-openapi
First you need to install the dlt-init-openapi cli tool.
pip install dlt-init-openapi
The dlt-init-openapi cli is a powerful generator which you can use to turn any OpenAPI spec into a dlt source to ingest data from that api. The quality of the generator source is dependent on how well the API is designed and how accurate the OpenAPI spec you are using is. You may need to make tweaks to the generated code, you can learn more about this here.
# generate pipeline
# NOTE: add_limit adds a global limit, you can remove this later
# NOTE: you will need to select which endpoints to render, you
# can just hit Enter and all will be rendered.
dlt-init-openapi chargebee --url https://openapi.chargebee.com/v2-pcv2/index.json --global-limit 2
cd chargebee_pipeline
# install generated requirements
pip install -r requirements.txt
The last command will install the required dependencies for your pipeline. The dependencies are listed in the requirements.txt:
dlt>=0.4.12
You now have the following folder structure in your project:
chargebee_pipeline/
├── .dlt/
│ ├── config.toml # configs for your pipeline
│ └── secrets.toml # secrets for your pipeline
├── rest_api/ # The rest api verified source
│ └── ...
├── chargebee/
│ └── __init__.py # TODO: possibly tweak this file
├── chargebee_pipeline.py # your main pipeline script
├── requirements.txt # dependencies for your pipeline
└── .gitignore # ignore files for git (not required)
1.1. Tweak chargebee/__init__.py
This file contains the generated configuration of your rest_api. You can continue with the next steps and leave it as is, but you might want to come back here and make adjustments if you need your rest_api source set up in a different way. The generated file for the chargebee source will look like this:
Click to view full file (1885 lines)
from typing import List
import dlt
from dlt.extract.source import DltResource
from rest_api import rest_api_source
from rest_api.typing import RESTAPIConfig
@dlt.source(name="chargebee_source", max_table_nesting=2)
def chargebee_source(
username: str = dlt.secrets.value,
password: str = dlt.secrets.value,
base_url: str = dlt.config.value,
) -> List[DltResource]:
# source configuration
source_config: RESTAPIConfig = {
"client": {
"base_url": base_url,
"auth": {
"type": "http_basic",
"username": username,
"password": password,
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"",
"maximum_offset":
20,
},
},
"resources":
[
# Retrieves an address resource for a subscription and the specified label.
{
"name": "retrieve_an_address",
"table_name": "address",
"endpoint": {
"data_selector": "address",
"path": "/addresses",
"params": {
"subscription_id": "FILL_ME_IN", # TODO: fill in required query parameter
"label": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# **Caution** This API cannot be used for subscriptions that have [ramp](ramps?prod_cat_ver=2)s. Retrieves the *advance_invoice_schedule* for a subscription. Note that this endpoint is only applicable for *schedule_type = specific_dates* or fixed_intervals.
{
"name": "retrieve_advance_invoice",
"table_name": "advance_invoice_schedule",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "advance_invoice_schedules",
"path": "/subscriptions/{subscription-id}/retrieve_advance_invoice_schedule",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Returns the set of all applicable [addon-items](items?prod_cat_ver=2#addon-items) for a specific [plan-item price](item_prices?prod_cat_ver=2#types). This set consists of all addon-items whose item prices can be applied to a subscription having the plan-item price in it. When determining this set, Chargebee considers the [item_applicability](items?prod_cat_ver=2#item_item_applicability) and [applicable_items](items?prod_cat_ver=2#item_applicable_items) defined for the parent item of the plan-item price.
{
"name": "list_applicable_items_for_a_plan_item_price",
"table_name": "applicable_item",
"endpoint": {
"data_selector": "list",
"path": "/item_prices/{item-price-id}/applicable_items",
"params": {
"item-price-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Returns the set of all applicable [addon-item](item_prices?prod_cat_ver=2#types) prices for a specific plan-item price. This set consists of all the addon-item prices that can be applied to a subscription having the plan-item price. When determining this set, Chargebee considers the following: * the [item_applicability](items?prod_cat_ver=2#item_item_applicability) and [applicable_items](items?prod_cat_ver=2#item_applicable_items) defined for the parent item of the plan-item price * the [compatibility](subscriptions?prod_cat_ver=2#compatibility) of the addon-item prices to the plan-item price **Note** If an addon-item price has [differential pricing](differential_prices?prod_cat_ver=2) defined against the parent item of the plan-item price, then the pricing information in the addon-item price object returned, reflects the differential pricing.
{
"name": "list_applicable_item_prices_for_a_plan_item_price",
"table_name": "applicable_item_price",
"endpoint": {
"data_selector": "list",
"path": "/item_prices/{item-price-id}/applicable_item_prices",
"params": {
"item-price-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "item_id": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves details of an attached addon or a charge item.
{
"name": "retrieve_an_attached_item",
"table_name": "attached_item",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "attached_item",
"path": "/attached_items/{attached-item-id}",
"params": {
"attached-item-id": "FILL_ME_IN", # TODO: fill in required path parameter
"parent_item_id": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# Returns a list of attached items satisfying **all** the conditions specified in the filter parameters below. The list is sorted by the date of creation in descending order (latest first).
{
"name": "list_attached_items",
"table_name": "attached_item",
"endpoint": {
"data_selector": "list",
"path": "/items/{item-id}/attached_items",
"params": {
"item-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "item_id": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "item_type": "OPTIONAL_CONFIG",
# "charge_on_event": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
},
}
},
# #### Deprecated This operation is obsoleted by the [Retrieve a payment source API](/docs/api/payment_sources#retrieve_a_payment_source). Retrieves the credit card for the customer id.
{
"name": "retrieve_card_for_a_customer",
"table_name": "card",
"endpoint": {
"data_selector": "card",
"path": "/cards/{customer-id}",
"params": {
"customer-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieve a comment for an entity identified by comment ID.
{
"name": "retrieve_a_comment",
"table_name": "comment",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "comment",
"path": "/comments/{comment-id}",
"params": {
"comment-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieve the list of comments sorted by the recent ones on the top. If you want to retrieve the list of comments for an [entity](https://apidocs.chargebee.com/docs/api/v1/comments?prod_cat_ver=1#list_comments_entity_type), for example, subscription you can filter them by passing the entity type and unique identifier for that entity, for example, subscription ID.
{
"name": "list_comments",
"table_name": "comment",
"endpoint": {
"data_selector": "list",
"path": "/comments",
"params": {
# the parameters below can optionally be configured
# "entity_type": "OPTIONAL_CONFIG",
# "entity_id": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This API retrieves all the contacts for a customer.
{
"name": "list_of_contacts_for_a_customer",
"table_name": "contact",
"endpoint": {
"data_selector": "list",
"path": "/customers/{customer-id}/contacts",
"params": {
"customer-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves a list of contract term resources for the subscription specified in the path.
{
"name": "list_contract_terms_for_a_subscription",
"table_name": "contract_term",
"endpoint": {
"data_selector": "list",
"path": "/subscriptions/{subscription-id}/contract_terms",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# List all the available coupons that are created for a specific promotion or offers. You can find list of coupon codes that are currently active, expired, archived or deleted.
{
"name": "list_coupons",
"table_name": "coupon",
"endpoint": {
"data_selector": "list",
"path": "/coupons",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "discount_type": "OPTIONAL_CONFIG",
# "duration_type": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "apply_on": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
# "currency_code": "OPTIONAL_CONFIG",
},
}
},
# This API retrieves a specific coupon using the coupon ID.
{
"name": "retrieve_a_coupon",
"table_name": "coupon",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "coupon",
"path": "/coupons/{coupon-id}",
"params": {
"coupon-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# List the available coupon codes.
{
"name": "list_coupon_codes",
"table_name": "coupon_code",
"endpoint": {
"data_selector": "list",
"path": "/coupon_codes",
"params": {
# the parameters below can optionally be configured
# "code": "OPTIONAL_CONFIG",
# "coupon_id": "OPTIONAL_CONFIG",
# "coupon_set_name": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a specific coupon code details.
{
"name": "retrieve_a_coupon_code",
"table_name": "coupon_code",
"endpoint": {
"data_selector": "coupon_code",
"path": "/coupon_codes/{coupon-code-code}",
"params": {
"coupon-code-code": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Use this API to get the list of all the coupon sets.
{
"name": "list_coupon_sets",
"table_name": "coupon_set",
"endpoint": {
"data_selector": "list",
"path": "/coupon_sets",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "coupon_id": "OPTIONAL_CONFIG",
# "total_count": "OPTIONAL_CONFIG",
# "redeemed_count": "OPTIONAL_CONFIG",
# "archived_count": "OPTIONAL_CONFIG",
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"list.[*].coupon_set.total_count",
},
}
},
# Use this API to retrieve a specific coupon set.
{
"name": "retrieve_a_coupon_set",
"table_name": "coupon_set",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "coupon_set",
"path": "/coupon_sets/{coupon-set-id}",
"params": {
"coupon-set-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Lists all the Credit Notes.
{
"name": "list_credit_notes",
"table_name": "credit_note",
"endpoint": {
"data_selector": "list",
"path": "/credit_notes",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
# "subscription_id": "OPTIONAL_CONFIG",
# "reference_invoice_id": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "reason_code": "OPTIONAL_CONFIG",
# "create_reason_code": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "date": "OPTIONAL_CONFIG",
# "total": "OPTIONAL_CONFIG",
# "price_type": "OPTIONAL_CONFIG",
# "amount_allocated": "OPTIONAL_CONFIG",
# "amount_refunded": "OPTIONAL_CONFIG",
# "amount_available": "OPTIONAL_CONFIG",
# "voided_at": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
# "channel": "OPTIONAL_CONFIG",
# "einvoice": "OPTIONAL_CONFIG",
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"list.[*].credit_note.total",
},
}
},
# Retrieves the Credit Note identified by the specified Credit Note number.
{
"name": "retrieve_a_credit_note",
"table_name": "credit_note",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "credit_note",
"path": "/credit_notes/{credit-note-id}",
"params": {
"credit-note-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API is used to retrieve an individual currency object configured within this site.
{
"name": "retrieve_a_currency",
"table_name": "currency",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "currency",
"path": "/currencies/{site-currency-id}",
"params": {
"site-currency-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API is used to retrieve the list of all currencies currently configured within the site.
{
"name": "list_currencies",
"table_name": "currency",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "currency",
"path": "/currencies/list",
}
},
# Retrieves meta data of specific custom field.
{
"name": "retrieve_the_meta_data",
"table_name": "custom_field_config",
"endpoint": {
"data_selector": "custom_field_config",
"path": "/custom_field_configs/retrieve",
"params": {
"entity_type": "FILL_ME_IN", # TODO: fill in required query parameter
"api_name": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# Retrieves the list of custom fields meta data.
{
"name": "list_custom_field_configs",
"table_name": "custom_field_config",
"endpoint": {
"data_selector": "list",
"path": "/custom_field_configs",
"params": {
# the parameters below can optionally be configured
# "entity_type": "OPTIONAL_CONFIG",
},
}
},
# Retrieves the details of the desired customer. You can use the unique identifier for a particular customer to retrieve the desired details.
{
"name": "retrieve_a_customer",
"table_name": "customer",
"endpoint": {
"data_selector": "$",
"path": "/customers/{customer-id}",
"params": {
"customer-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves a list of customers added to your Chargebee site. The list contains the necessary customer details such as First Name, Last Name and the Customer ID.
{
"name": "list_customers",
"table_name": "customer",
"endpoint": {
"data_selector": "list",
"path": "/customers",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "first_name": "OPTIONAL_CONFIG",
# "last_name": "OPTIONAL_CONFIG",
# "email": "OPTIONAL_CONFIG",
# "company": "OPTIONAL_CONFIG",
# "phone": "OPTIONAL_CONFIG",
# "auto_collection": "OPTIONAL_CONFIG",
# "taxability": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "offline_payment_method": "OPTIONAL_CONFIG",
# "auto_close_invoices": "OPTIONAL_CONFIG",
# "channel": "OPTIONAL_CONFIG",
# "business_entity_id": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
# "relationship": "OPTIONAL_CONFIG",
},
}
},
# Returns a list of differential prices satisfying **all** the conditions specified in the filter parameters below. The list is sorted by the date of creation in descending order (latest first).
{
"name": "list_differential_prices",
"table_name": "differential_price",
"endpoint": {
"data_selector": "list",
"path": "/differential_prices",
"params": {
# the parameters below can optionally be configured
# "item_price_id": "OPTIONAL_CONFIG",
# "item_id": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "parent_item_id": "OPTIONAL_CONFIG",
},
}
},
# Retrieve a differential price using a `differential_price_id` and `item_price_id`.
{
"name": "retrieve_a_differential_price",
"table_name": "differential_price",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "differential_price",
"path": "/differential_prices/{differential-price-id}",
"params": {
"differential-price-id": "FILL_ME_IN", # TODO: fill in required path parameter
"item_price_id": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# Retrieves a list of [discount](discounts) resources [currently attached](subscriptions#subscription_discounts) to a specific subscription. The list is sorted in descending order based on the [created_at](discounts#discount_created_at) timestamp. **Note** This endpoint does not return [coupon](coupons) or [coupon_code](coupon_codes) resources.
{
"name": "list_discounts_for_a_subscription",
"table_name": "discount",
"endpoint": {
"data_selector": "list",
"path": "/subscriptions/{subscription-id}/discounts",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Download the e-invoice in both XML and PDF formats. The response consists of a `download` object for each format. The XML format follows the [structure as per Peppol BIS Billing v3.0](https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/tree/). **Note** * You can only download e-invoices when their `status` is `success`. * There are some cases in which the PDF is not available for download. In such cases, you can obtain it from the XML by decoding the value for [cbc:EmbeddedDocumentBinaryObject](https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/cac-AdditionalDocumentReference/cac-Attachment/cbc-EmbeddedDocumentBinaryObject/), which is the Base64-encoded version of the PDF.
{
"name": "download_e_invoice",
"table_name": "download",
"endpoint": {
"data_selector": "downloads",
"path": "/invoices/{invoice-id}/download_einvoice",
"params": {
"invoice-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Download the e-invoice for the credit note in both XML and PDF formats. The response consists of a `download` object for each format. The XML format follows the [structure as per Peppol BIS Billing v3.0](https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-creditnote/tree/). **Note** * You can only download e-invoices when their `status` is `success` or `registered`. * There are some cases in which the PDF is not available for download. In such cases, you can obtain it from the XML by decoding the value for [cbc:EmbeddedDocumentBinaryObject](https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-creditnote/cac-AdditionalDocumentReference/cac-Attachment/cbc-EmbeddedDocumentBinaryObject/), which is the Base64-encoded version of the PDF.
{
"name": "download_e_invoice_for_credit_note",
"table_name": "download",
"endpoint": {
"data_selector": "downloads",
"path": "/credit_notes/{credit-note-id}/download_einvoice",
"params": {
"credit-note-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves a list of all the `entitlement`s associated with the specified `feature`.
{
"name": "list_all_entitlements",
"table_name": "entitlement",
"endpoint": {
"data_selector": "list",
"path": "/entitlements",
"params": {
# the parameters below can optionally be configured
# "feature_id": "OPTIONAL_CONFIG",
# "entity_type": "OPTIONAL_CONFIG",
# "entity_id": "OPTIONAL_CONFIG",
},
}
},
# Retrieve the list of entitlement overrides for a subscription.
{
"name": "list_entitlement_overrides_for_a_subscription",
"table_name": "entitlement_override",
"endpoint": {
"data_selector": "list",
"path": "/subscriptions/{subscription-id}/entitlement_overrides",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves list of events.
{
"name": "list_events",
"table_name": "event",
"endpoint": {
"data_selector": "list",
"path": "/events",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "webhook_status": "OPTIONAL_CONFIG",
# "event_type": "OPTIONAL_CONFIG",
# "source": "OPTIONAL_CONFIG",
# "occurred_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a specific event identified by a unique event identifier. **Note:** Only events that are less than 90 days old will be retrieved.
{
"name": "retrieve_an_event",
"table_name": "event",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "event",
"path": "/events/{event-id}",
"params": {
"event-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API gets the status of the export job initiated by the Exports API. If the export job is completed, the downloads resource will also be obtained in the API response. The returned URL in the downloads resource is secure and can be downloaded. The URL expires after 4 hours. Please note that this is a public URL, and can be downloaded by anyone with whom it's shared. **Note:** In case the export is in Failed or In-process state, then the downloads resource will not be available.
{
"name": "retrieve_an_export",
"table_name": "export",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "export",
"path": "/exports/{export-id}",
"params": {
"export-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves a list of features meeting **all** the conditions specified in the filter parameters.
{
"name": "list_features",
"table_name": "feature",
"endpoint": {
"data_selector": "list",
"path": "/features",
"params": {
# the parameters below can optionally be configured
# "name": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
},
}
},
# Retrieve a specific feature using its ID.
{
"name": "retrieve_a_feature",
"table_name": "feature",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "feature",
"path": "/features/{feature-id}",
"params": {
"feature-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This endpoint retrieves the status of your data export request.
{
"name": "retrieve_full_export_status",
"table_name": "full_export",
"endpoint": {
"data_selector": "full_export",
"path": "/full_exports/status",
"params": {
"table": "FILL_ME_IN", # TODO: fill in required query parameter
"date": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# Retrieves the list of gifts.
{
"name": "list_gifts",
"table_name": "gift",
"endpoint": {
"data_selector": "list",
"path": "/gifts",
"params": {
# the parameters below can optionally be configured
# "status": "OPTIONAL_CONFIG",
# "gift_receiver": "OPTIONAL_CONFIG",
# "gifter": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a gift subscription. This API accepts the gift 'id' and returns the gift along with the subscription.
{
"name": "retrieve_a_gift",
"table_name": "gift",
"endpoint": {
"data_selector": "$",
"path": "/gifts/{gift-id}",
"params": {
"gift-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves the full or partial [account hierarchy](/docs/api/hierarchies) for a customer.
{
"name": "get_hierarchy",
"table_name": "hierarchy",
"endpoint": {
"data_selector": "hierarchies",
"path": "/customers/{customer-id}/hierarchy",
"params": {
"customer-id": "FILL_ME_IN", # TODO: fill in required path parameter
"hierarchy_operation_type": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# This API retrieves the list of hosted page resources.
{
"name": "list_hosted_pages",
"table_name": "hosted_page",
"endpoint": {
"data_selector": "list",
"path": "/hosted_pages",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "state": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
},
}
},
# When you retrieve a hosted page whose `status` is `successful`, the `content` attribute has the following objects based on the `type` of the hosted page. |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **`type` of hosted page** | **`content` attribute constituents** | | `checkout_new` | * `customer`: the object representing the details of the [Customer](/docs/api/customers#customer_attributes) for whom the subscription was created. * `subscription`: the new Subscription object created. * `card`: the [Card](/docs/api/cards#card_attributes) object if the [payment method](/docs/api/customers#customer_payment_method) `type` used was `card`. * `invoice`: the Invoice object, if an invoice was generated. | | `checkout_existing` | * `customer`: the object representing the details of the [Customer](/docs/api/customers#customer_attributes) whose subscription was changed. * `subscription`: the updated Subscription object created. * `card`: the [Card](/docs/api/cards#card_attributes) object if the [payment method](/docs/api/customers#customer_payment_method) `type` used was `card`. * `invoice`: the Invoice object, if an invoice was generated for the subscription change. | | `update_payment_method` | * `customer`: the object representing the details of the [Customer](/docs/api/customers#customer_attributes) whose subscription was changed. * `card`: the [Card](/docs/api/cards#card_attributes) object if the new [payment method](/docs/api/customers#customer_payment_method) added was of `type` `card`. | | `pre_cancel` | `retention`: Use the `bypass` flag in this object to route the cancellation flow to the merchants' portal or the Chargebee Retention. * If `bypass` flag is `true`, you should route the end-customers to your native cancellation flow. * If the `bypass` flag is `false`, you should route the end-customers to the hosted page URL. **Note:** Retention is currently in `beta`. To enable Retention, [Contact Support.](https://support.chargebee.com/support/home) | | `collect_now` | * `transactions`: this object should contain a list of [transactions](/docs/api/transactions#transaction_attributes) triggered from the `collect_now` hosted page. Each transaction in the list should be represented as an array that includes relevant information about the transaction, such as transaction ID, customer ID, amount, currency, payment method, and any other relevant details. * `customer`: this object should contain the customer record associated with the transaction. The key, `customer_id` is used to link the transaction to the corresponding customer record. |
{
"name": "retrieve_a_hosted_page",
"table_name": "hosted_page",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "hosted_page",
"path": "/hosted_pages/{hosted-page-id}",
"params": {
"hosted-page-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Lists the installments that match the criteria provided in the filter parameters.
{
"name": "list_installments",
"table_name": "installment",
"endpoint": {
"data_selector": "list",
"path": "/installments",
"params": {
"invoice_id": "FILL_ME_IN", # TODO: fill in required query parameter
# the parameters below can optionally be configured
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a specific installment resource.
{
"name": "retrieve_an_installment",
"table_name": "installment",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "installment",
"path": "/installments/{installment-id}",
"params": {
"installment-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This endpoint retrieves an installment_config resource.
{
"name": "retrieve_an_installment_config",
"table_name": "installment_config",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "installment_config",
"path": "/installment_configs/{installment-config-id}",
"params": {
"installment-config-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Lists all the Invoices.
{
"name": "list_invoices",
"table_name": "invoice",
"endpoint": {
"data_selector": "list",
"path": "/invoices",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "subscription_id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
# "recurring": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "price_type": "OPTIONAL_CONFIG",
# "date": "OPTIONAL_CONFIG",
# "paid_at": "OPTIONAL_CONFIG",
# "total": "OPTIONAL_CONFIG",
# "amount_paid": "OPTIONAL_CONFIG",
# "amount_adjusted": "OPTIONAL_CONFIG",
# "credits_applied": "OPTIONAL_CONFIG",
# "amount_due": "OPTIONAL_CONFIG",
# "dunning_status": "OPTIONAL_CONFIG",
# "payment_owner": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "channel": "OPTIONAL_CONFIG",
# "voided_at": "OPTIONAL_CONFIG",
# "void_reason_code": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
# "einvoice": "OPTIONAL_CONFIG",
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"list.[*].invoice.total",
},
}
},
# Retrieve the invoice for the specified invoice id.
{
"name": "retrieve_an_invoice",
"table_name": "invoice",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "invoice",
"path": "/invoices/{invoice-id}",
"params": {
"invoice-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Returns a list of items satisfying **all** the conditions specified in the filter parameters below. The list is sorted by date of creation, in descending order.
{
"name": "list_items",
"table_name": "item",
"endpoint": {
"data_selector": "list",
"path": "/items",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "item_family_id": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "item_applicability": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "is_giftable": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "enabled_for_checkout": "OPTIONAL_CONFIG",
# "enabled_in_portal": "OPTIONAL_CONFIG",
# "metered": "OPTIONAL_CONFIG",
# "usage_calculation": "OPTIONAL_CONFIG",
# "channel": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieve an item resource.
{
"name": "retrieve_an_item",
"table_name": "item",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "item",
"path": "/items/{item-id}",
"params": {
"item-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# **Deprecated** This endpoint remains operational, but we recommend transitioning to its successor: [List entitlements](entitlements?prod_cat_ver=2#list_all_entitlements). Retrieves a list of all the `item_entitlement`s for the `feature` specified.
{
"name": "list_item_entitlements_for_a_feature",
"table_name": "item_entitlement",
"endpoint": {
"data_selector": "list",
"path": "/features/{feature-id}/item_entitlements",
"params": {
"feature-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# **Deprecated** This endpoint remains operational, but we recommend transitioning to its successor: [List entitlements](entitlements?prod_cat_ver=2#list_all_entitlements). Retrieves a list of all the `item_entitlements` for the `item` specified.
{
"name": "list_item_entitlements_for_an_item",
"table_name": "item_entitlement",
"endpoint": {
"data_selector": "list",
"path": "/items/{item-id}/item_entitlements",
"params": {
"item-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Returns a list of item families satisfying **all** the conditions specified in the filter parameters below. The list is sorted by date of creation, in descending order.
{
"name": "list_item_families",
"table_name": "item_family",
"endpoint": {
"data_selector": "list",
"path": "/item_families",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
},
}
},
# This endpoint retrieves an item family based on the item family id.
{
"name": "retrieve_an_item_family",
"table_name": "item_family",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "item_family",
"path": "/item_families/{item-family-id}",
"params": {
"item-family-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API retrieves a specific item price using the id.
{
"name": "retrieve_an_item_price",
"table_name": "item_price",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "item_price",
"path": "/item_prices/{item-price-id}",
"params": {
"item-price-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Returns a list of item prices satisfying **all** the conditions specified in the filter parameters below. The list is sorted by the date of creation in descending order.
{
"name": "list_item_prices",
"table_name": "item_price",
"endpoint": {
"data_selector": "list",
"path": "/item_prices",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "pricing_model": "OPTIONAL_CONFIG",
# "item_id": "OPTIONAL_CONFIG",
# "item_family_id": "OPTIONAL_CONFIG",
# "item_type": "OPTIONAL_CONFIG",
# "currency_code": "OPTIONAL_CONFIG",
# "price_variant_id": "OPTIONAL_CONFIG",
# "trial_period": "OPTIONAL_CONFIG",
# "trial_period_unit": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "period_unit": "OPTIONAL_CONFIG",
# "period": "OPTIONAL_CONFIG",
# "channel": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This API is used to retrieve a list of all the available orders.
{
"name": "list_orders",
"table_name": "order",
"endpoint": {
"data_selector": "list",
"path": "/orders",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "exclude_deleted_credit_notes": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "invoice_id": "OPTIONAL_CONFIG",
# "subscription_id": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "shipping_date": "OPTIONAL_CONFIG",
# "shipped_at": "OPTIONAL_CONFIG",
# "order_type": "OPTIONAL_CONFIG",
# "order_date": "OPTIONAL_CONFIG",
# "paid_on": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "resent_status": "OPTIONAL_CONFIG",
# "is_resent": "OPTIONAL_CONFIG",
# "original_order_id": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"list.[*].order.total",
},
}
},
# Retrieves an order corresponding to the order id passed.
{
"name": "retrieve_an_order",
"table_name": "order",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "order",
"path": "/orders/{order-id}",
"params": {
"order-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves the payments for an invoice with the recent ones on top. This returns all the payment attempts(manual \& automatic) made for this invoice.
{
"name": "list_payments_for_an_invoice",
"table_name": "payment",
"endpoint": {
"data_selector": "list",
"path": "/invoices/{invoice-id}/payments",
"params": {
"invoice-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves the PaymentIntent resource.
{
"name": "retrieve_a_payment_intent",
"table_name": "payment_intent",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "payment_intent",
"path": "/payment_intents/{payment-intent-id}",
"params": {
"payment-intent-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API endpoint allows users to retrieve the payment reference numbers (PRNs) associated with an invoice. Only one PRN is allowed per payment type. You can use the `invoice_id` or the `payment_reference_number[number]` to retrieve the PRN.
{
"name": "list_payment_reference_numbers",
"table_name": "payment_reference_number",
"endpoint": {
"data_selector": "list",
"path": "/invoices/payment_reference_numbers",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "payment_reference_number": "OPTIONAL_CONFIG",
},
}
},
# Lists all the payment sources
{
"name": "list_payment_sources",
"table_name": "payment_source",
"endpoint": {
"data_selector": "list",
"path": "/payment_sources",
"params": {
# the parameters below can optionally be configured
# "subscription_id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves the payment source identified by the unique identifier.
{
"name": "retrieve_a_payment_source",
"table_name": "payment_source",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "payment_source",
"path": "/payment_sources/{cust-payment-source-id}",
"params": {
"cust-payment-source-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves vouchers for a customer in reverse chronological order.
{
"name": "list_vouchers_for_a_customer",
"table_name": "payment_voucher",
"endpoint": {
"data_selector": "list",
"path": "/customers/{customer-id}/payment_vouchers",
"params": {
"customer-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "status": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves vouchers for an invoice in reverse chronological order.
{
"name": "list_vouchers_for_an_invoice",
"table_name": "payment_voucher",
"endpoint": {
"data_selector": "list",
"path": "/invoices/{invoice-id}/payment_vouchers",
"params": {
"invoice-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "status": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a voucher using the unique `payment_voucher_id`.
{
"name": "retrieve_voucher_data",
"table_name": "payment_voucher",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "payment_voucher",
"path": "/payment_vouchers/{payment-voucher-id}",
"params": {
"payment-voucher-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
{
"name": "list_pc2_migration_items",
"table_name": "pc2_migration_item",
"endpoint": {
"data_selector": "list",
"path": "/pc2_migration_items",
"params": {
"pc2_migration_item_family": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
{
"name": "list_pc2_migration_item_families",
"table_name": "pc2_migration_item_family",
"endpoint": {
"data_selector": "list",
"path": "/pc2_migration_item_families",
"params": {
"pc2_migration_id": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
{
"name": "list_pc2_migration_item_prices",
"table_name": "pc2_migration_item_price",
"endpoint": {
"data_selector": "list",
"path": "/pc2_migration_item_prices",
"params": {
"pc2_migration_item_id": "FILL_ME_IN", # TODO: fill in required query parameter
# the parameters below can optionally be configured
# "pc2_migration_id": "OPTIONAL_CONFIG",
},
}
},
{
"name": "retrieve_a_pc2_migration",
"table_name": "pc_2_migration",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "pc2_migration",
"path": "/pc2_migrations/{pc2-migration-id}",
"params": {
"pc2-migration-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
{
"name": "retrieve_a_pc2_migration_item",
"table_name": "pc_2_migration_item",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "pc2_migration_item",
"path": "/pc2_migration_items/{pc2-migration-item-id}",
"params": {
"pc2-migration-item-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
{
"name": "retrieve_a_pc2_migration_item_family",
"table_name": "pc_2_migration_item_family",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "pc2_migration_item_family",
"path": "/pc2_migration_item_families/{pc2-migration-item-family-id}",
"params": {
"pc2-migration-item-family-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
{
"name": "retrieve_a_pc2_migration_item_price",
"table_name": "pc_2_migration_item_price",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "pc2_migration_item_price",
"path": "/pc2_migration_item_prices/{pc2-migration-item-price-id}",
"params": {
"pc2-migration-item-price-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API retrieves a portal session using `portal_session_id` as a path parameter.
{
"name": "retrieve_a_portal_session",
"table_name": "portal_session",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "portal_session",
"path": "/portal_sessions/{portal-session-id}",
"params": {
"portal-session-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This endpoint is used to retrieve a list of price variants.
{
"name": "list_price_variants",
"table_name": "price_variant",
"endpoint": {
"data_selector": "list",
"path": "/price_variants",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This endpoint retrieves the details of a specific price variant using its unique identifier.
{
"name": "retrieve_a_price_variant",
"table_name": "price_variant",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "price_variant",
"path": "/price_variants/{price-variant-id}",
"params": {
"price-variant-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieve a product using `product_id`.
{
"name": "retrieve_a_product",
"table_name": "product",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "product",
"path": "/products/{product-id}",
"params": {
"product-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This API retrieves the list of products that are `active` or `inactive`. Use `include_deleted` parameter to include deleted products with `active` and `inactive` products.
{
"name": "list_products",
"table_name": "product",
"endpoint": {
"data_selector": "list",
"path": "/products",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "shippable": "OPTIONAL_CONFIG",
# "has_variant": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This endpoint retrieves the promotional credit based on the promotional credit id
{
"name": "retrieve_a_promotional_credit",
"table_name": "promotional_credit",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "promotional_credit",
"path": "/promotional_credits/{account-credit-id}",
"params": {
"account-credit-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This endpoint lists the promotional credits set for a customer
{
"name": "list_promotional_credits",
"table_name": "promotional_credit",
"endpoint": {
"data_selector": "list",
"path": "/promotional_credits",
"params": {
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
},
}
},
# Retrieves the quotes identified by the 'number' specified in the url.
{
"name": "retrieve_a_quote",
"table_name": "quote",
"endpoint": {
"data_selector": "$",
"path": "/quotes/{quote-id}",
"params": {
"quote-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# List all quotes.
{
"name": "list_quotes",
"table_name": "quote",
"endpoint": {
"data_selector": "list",
"path": "/quotes",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
# "subscription_id": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "date": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"list.[*].quote.total",
},
}
},
# This API retrieves all the quote line groups and lineitems for a quote.
{
"name": "list_quote_line_groups",
"table_name": "quote_line_group",
"endpoint": {
"data_selector": "list",
"path": "/quotes/{quote-id}/quote_line_groups",
"params": {
"quote-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
"paginator": {
"type":
"offset",
"limit":
100,
"offset_param":
"offset",
"limit_param":
"limit",
"total_path":
"list.[*].quote_line_group.total",
},
}
},
# Lists the subscription ramps that match the criteria provided in the filter parameters. **Note** By default, the ramps are returned [sorted](ramps#list_ramps_sort_by) in descending order (latest first) by [updated_at](ramps#ramp_updated_at).
{
"name": "list_ramps",
"table_name": "ramp",
"endpoint": {
"data_selector": "list",
"path": "/ramps",
"params": {
"subscription_id": "FILL_ME_IN", # TODO: fill in required query parameter
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "effective_from": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a specific subscription ramp.
{
"name": "retrieve_a_ramp",
"table_name": "ramp",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "ramp",
"path": "/ramps/{subscription-schedule-id}",
"params": {
"subscription-schedule-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# This returns an estimate of the amount that will be charged when the subscription is billed next. The estimate is calculated based on the current recurring items of the subscription - plan, addons, and coupons. In the response, * **estimate.subscription_estimate** has the current subscription details like its status, next billing date, and so on. * **estimate.invoice_estimate** has details of the invoice that will be generated at the next billing date. The generated invoice estimate will include all the balances - [Promotional Credits](https://www.chargebee.com/docs/promotional-credits.html), Refundable Credits, and Excess Payments - if any. If you don't want these balances to be included you can specify 'false' for the parameter *use_existing_balances*. To exclude the [delayed charges](https://www.chargebee.com/docs/charges.html) from the invoice estimate, specify 'false' for the parameter *include_delayed_charges*. **Note:** * This API will not generate a renewal invoice if an [advance invoice](https://www.chargebee.com/docs/advance-invoices.html) is already present for the subscription. * For 'Non Renewing' subscriptions, only the [delayed charges](https://www.chargebee.com/docs/charges.html) will be included in the invoice estimate. * This API is not supported for 'Cancelled' subscriptions. * Only the subscription's charges will be included. If you have enabled the Consolidated invoicing feature, use the *Upcoming Invoices* estimate available for the Customer object to get the actual estimate invoice for the customer.
{
"name": "subscription_renewal_estimate",
"table_name": "renewal_estimate",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "estimate.subscription_estimates",
"path": "/subscriptions/{subscription-id}/renewal_estimate",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "include_delayed_charges": "True",
# "use_existing_balances": "True",
# "ignore_scheduled_cancellation": "OPTIONAL_CONFIG",
# "ignore_scheduled_changes": "OPTIONAL_CONFIG",
},
}
},
# Gets the last migration details.
{
"name": "retrieve_latest_migration_details",
"table_name": "resource_migration",
"endpoint": {
"data_selector": "resource_migration",
"path": "/resource_migrations/retrieve_latest",
"params": {
"from_site": "FILL_ME_IN", # TODO: fill in required query parameter
"entity_type": "FILL_ME_IN", # TODO: fill in required query parameter
"entity_id": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# **Caution** This API cannot be used for subscriptions that have [ramp](ramps?prod_cat_ver=2)s. Retrieves a subscription with the scheduled changes applied. **Note:** Only the following attributes are changed * item_id * item_price_id * billing_period * billing_period_unit * remaining_billing_cycles * coupons Other attributes such as **status** ,**next_billing_at** are not changed and will reflect the current subscription values.
{
"name": "retrieve_with_scheduled_changes",
"table_name": "retrieve_with_scheduled_change",
"endpoint": {
"data_selector": "subscription.subscription_items",
"path": "/subscriptions/{subscription-id}/retrieve_with_scheduled_changes",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves Revenue story resources
{
"name": "list_rs_data_export_resources",
"table_name": "rs_data_export_resource",
"endpoint": {
"data_selector": "list",
"path": "/rs_data_export_resources",
"params": {
# the parameters below can optionally be configured
# "resource": "OPTIONAL_CONFIG",
},
}
},
# This endpoint lists the site migration details.
{
"name": "list_site_migration_details",
"table_name": "site_migration_detail",
"endpoint": {
"data_selector": "list",
"path": "/site_migration_details",
"params": {
# the parameters below can optionally be configured
# "entity_id_at_other_site": "OPTIONAL_CONFIG",
# "other_site_name": "OPTIONAL_CONFIG",
# "entity_id": "OPTIONAL_CONFIG",
# "entity_type": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
},
}
},
# Returns a list of subscriptions meeting **all** the conditions specified in the filter parameters below.
{
"name": "list_subscriptions",
"table_name": "subscription",
"endpoint": {
"data_selector": "list",
"path": "/subscriptions",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
# "item_id": "OPTIONAL_CONFIG",
# "item_price_id": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "cancel_reason": "OPTIONAL_CONFIG",
# "cancel_reason_code": "OPTIONAL_CONFIG",
# "remaining_billing_cycles": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "activated_at": "OPTIONAL_CONFIG",
# "next_billing_at": "OPTIONAL_CONFIG",
# "cancelled_at": "OPTIONAL_CONFIG",
# "has_scheduled_changes": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "offline_payment_method": "OPTIONAL_CONFIG",
# "auto_close_invoices": "OPTIONAL_CONFIG",
# "override_relationship": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
# "business_entity_id": "OPTIONAL_CONFIG",
# "channel": "OPTIONAL_CONFIG",
},
}
},
# Retrieves a subscription.
{
"name": "retrieve_a_subscription",
"table_name": "subscription",
"endpoint": {
"data_selector": "$",
"path": "/subscriptions/{subscription-id}",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves the list of `subscription_entitlements` for the [subscription](/docs/api/subscriptions). **Note:** The `components` attribute is not returned for any of the `subscription_entitlements`. Use the retrieve operation(coming soon) to obtain the `components`.
{
"name": "list_subscription_entitlements",
"table_name": "subscription_entitlement",
"endpoint": {
"data_selector": "list",
"path": "/subscriptions/{subscription-id}/subscription_entitlements",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
{
"name": "scheduled_changes_a_subscription_scheduled_change",
"table_name": "subscription_scheduled_change",
"endpoint": {
"data_selector": "subscription_scheduled_change",
"path": "/subscriptions/{subscription-id}/scheduled_changes",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves the time machine. Currently only one time machine is available per site and is named 'delorean'.
{
"name": "retrieve_a_time_machine",
"table_name": "time_machine",
"endpoint": {
"data_selector": "time_machine",
"path": "/time_machines/{time-machine-name}",
"params": {
"time-machine-name": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieve a token using token ID.
{
"name": "retrieve_a_token",
"table_name": "token",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "token",
"path": "/tokens/{cb-token-id}",
"params": {
"cb-token-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Lists all the transactions.
{
"name": "list_transactions",
"table_name": "transaction",
"endpoint": {
"data_selector": "list",
"path": "/transactions",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
# "subscription_id": "OPTIONAL_CONFIG",
# "payment_source_id": "OPTIONAL_CONFIG",
# "payment_method": "OPTIONAL_CONFIG",
# "gateway": "OPTIONAL_CONFIG",
# "gateway_account_id": "OPTIONAL_CONFIG",
# "id_at_gateway": "OPTIONAL_CONFIG",
# "reference_number": "OPTIONAL_CONFIG",
# "type": "OPTIONAL_CONFIG",
# "date": "OPTIONAL_CONFIG",
# "amount": "OPTIONAL_CONFIG",
# "amount_capturable": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# Retrieve a transaction identified by its unique id.
{
"name": "retrieve_a_transaction",
"table_name": "transaction",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "transaction",
"path": "/transactions/{transaction-id}",
"params": {
"transaction-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Returns a list of [business_entity_transfer](business_entity_transfers?prod_cat_ver=2) resources meeting all the conditions specified in the filter parameters below. By default, this list is sorted by `created_at` in descending order (latest first). **Tip** To retrieve a history of all the business entity transfers for a resource, pass the filter parameters [active_resource_id[is]](business_entities?prod_cat_ver=2#list_the_business_entity_transfers_active_resource_id) and [resource_type[]](business_entities?prod_cat_ver=2#list_the_business_entity_transfers_resource_type).
{
"name": "list_the_business_entity_transfers",
"table_name": "transfer",
"endpoint": {
"data_selector": "list",
"path": "/business_entities/transfers",
"params": {
# the parameters below can optionally be configured
# "resource_type": "OPTIONAL_CONFIG",
# "resource_id": "OPTIONAL_CONFIG",
# "active_resource_id": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This endpoint lists all the unbilled charges.
{
"name": "list_unbilled_charges",
"table_name": "unbilled_charge",
"endpoint": {
"data_selector": "list",
"path": "/unbilled_charges",
"params": {
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "is_voided": "OPTIONAL_CONFIG",
# "subscription_id": "OPTIONAL_CONFIG",
# "customer_id": "OPTIONAL_CONFIG",
},
}
},
# Estimate of the upcoming scheduled invoices (subscription activations, renewals etc) of a customer. For now preview of the invoices generated on the immediate upcoming date is supported. Say a customer has couple of subscription renewals scheduled on *Jan,10th* and another subscription renewal scheduled on *Jan,15th* . This API gives the preview of all the invoices scheduled to be generated on *Jan,10th* (immediate upcoming date). In the response: * **estimate.invoice_estimates\[\]** has details of the invoices scheduled to be generated. **Note:** If *consolidated invoicing* is enabled you may use this API to test whether upcoming renewals are consolidated.
{
"name": "upcoming_invoices_estimate",
"table_name": "upcoming_invoices_estimate",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "estimate.subscription_estimates",
"path": "/customers/{customer-id}/upcoming_invoices_estimate",
"params": {
"customer-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Retrieves a usage record of a specific subscription.
{
"name": "retrieve_a_usage",
"table_name": "usage",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "usage",
"path": "/subscriptions/{subscription-id}/usages",
"params": {
"subscription-id": "FILL_ME_IN", # TODO: fill in required path parameter
"id": "FILL_ME_IN", # TODO: fill in required query parameter
},
}
},
# Retrieves the list of usages.
{
"name": "list_usages",
"table_name": "usage",
"endpoint": {
"data_selector": "list",
"path": "/usages",
"params": {
"subscription_id": "FILL_ME_IN", # TODO: fill in required query parameter
# the parameters below can optionally be configured
# "id": "OPTIONAL_CONFIG",
# "usage_date": "OPTIONAL_CONFIG",
# "item_price_id": "OPTIONAL_CONFIG",
# "invoice_id": "OPTIONAL_CONFIG",
# "source": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This API retrieves the list of product variants.
{
"name": "list_product_variants",
"table_name": "variant",
"endpoint": {
"data_selector": "list",
"path": "/products/{product-id}/variants",
"params": {
"product-id": "FILL_ME_IN", # TODO: fill in required path parameter
# the parameters below can optionally be configured
# "include_deleted": "OPTIONAL_CONFIG",
# "id": "OPTIONAL_CONFIG",
# "name": "OPTIONAL_CONFIG",
# "sku": "OPTIONAL_CONFIG",
# "status": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
# "sort_by": "OPTIONAL_CONFIG",
},
}
},
# This API is used to retrieve a product variant using `variant_id`.
{
"name": "retrieve_a_product_variant",
"table_name": "variant",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "variant",
"path": "/variants/{product-variant-id}",
"params": {
"product-variant-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
# Lists all the virtual bank accounts.
{
"name": "list_virtual_bank_accounts",
"table_name": "virtual_bank_account",
"endpoint": {
"data_selector": "list",
"path": "/virtual_bank_accounts",
"params": {
# the parameters below can optionally be configured
# "customer_id": "OPTIONAL_CONFIG",
# "updated_at": "OPTIONAL_CONFIG",
# "created_at": "OPTIONAL_CONFIG",
},
}
},
# Retrieves the virtual bank account identified by the unique identifier.
{
"name": "retrieve_a_virtual_bank_account",
"table_name": "virtual_bank_account",
"primary_key": "id",
"write_disposition": "merge",
"endpoint": {
"data_selector": "virtual_bank_account",
"path": "/virtual_bank_accounts/{virtual-bank-account-id}",
"params": {
"virtual-bank-account-id": "FILL_ME_IN", # TODO: fill in required path parameter
},
}
},
]
}
return rest_api_source(source_config)
2. Configuring your source and destination credentials
info
dlt-init-openapi will try to detect which authentication mechanism (if any) is used by the API in question and add a placeholder in your secrets.toml.
The dlt cli will have created a .dlt directory in your project folder. This directory contains a config.toml file and a secrets.toml file that you can use to configure your pipeline. The automatically created version of these files look like this:
generated config.toml
[runtime]
log_level="INFO"
[sources.chargebee]
# Base URL for the API
# Live Site
base_url = "{protocol}://{site}.{environment}:{port}/api/v2"
# Alternative servers found in openapi spec:
# Test Site
# base_url = "{protocol}://{site}-test.{environment}:{port}/api/v2"
generated secrets.toml
[sources.chargebee]
# secrets for your chargebee source
username = "FILL ME OUT" # TODO: fill in your credentials
password = "FILL ME OUT" # TODO: fill in your credentials
2.1. Adjust the generated code to your usecase
Further help setting up your source and destinations
At this time, the dlt-init-openapi cli tool will always create pipelines that load to a local duckdb instance. Switching to a different destination is trivial, all you need to do is change the destination parameter in chargebee_pipeline.py to postgres and supply the credentials as outlined in the destination doc linked below.
3. Running your pipeline for the first time
The dlt cli has also created a main pipeline script for you at chargebee_pipeline.py, as well as a folder chargebee that contains additional python files for your source. These files are your local copies which you can modify to fit your needs. In some cases you may find that you only need to do small changes to your pipelines or add some configurations, in other cases these files can serve as a working starting point for your code, but will need to be adjusted to do what you need them to do.
The main pipeline script will look something like this:
import dlt
from chargebee import chargebee_source
if __name__ == "__main__":
pipeline = dlt.pipeline(
pipeline_name="chargebee_pipeline",
destination='duckdb',
dataset_name="chargebee_data",
progress="log",
export_schema_path="schemas/export"
)
source = chargebee_source()
info = pipeline.run(source)
print(info)
Provided you have set up your credentials, you can run your pipeline like a regular python script with the following command:
python chargebee_pipeline.py
4. Inspecting your load result
You can now inspect the state of your pipeline with the dlt cli:
dlt pipeline chargebee_pipeline info
You can also use streamlit to inspect the contents of your Azure Cosmos DB destination for this:
# install streamlit
pip install streamlit
# run the streamlit app for your pipeline with the dlt cli:
dlt pipeline chargebee_pipeline show
5. Next steps to get your pipeline running in production
One of the beauties of dlt is, that we are just a plain Python library, so you can run your pipeline in any environment that supports Python >= 3.8. We have a couple of helpers and guides in our docs to get you there:
The Deploy section will show you how to deploy your pipeline to
- Deploy with GitHub Actions: Use GitHub Actions to automate your pipeline deployment. Learn more here.
- Deploy with Airflow: Integrate your pipeline with Airflow and Google Composer for a managed workflow. Detailed instructions are available here.
- Deploy with Google Cloud Functions: Utilize Google Cloud Functions for serverless pipeline deployment. Follow the guide here.
- Explore other deployment options: Discover various other methods to deploy your pipeline here.
The running in production section will teach you about:
- How to Monitor your pipeline: Learn how to effectively monitor your
dltpipelines in production to ensure they run smoothly and efficiently. How to Monitor your pipeline - Set up alerts: Configure alerts to stay informed about the status and health of your
dltpipelines in real-time. Set up alerts - Set up tracing: Implement tracing to gain detailed insights into the execution of your
dltpipelines, helping you troubleshoot and optimize performance. And set up tracing
Available Sources and Resources
For this verified source the following sources and resources are available
Source Chargebee
Chargebee source for subscription billing and revenue management data.
| Resource Name | Write Disposition | Description |
|---|---|---|
card | append | Stores information about customer payment cards. |
custom_field_config | append | Configuration for custom fields in Chargebee. |
contact | append | Details of contacts associated with customers. |
customer | append | Information about customers in Chargebee. |
entitlement_override | append | Overrides for customer entitlements. |
pc_2_migration_item | append | Items involved in a Phase 2 migration. |
discount | append | Information about discounts applied to subscriptions. |
quote | append | Details of quotes provided to customers. |
order | append | Information about orders placed by customers. |
price_variant | append | Variants of pricing plans. |
variant | append | Variants of products or services. |
contract_term | append | Terms of contracts with customers. |
pc2_migration_item_family | append | Families of items involved in a Phase 2 migration. |
pc_2_migration | append | Details of Phase 2 migrations. |
coupon_set | append | Sets of coupons available for promotions. |
currency | append | Supported currencies in Chargebee. |
site_migration_detail | append | Details of site migrations. |
quote_line_group | append | Groups of line items in a quote. |
differential_price | append | Differential pricing details. |
full_export | append | Full export of data from Chargebee. |
advance_invoice_schedule | append | Schedules for advance invoicing. |
installment | append | Details of installment payments. |
coupon | append | Information about coupons available for discounts. |
applicable_item | append | Items to which certain rules or conditions apply. |
renewal_estimate | append | Estimates for subscription renewals. |
feature | append | Features available in Chargebee. |
pc_2_migration_item_price | append | Prices of items involved in a Phase 2 migration. |
promotional_credit | append | Credits given to customers for promotions. |
attached_item | append | Items attached to subscriptions or orders. |
installment_config | append | Configuration for installment payments. |
item | append | Items available in Chargebee. |
item_entitlement | append | Entitlements associated with items. |
entitlement | append | Customer entitlements in Chargebee. |
item_price | append | Prices of items in Chargebee. |
gift | append | Details of gifts given to customers. |
portal_session | append | Sessions for customer portal access. |
address | append | Addresses of customers. |
payment_source | append | Sources of payments made by customers. |
subscription_scheduled_change | append | Scheduled changes to subscriptions. |
item_family | append | Families of items available in Chargebee. |
token | append | Tokens used for secure transactions. |
payment | append | Details of payments made by customers. |
upcoming_invoices_estimate | append | Estimates for upcoming invoices. |
subscription_entitlement | append | Entitlements associated with subscriptions. |
event | append | Events occurring within Chargebee. |
payment_reference_number | append | Reference numbers for payments. |
resource_migration | append | Migrations of resources within Chargebee. |
payment_voucher | append | Vouchers used for payments. |
ramp | append | Details of ramp plans for subscriptions. |
subscription | append | Information about subscriptions in Chargebee. |
time_machine | append | Historical data and snapshots. |
comment | append | Comments and notes added to records. |
credit_note | append | Credit notes issued to customers. |
virtual_bank_account | append | Virtual bank accounts used for transactions. |
invoice | append | Invoices issued to customers. |
retrieve_with_scheduled_change | append | Retrieve data with scheduled changes. |
hosted_page | append | Hosted pages for customer interactions. |
usage | append | Usage data for metered billing. |
unbilled_charge | append | Charges that have not yet been billed. |
product | append | Products available in Chargebee. |
export | append | Export of data from Chargebee. |
transfer | append | Transfers of funds between accounts. |
coupon_code | append | Codes used for applying coupons. |
payment_intent | append | Intents for payments to be made. |
applicable_item_price | append | Prices of items to which certain rules apply. |
rs_data_export_resource | append | Resources for exporting data. |
download | append | Downloads of data or files. |
hierarchy | append | Hierarchical structure of resources. |
transaction | append | Transactions made by customers. |
Additional pipeline guides
- Load data from Slack to DuckDB in python with dlt
- Load data from MySQL to DuckDB in python with dlt
- Load data from Google Cloud Storage to Neon Serverless Postgres in python with dlt
- Load data from Shopify to Databricks in python with dlt
- Load data from Adobe Commerce (Magento) to Databricks in python with dlt
- Load data from IFTTT to Azure Synapse in python with dlt
- Load data from Klaviyo to Microsoft SQL Server in python with dlt
- Load data from Soundcloud to AWS Athena in python with dlt
- Load data from Mux to MotherDuck in python with dlt
- Load data from ClickHouse Cloud to Snowflake in python with dlt