# Fetch the health status of the Service Provider. Source: https://spidocs.chargebee.com/api-reference/common/fetch-the-health-status-of-the-service-provider get /health This endpoint is used to fetch the health status of the Service Provider. # Validate credentials Source: https://spidocs.chargebee.com/api-reference/common/validate-credentials post /credentials/validate This endpoint is used to validate the credentials used to call the Service Provider. # Adapter to Chargebee(OAuth 2.0) Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/docs/authorization/adapter_to_chargebee ## Overview Partner adapter apps must be authorized by Chargebee using the OAuth 2.0 Authorization. This allows your app to securely call Chargebee APIs (such as webhook callbacks) on behalf of a merchant after consent is given. This guide explains how Chargebee initiates the flow, how your adapter should implement Oauth flows, and best practices for secure implementation. *** ## OAuth 2.0 Flow Overview The OAuth 2.0 authorization flow consists of these main steps: * User Authorization: Redirect users to Chargebee's authorization server * User Consent: Users review and grant permission to your application * Authorization Code: Chargebee returns a temporary authorization code * Token Exchange: Exchange the code for access and refresh tokens * API Access: Use the access token to make authenticated API calls * Token Refresh: Use refresh tokens to obtain new access tokens when needed OAuth 2.0 flow ### Prerequisites Before implementing OAuth 2.0, ensure you have: * A Chargebee partner sandbox account. * Client ID and Client Secret from Chargebee. * Understanding of your application's required scopes. * HTTPS-enabled application (required for production). *** ### Supported Grant Types Chargebee OAuth 2.0 currently supports the following grant types: * **Authorization Code Flow**\ Recommended for web-based applications and server-side implementations that require secure, user-authorized access. * **Refresh Token Flow**\ Used to obtain a new access token without requiring user reauthorization, after the original access token expires. ### Step 1: App Registration by Chargebee * Once you have submitted your app following the [onboarding process](../../../app-onboarding/guide), Our team will review your application and the client credentials will be shared with you securely. > **Note:** The credential provisioning process typically takes **2–3 business days**. Please ensure your application details are accurate to help us process your request faster. *** ### Step 2: Merchant Authorization via Chargebee UI When a Chargebee merchant connects your app: * Chargebee displays a **consent screen** to the merchant. * After approval, Chargebee redirects the user to your registered `redirect_uri` with: * An `authorization_code` * An optional `state` parameter for CSRF protection ```http theme={null} GET https://your-app.com/oauth/callback? code=AUTH_CODE_REDACTED state=STATE_REDACTED ``` *** ### Step 3: Exchange Authorization Code for Tokens Once your adapter app receives the `code` parameter from Chargebee via the redirect URI, you must exchange it for an `access_token` and `refresh_token` using the token endpoint. #### Token Request (cURL) ```bash theme={null} curl -X POST 'https://app.chargebee.com/oauth/token' \ -u "${CLIENT_ID}:${CLIENT_SECRET}" \ -d 'grant_type=authorization_code' \ -d 'code=AUTH_CODE_REDACTED' \ -d 'redirect_uri=https://your-app.com/oauth/callback' ``` #### Sample response ```json theme={null} { "access_token": "ACCESS_TOKEN_REDACTED", "refresh_token": "REFRESH_TOKEN_REDACTED", "token_type": "Bearer", "expires_in": 3600, "scope": "einvoicing.write" } ``` *** ### Step 4: Make Authorized API Calls to Chargebee Once the access token is available, your adapter app can call Chargebee APIs (such as posting document status updates). #### Example API Call (cURL) ```bash theme={null} curl -X POST 'https://{chargebee-domain}.chargebee.com/webhooks/einvoicing/{partner-id}/document_status' \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ -d '{ "document_id": "INV-1001", "status": "ACCEPTED" }' ``` Chargebee will validate the token and the partner-id for authorization before accepting the request. **Note**: The domain identifier is contained within the access token claims. You'll need to decode the JWT access token to extract the domain information for constructing the API URL: https\://.chargebee.com/api/v2/. #### Access Token Claims The access token issued by Chargebee is a **JWT (JSON Web Token)**. It contains encoded claims that provide metadata about the authorization context. To extract the Chargebee domain, which is required to construct the correct API URL: 1. Decode the JWT payload (the **second** part of the JWT: `header.payload.signature`) 2. Extract the `domain` claim from the decoded payload 3. Use the value of `domain` to construct the API base URL #### Example JWT Payload ```json theme={null} { "iss": "https://app.chargebee.com", "sub": "user_id", "aud": "https://app.chargebee.com", "exp": 1640995200, "iat": 1640991600, "scope": "einvoicing.write", "domain": "your-site-name" } ``` *** ### Step 5: Refresh Access Tokens Access tokens are short-lived. When expired, use the refresh\_token to obtain a new access token without requiring the merchant to authorize again. ### Refresh Token Request ```curl theme={null} curl -X POST 'https://app.chargebee.com/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u "${CLIENT_ID}:${CLIENT_SECRET}" \ -d 'grant_type=refresh_token' \ -d 'refresh_token=REFRESH_TOKEN_REDACTED' ``` *** ### Security Best Practices * Always use HTTPS for all OAuth communications in production environments. * Store client secrets securely using environment variables or secure key management systems. * Implement proper token validation and verification on every request. * Never expose access tokens in client-side code or public repositories. * Implement proper error handling for token-related operations. * Regularly rotate client secrets as part of your security practices. # Chargebee to Adapter (Header-Based Auth) Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/docs/authorization/chargebee_to_adapter This applies when **Chargebee initiates calls to the adapter**, such as when submitting a document or requesting document status. Your adapter must be able to **receive and validate HTTP requests authenticated via headers**. Chargebee uses [**HTTP header-based authorization**](https://datatracker.ietf.org/doc/html/rfc7235) for all outbound SPI calls to partner adapter endpoints. This approach enables **secure, consistent, and dynamic management of credentials**. ### How It Works * The **Authorization Key** for API calls is dynamically passed in the HTTP header, enabling secure and seamless integration. * This key is defined in the [JSON Schema](https://github.com/chargebee/cb-partner-spi/blob/main/spec/capabilities/einvoicing-provider.schema.json), which must be completed and submitted by the partner during the app registration process in Chargebee’s Marketplace. * During the application onboarding process in Chargebee, merchants provide the necessary authorization parameter values. * The Chargebee application uses these values to authenticate and make API calls to the Service Adapter. ### Structure of `credential_configuration` * The `credential_configuration` is an array of objects, where each object represents a credential parameter. * Each object includes the following attributes: * **`id`**: A unique identifier for the credential. For example, `authorization_key` or `client_secret`. * **`name`**: A descriptive label of the credential. * **`type`**:The credential type. For example, `text`. * **`is_sensitive`**: Indicates whether the credential is sensitive. * **`multi_entity_support`**: (optional): Indicates whether the credential should be configured separately for each business entity in a multi-entity setup. When set to true, Chargebee will prompt the merchant to provide different values for this credential for each entity. Defaults to false if not specified. ### JSON Configuration Example ```json theme={null} { "api_configuration": { "api_base_url": "https://chargebee.partnerX.com/v1", "credential_configuration": [ { "id": "api_key", "name": "API Key", "type": "text", "is_sensitive": true }, { "id": "company_code", "name": "Company code", "type": "text", "is_sensitive": false, "multi_entity_support": true } ] } } ``` ### Authorization Header When the Chargebee app initiates a request to the Service Adapter, it includes the authentication credentials within the Authorization header as a JSON string. Additionally, Chargebee injects below headers. like `merchant_id` and `trace_id` by default for tracking and tenant identification purposes. * `merchant_id` - This is the domain name of merchant chargebee site. * `trace_id` - This id is sent by Chargebee by default. It can be used for tracing logs. Below is an example of how the headers appear in a request: ```bash theme={null} curl --request POST https://chargebee.partnerX.com/v1/endpoint \ --header 'Authorization: {"api_key":"service_provider_api_key"}' \ --header "merchant_id: acme-gb" // This is sent by Chargebee by default \ --header "trace_id: test_trace_id" // This is sent by Chargebee by default. It can be used for tracing logs. ``` # Overview Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/docs/authorization/overview The e-invoicing SPI involves two directions of API communication, each with its own authentication model. As a partner developer, you'll need to understand and implement both flows depending on your adapter's role in the integration. # Overview Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/docs/overview # E-Invoicing SPI Integration Chargebee streamlines e-invoicing compliance across regions by supporting the following operations throughout the billing lifecycle: ### 1) Retrieve E-invoicing Activations * Retrieves the list of country and network activations configured in the connected e-invoicing provider platform. * Each activation corresponds to a specific country and e-invoicing network offered by the provider. * Chargebee uses this operation during provider enablement to determine which activations can be offered to merchants. Activation_workflow ### 2) Document Submission * Submits invoices and credit notes to external e-invoicing systems for validation, compliance processing, and delivery to tax authorities or trading partners. Document_submission_workflow ### 3) Status Tracking * Supports asynchronous document lifecycle tracking through webhook notifications sent by the e-invoicing adapter. These updates reflect real-time status changes as documents move through validation, compliance, and regulatory delivery stages. webhook_workflow * Allows on-demand status checks to retrieve the latest processing state of submitted documents, ensuring continued visibility even if webhook delivery is delayed or disrupted. poll_document_workflow ### 4) Final Document Retrieval * Retrieves finalized, regulator-approved documents for archiving, auditing, or customer use. download_document_workflow Chargebee leverages external e-invoicing services to execute these operations effectively. These services are certified vendors offering APIs to manage e-invoicing compliance and document exchange with tax authorities. *** ## The Role of the E-invoicing Adapter App To communicate with external e-invoicing systems, Chargebee uses an **E-invoicing Adapter App** — a secure and standardized bridge between Chargebee and the e-invoicing system. This integration is governed by the **E-invoicing Service Provider Interface (SPI)**. *** ## Building an E-invoicing Adapter App To integrate your e-invoicing system with Chargebee, you must implement the E-invoicing SPI.(You can refer to the spec file for this SPI [here](https://github.com/chargebee/cb-partner-spi/blob/main/spec/spi/openapi_einvoicing.yml)). You’ll need to build an adapter app in the following cases: ### As an E-invoicing Provider Connect your compliance platform to Chargebee so that merchants can automatically submit billing documents in a regulator-approved format. ### As a System Integrator Build a connector that bridges a third-party e-invoicing provider with Chargebee, enabling seamless integration for merchants. By implementing the E-invoicing SPI, you enable Chargebee to support **global regulatory compliance** through a **scalable and region-agnostic architecture**. ## JSON Schema for Einvoicing Provider Below is the Chargebee E-invoicing [JSON Schema](https://json-schema.org/docs). Use this schema to ensure that your E-invoicing data is structured [View Full E-invoicing provider JSON Schema](https://github.com/chargebee/cb-partner-spi/blob/main/spec/capabilities/einvoicing-provider.schema.json) # Testing with Postman Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/docs/testing-with-postman Postman is an API development environment that simplifies running and testing API requests. With Postman, you won’t have to copy and paste data from one endpoint to another. [![Run In Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/chargebee/chargebee-partners/collection/29468245-27ed94be-c582-497b-b39a-7dc73821840a?action=share\&source=copy-link\&creator=29468245) 1. **Download and Install Postman** * Download Postman from the [Postman Downloads page](https://www.postman.com/downloads/). * Install the application on your system by following the setup instructions. 2. **Access E-invoicing SPI** * Visit the [E-invoicing SPI collection](https://www.postman.com/chargebee/chargebee-partners/collection/29468245-27ed94be-c582-497b-b39a-7dc73821840a?action=share\&source=copy-link\&creator=29468245). 3. **Fork Collection and select the Environment** * Fork the Collection and choose the "E-invoicing SPI" environment from the Postman workspace. 4. **Configure Environment Variables** * Add the following environment variables: * `url` - The base URL of the app. * `authorization_header` - The value for the authorization header required for API authentication. Refer to the [Authorization section](../docs/authorization/overview) to know more about this. Now, you're ready to interact with E-invoicing SPI endpoints using Postman. # Retrieve a list of Activations. Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/activations/retrieve-a-list-of-activations get /einvoicing/activations Retrieves either: - A list of country-level e-invoicing activations configured at the connected e-invoicing provider, or - A list of business entities configured at the provider, depending on the query parameters used. Each activation represents the provider's capability to support e-invoicing in a specific country and model for a given business entity. **Business Entity Concept** In Chargebee, a *business entity* represents a business unit or brand under the merchant's organization. Refer [here](https://apidocs.chargebee.com/docs/api/business_entities) for more details. In this SPI, a business entity corresponds to the closest equivalent in the provider's system (for example, a company, or tenant). **Modes of Operation** - When called **without parameters**, returns all activations across business entities (if supported by the provider). - When called with `business_entity_id`, returns activations for that specific business entity. - When called with `mode=business_entities`, returns a list of business entities that are active or configured in the provider. This endpoint enables Chargebee to: - Identify e-invoicing capabilities available for activation. - Fetch business entity lists for provider configuration workflows. - Retrieve activation details filtered by a specific business entity during country-level setup. **Example use cases** - During integration setup: `GET /einvoicing/activations?mode=business_entities` - During country configuration: `GET /einvoicing/activations?business_entity_id=` # Retrieves data input fields Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/activations/retrieves-data-input-fields get /einvoicing/data_input_fields This optional SPI endpoint is used to retrieve the required and optional data input fields for various e-invoicing scenarios supported by the provider. Each scenario is defined by a unique combination of country, e-invoicing network, and transaction type (B2B, B2C, or B2G). Implementation of this endpoint is recommended only if the e-invoicing provider requires merchant to configure field mappings themselves, rather than relying on predefined mappings managed by the provider or Chargebee. Within Chargebee, this endpoint is invoked during the e-invoicing setup workflow, when a user maps fields between the provider’s schema and Chargebee’s internal data model for a specific combination of country, network, and transaction type. Once this configuration is complete, the resulting field mappings are included in the document submission request and passed to the adapter via the field_mapping parameter, enabling the adapter to transform the SPI-compliant payload into the provider’s required format. # Receive document status updates for a credit note Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/callbacks/receive-document-status-updates-for-credit-note post /api/v2/credit_notes/{document_id}/einvoice_status The adapter receives a webhook from the provider, transforms the payload into Chargebee’s standardized schema, and forwards the final document status to this endpoint. Chargebee uses this callback to update internal document tracking states and trigger downstream workflows such as customer notifications or audit logs. This endpoint is **idempotent**, repeated submissions with the same `document_id` and `status` will not result in duplicate processing. Requires an OAuth 2.0 access token authorized via the merchant OAuth flow. The Chargebee merchant must authorize the e-invoicing app via the OAuth flow to allow it to make authenticated POST calls to this endpoint. # Receive document status updates for an invoice Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/callbacks/receive-document-status-updates-for-invoice post /api/v2/invoices/{document_id}/einvoice_status The adapter receives a webhook from the provider, transforms the payload into Chargebee’s standardized schema, and forwards the final document status to this endpoint. Chargebee uses this callback to update internal document tracking states and trigger downstream workflows such as customer notifications or audit logs. This endpoint is **idempotent**, repeated submissions with the same `document_id` and `status` will not result in duplicate processing. Requires an OAuth 2.0 access token authorized via the merchant OAuth flow. The Chargebee merchant must authorize the e-invoicing app via the OAuth flow to allow it to make authenticated POST calls to this endpoint. # Download Document Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/documents/download-document get /einvoicing/documents/{document_id}/download Retrieves the document content associated with the provided documentId from the connected e-invoicing provider. A document_id by itself is not always sufficient for the provider to determine which document formats or variants to return. Chargebee includes additional query parameters — such as country, transaction_type, and model — so the adapter can accurately identify and fetch the correct document representations. If the mime_type query parameter is not provided, the adapter MUST retrieve all available document representations for the specified document_id. When a specific mime_type is supplied, the adapter MUST return only the matching representation(s). The document may be returned either as a pre-signed URL or as a direct binary stream (such as a PDF or XML file), depending on the provider’s capabilities and the SPI implementation. In Chargebee, this endpoint is called after the document has been successfully processed either to send it via email to the end customer or when the merchant initiates a download from the Chargebee UI. Implementing this endpoint is MANDATORY to support document retrieval operations. # Get Document Status Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/documents/get-document-status get /einvoicing/documents/{document_id}/status Retrieves the current processing status of a document previously submitted to the connected e-invoicing provider. The status provides insights into whether the document has been successfully processed, is still under validation, has failed, or has been rejected by tax authorities or intermediaries. In Chargebee, this endpoint is periodically called to retrieve the latest processing status of the e-invoicing document. While Chargebee primarily relies on the callback listener to receive status updates, this endpoint serves as a fallback mechanism to ensure status synchronization. ' # Submit a document Source: https://spidocs.chargebee.com/api-reference/einvoicing-spi/endpoints/v1/documents/submit-a-document post /einvoicing/documents Submits a new document, such as an invoice or credit note, to the connected e-invoicing provider for validation, compliance checks, and delivery to the appropriate tax authorities or business partners. This endpoint is MANDATORY for enabling document submission through the Chargebee E-invoicing SPI framework. Within Chargebee, this endpoint is invoked asynchronously by an internal background job whenever a new invoice, credit note, or other supported billing document is generated and requires processing through the configured e-invoicing provider. If the e-invoicing provider requires merchants to configure field mappings manually, instead of relying on predefined mappings managed by Chargebee, Chargebee will collect this mapping as entered by the Chargebee merchant through the Chargebee Admin Console. The collected field mapping and the corresponding input values will be passed to the adapter via the `overrides` parameter. Note: When the `overrides` parameter is present, the adapter must rely exclusively on the `field_mapping` and `values` defined within it. All other standard schema fields should be ignored for transformation purposes. Additionally, this endpoint supports submission of Application Response documents, such as invoice acknowledgements or rejections, to facilitate downstream workflows and business rule validation. These responses are submitted using the same endpoint but distinguished using a type discriminator with APPLICATION_RESPONSE. # Overview Source: https://spidocs.chargebee.com/api-reference/partner-spi/overview **Partner SPI** is designed to enable seamless integration with Chargebee, allowing partners to extend and enhance the platform's functionality. This SPI offer a standardized interface for partners to connect their services, enabling efficient workflows and exceptional user experience. It is built for scalability and easy integration, helping partners deliver specialized functionality that caters to Chargebee's diverse customer needs. You can explore the OpenAPI specifications for Partner SPI in the GitHub repository [here](https://github.com/chargebee/cb-partner-spi). ## Key Features of Partner SPI 1. ### Tax Calculation Integrate tax computation services effortlessly to ensure compliance and achieve real-time accuracy. 2. ### Tax Reconciliation Submit invoice and credit note data to external systems for tax reconciliation. 3. ### Tax Registration Number Validation Validate tax registration numbers instantly to simplify customer onboarding and meet compliance requirements. 4. ### E-invoicing Seamlessly generate and submit compliant electronic invoices through connected e-invoicing networks to meet country-specific regulatory mandates and reduce manual processing. # Overview Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/docs/overview # Tax Registration Number Validate SPI Integration The **Tax Registration Number Validate Service Provider Interface (SPI)** enables seamless communication between Chargebee and external API platforms offering tax-related services. You can refer the spec file for this spi [here](https://github.com/chargebee/cb-partner-spi/blob/main/spec/spi/openapi_trn.yml). This SPI allows Chargebee to efficiently validate tax registration numbers for merchants, supporting both individual and batch validation processes. This document provides a comprehensive overview for third-party users looking to integrate their API platforms with Chargebee's Tax Registration Number Validation Service, ensuring a secure and smooth validation experience for merchants within the Chargebee ecosystem. ## Key Services Provided * **Individual Tax Registration Number Validation**: Validates the accuracy and legitimacy of tax registration numbers on a one-by-one basis. * **Batch Tax Registration Number Validation**: Enabling bulk validation simplifies the validation process for merchants handling large datasets. ## Integrate your Tax Registration Number Validation Service Adapter App To integrate your Tax Registration Number Validation Service Adapter App you can follow the App Onboarding process from [here](../../../app-onboarding/guide). # Testing with Postman Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/docs/testing-with-postman Postman is an API development environment that simplifies running and testing API requests. With Postman, you won’t have to copy and paste data from one endpoint to another. [![Run In Postman](https://run.pstmn.io/button.svg)](https://chargebee.postman.co/collection/19303335-f9503437-0c58-4967-8aa7-3626090ec486?source=rip_markdown\&active-environment=19303335-298da9ef-c95b-451f-99c6-b107d6740f05) 1. **Download and Install Postman** * Download Postman from the [Postman Downloads page](https://www.postman.com/downloads/). * Install the application on your system by following the setup instructions. 2. **Access Tax Registration Validation SPI** * Visit the [Tax Registration Number Validate SPI Workspace](https://chargebee.postman.co/collection/19303335-f9503437-0c58-4967-8aa7-3626090ec486?source=rip_markdown\&active-environment=19303335-298da9ef-c95b-451f-99c6-b107d6740f05). 3. **Fork Collection and select the Environment** * Fork the Collection and choose the "Tax Registration Number Validate" environment from the Postman workspace. 4. **Configure Environment Variables** * Add the following environment variables: * `url` - The base URL of the app. * `authorization_header` - The value for the authorization header required for API authentication. Refer to the [Authorization section](../docs/Authorization) to know more about this. Now, you're ready to interact with Tax Registration Number SPI endpoints using Postman. # Delete the request of batch of tax registration numbers validation Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/delete-the-request-of-batch-of-tax-registration-numbers-validation delete /trn/validate/batch/{batchId} This endpoint takes the batch id and delete the running batch of tax registration numbers validation request at server side. # Fetch the health status of the Service Provider. Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/fetch-the-health-status-of-the-service-provider get /health This endpoint is used to fetch the health status of the Service Provider. # Get the response of batch of tax registration numbers Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/get-the-response-of-batch-of-tax-registration-numbers get /trn/validate/batch/{batchId} This endpoint takes the batch id and returns the response of batch of tax registration numbers. # Get the response of tax registration number validate request Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/get-the-response-of-tax-registration-number-validate-request get /trn/validate/{requestId} This endpoint takes the request id and returns the response of the tax registration number # Validate credentials Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/validate-credentials post /credentials/validate This endpoint is used to validate the credentials used to call the Service Provider. # Validate the tax registration number Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/validate-the-tax-registration-number post /trn/validate This endpoint takes the details of tax registration number and validate. # Validate the tax registration numbers in batch Source: https://spidocs.chargebee.com/api-reference/tax-reg-number-validate/endpoints/v1/validate-the-tax-registration-numbers-in-batch post /trn/validate/batch This endpoint takes the batch of tax registration numbers and validate. # Authorization Source: https://spidocs.chargebee.com/api-reference/tax-spi/docs/authorization ## Overview Chargebee uses [**HTTP header-based authorization**](https://datatracker.ietf.org/doc/html/rfc7235) for all API endpoints related to the Service Adapter. This approach ensures secure and dynamic management of authorization credentials during API interactions. ## How It Works * The **Authorization Key** for API calls is dynamically passed in the HTTP header, enabling secure and seamless integration. * This key is specified in the `[api_configuration](url)` object, which is part of the JSON configuration used during onboarding in Chargebee's marketplace. (Attach link) * During the application onboarding process in Chargebee, merchants provide the necessary authorization parameter values. * The Chargebee application uses these values to authenticate and make API calls to the Service Adapter. ## Structure of `credential_configuration` * The `credential_configuration` is an array of objects, where each object represents a credential parameter. * Each object includes the following attributes: * **`id`**: A unique identifier for the credential. For example, `authorization_key` or `client_secret`. * **`name`**: A descriptive label of the credential. * **`type`**:The credential type. For example, `text`. * **`is_sensitive`**: Indicates whether the credential is sensitive. ## JSON Configuration Example ```json theme={null} { "api_configuration": { "api_base_url": "https://chargebee.partnerX.com/v1", "credential_configuration": [ { "id": "api_key", "name": "API Key", "type": "text", "is_sensitive": true }, { "id": "company_code", "name": "Company code", "type": "text", "is_sensitive": false } ] } } ``` ## Authorization Header Below is the structure of authorization header that will be passed from Chargebee app to Service Adapter. Some of the parameters are sent by default by Chargebee as mentioned in the example below: ```json theme={null} { --header 'Authorization: { "api_key": "api_keyX", "merchant_id": "merchant_id_partnerX", //sent by Chargebee by default "company_code": "company_code_partnerX", //sent by Chargebee by default "trace_id": "12345-abcde-67890" //sent by Chargebee by default } ' } ``` # Overview Source: https://spidocs.chargebee.com/api-reference/tax-spi/docs/overview # Tax SPI Integration Chargebee simplifies tax management during checkout sessions and invoice generation throughout the subscription lifecycle by performing the following operations: ### 1. Validating Customer Shipping Address Validates shipping addresses to ensure accurate tax calculation and product delivery. ### 2. Tax Estimation Calculates applicable taxes for invoices and their line items. ### 3. Tax Reconciliation Submits invoice and credit note data to external systems for tax reconciliation. Chargebee leverages external tax services to execute these operations effectively. These services can be categorized as: * **Third-Party Tax Service Providers:**\ APIs provided by third-party tax service vendors for tax calculation and reconciliation. * **Merchant's In-House Tax Software:**\ Custom-built tax management solutions used internally by merchants. ## The Role of the Tax Service Adapter App To connect with external tax services, Chargebee requires a tax service adapter—a bridge facilitating seamless communication between Chargebee and the tax service. This connection is established using the **Tax Service Provider Interface (SPI)**. ## Building a Tax Service Adapter App To integrate a tax service with Chargebee, you must implement the Tax SPI (you can refer the spec file for this spi [here](https://github.com/chargebee/cb-partner-spi/blob/main/spec/spi/openapi_tax.yml)) by developing a tax service adapter app. This is essential for one of the following scenarios: * ### As a Tax Service Provider: Connect your tax service with Chargebee to provide seamless tax calculation capabilities to merchants. * ### As a Merchant: Connect your in-house tax software to Chargebee for tailored tax management. * ### As a System Integrator: Develop a connector to bridge a tax service provider and Chargebee, enabling integration for merchants. By implementing the Tax SPI, you enable Chargebee to perform tax-related operations efficiently, ensuring accurate compliance and streamlined workflows. How Chargebee interacts with the tax service via the adapter ## JSON Schema for Tax Provider Below is the Chargebee Tax Provider [JSON Schema](https://json-schema.org/docs). Using this schema ensures that your tax provider data is structured accurately and complies with Chargebee’s platform requirements. This improves data consistency and simplifies integration with other systems or applications. [View Full Tax Provider JSON Schema](https://github.com/chargebee/cb-partner-spi/blob/main/spec/capabilities/tax-provider.schema.json) # Testing with Postman Source: https://spidocs.chargebee.com/api-reference/tax-spi/docs/testing-with-postman Postman is an API development environment that simplifies running and testing API requests. With Postman, you won’t have to copy and paste data from one endpoint to another. [![Run In Postman](https://run.pstmn.io/button.svg)](https://chargebee.postman.co/collection/19303335-eef7d7e8-4c3a-44f0-bb20-f25dad404186?source=rip_markdown\&active-environment=19303335-bb889063-006c-486c-8675-ac66c55b84a3) 1. **Download and Install Postman** * Download Postman from the [Postman Downloads page](https://www.postman.com/downloads/). * Install the application on your system by following the setup instructions. 2. **Access Tax SPI** * Visit the [Tax SPI Workspace](https://chargebee.postman.co/collection/19303335-eef7d7e8-4c3a-44f0-bb20-f25dad404186?source=rip_markdown\&active-environment=19303335-bb889063-006c-486c-8675-ac66c55b84a3). 3. **Fork Collection and select the Environment** * Fork the Collection and choose the "Tax\_Provider" environment from the Postman workspace. 4. **Configure Environment Variables** * Add the following environment variables: * `url` - The base URL of the app. * `authorization_header` - The value for the authorization header required for API authentication. Refer to the [Authorization section](../docs/Authorization) to know more about this. Now, you're ready to interact with Tax SPI endpoints using Postman. # Address validation Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/address-validation post /address/validate Checks whether a given address is a valid delivery address for shipping purposes. The tax provider can decide whether to mention the full or valid address depending on their requirement. # Check taxability Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/check-taxability post /address/check-taxability Checks whether the tax address is valid in terms of tax calculation. This endpoint checks whether the address information of the customer is sufficient for the tax provider to return a tax rate. It does not consider the nexus status of the merchant and is mandatory to integrate for the tax provider. # Commit credit note Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/commit-credit-note post /credit-notes/{creditNoteId}/commit This endpoint is used to mark a credit note as committed. Once committed, the credit note is considered as finalized. # Commit Invoice Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/commit-invoice post /invoices/{invoiceId}/commit This endpoint is used to commit an invoice for a given invoice id. Once committed, the invoice is considered to be finalized. # Create credit note Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/create-credit-note post /credit-notes This endpoint is used to send a credit note to the Tax Service Adapter. A credit note is used to reduce the amount due on an invoice. If the credit note is issued after payments have been made for the invoice, refunds can be issued to the Customer. # Create Invoice Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/create-invoice post /invoices This endpoint is used to send an invoice to the Tax Service Provider. Invoices created in Chargebee are statements of amounts owed by the Customer to the Merchant for a specific purchase. # Estimate tax Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/estimate-tax post /tax-estimate This endpoint is used to estimate taxes for a set of line items being sold by the Merchant to a Customer and is mandatory to integrate for the tax provider # Fetch the health status of the Service Provider. Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/fetch-the-health-status-of-the-service-provider get /health This endpoint is used to fetch the health status of the Service Provider. # Retrieve credit note Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/retrieve-credit-note get /credit-notes/{creditNoteId} This endpoint is used to retrieve a specific credit note using the unique credit note id. # Retrieve Invoice Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/retrieve-invoice get /invoices/{invoiceId} This endpoint is used to retrieve an invoice for a given invoice id. # Validate credentials Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/validate-credentials post /credentials/validate This endpoint is used to validate the credentials used to call the Service Provider. # Void credit note Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/void-credit-note post /credit-notes/{creditNoteId}/void This endpoint is used to void the credit note for a specific credit note id. Voiding reverses the credit note, thereby restoring the amount due on the invoice. # Void Invoice Source: https://spidocs.chargebee.com/api-reference/tax-spi/endpoints/v1/void-invoice post /invoices/{invoiceId}/void This endpoint is used to mark a specific invoice as void. Voiding cancels the invoice without deleting it. # Troubleshooting Source: https://spidocs.chargebee.com/api-reference/troubleshooting The `trace_id` included in the Authorization header is a unique identifier that helps track API requests across systems. It's a valuable tool for troubleshooting issues such as failed requests, authentication errors, or slow responses. ### How to Use `trace_id` for Troubleshooting: 1. **Locate the `trace_id`:**\ The `trace_id` is found in the Authorization header of the API request, for example: ```json theme={null} { --header 'Authorization: { "api_key": "api_keyX", "merchant_id": "merchant_id_partnerX", //sent by Chargebee by default "trace_id": "12345-abcde-67890" //sent by Chargebee by default } ' } ``` 2. **Track Requests Across Systems:** Use the trace\_id to trace the request through your logs and identify where issues may have occurred such as: * Incoming requests. * Internal processing layers. * Outgoing responses to Chargebee. 3. **Collaborate with Chargebee:** -Using `trace_id`: If a request fails or behaves unexpectedly, share the `trace_id` with Chargebee's team. This helps them identify the exact request and investigate the root cause efficiently. Similar way Chargebee team can also use the `trace_id` to reach out Partner team for any issues. 4. **Common Issues to Troubleshoot:** * Authentication Errors (401/403): Verify api\_key and merchant\_id. * Data Mismatches: Trace the request to spot discrepancies. * Timeouts or Slow Responses: Use the trace\_id to identify bottlenecks. # Integrating your App with Chargebee Source: https://spidocs.chargebee.com/app-onboarding/guide Guide to integrate your app with Chargebee and list it on Chargebee’s marketplace. ## Developing an App to Integrate with Chargebee Chargebee partners can use the [Service Provider Interfaces (SPI)](https://spidocs.chargebee.com/api-reference/partner-spi/overview) to develop apps that seamlessly integrate with Chargebee. These apps extend Chargebee's core capabilities to support diverse business use cases. ### Steps to Develop Your Application 1. **Understand the OpenAPI Specification**: Review the OpenAPI specification and integration details to design and build an app with seamless functionality. 2. **Implement SPI-Defined Endpoints**: Develop endpoints as outlined in the SPI documentation to ensure compatibility with Chargebee’s ecosystem. 3. **Adhere to Requirements**: Review the [General Requirements](#general-requisites) and [Technical Requirements](#technical-requisites) to ensure compliance with Chargebee’s guidelines. 4. **Test the Integration**: Perform both **API Testing** and **End-to-End Testing** to ensure a seamless integration with Chargebee: * **API Testing**: Validate and test your App using the provided [Postman collection](https://www.postman.com/chargebee/chargebee-partners/overview). * **End-to-End Testing**: Test all required Chargebee use cases by integrating your app with Chargebee’s sandbox environment. To request sandbox access, [follow](#go-live-steps) -> Step 3. ## Onboarding Process for Apps via SPI ### General Requisites To list your app on **Chargebee's Marketplace** as a solution provider, complete the following steps: 1. **Compliance with PII Standards** * Ensure your app complies with **Personal Identifiable Information (PII)** standards. * Handle merchant-specific confidential data securely and in accordance with PII guidelines. * Refer to Chargebee's [Security and Compliance Guidelines](https://www.chargebee.com/security/) to meet data privacy and security requirements. * Provide **Service Level Agreements (SLAs)** that address data deletion requirements. 2. **Traffic Management** * Accept traffic **only from allow-listed servers** to maintain secure interactions within Chargebee's ecosystem. 3. **Legal Agreements** * Sign a formal agreement with Chargebee to establish clear terms and conditions. 4. **Responsibilities as a Solution Provider** * Execute agreements directly with merchants using your app. * Clearly define the scope of data accessed from Chargebee, including customer and transaction details. 5. **Pre-Go-Live Deliverables** Submit the following details to the Chargebee team: * **Escalation Matrix**: Define critical issue resolution steps. * **Merchant Support Email**: Provide contact information for merchant queries. * **Partner Support Email**: Share a dedicated technical support email. * **Merchant User Guides**: Include links to detailed guides for merchants. * **Configuration Documentation**: Explain configurations such as managing API keys and importing plans. 6. **System Status and Maintenance Updates** * Maintain a public **external product status page** to communicate system outages and scheduled maintenance. This status page must reflect the health status of both the actual service provider and the application. 7. **Terms, Consent, and Privacy Policies** * Publish the following policies on your website: * Terms of Service * Consent Policy * Privacy Policy By following these guidelines, you can ensure a seamless onboarding process and compliance with Chargebee’s standards for integrating apps into its ecosystem. ### Technical Requisites 1. **Availability** * Ensure **99.9% uptime** for your app. * Provide advance notice for scheduled downtime to minimize disruptions. **Note**: Uninformed downtimes may lead to the app being **delisted** from the marketplace. 2. **Rate Limiting** * Rate limiting is enforced based on the Chargebee customer's subscription plan. Detailed information is available [here](https://apidocs.chargebee.com/docs/api/error-handling?lang=curl#api_rate_limits) * The App must account for these rate limits and implement appropriate mechanisms to handle requests within the allowed capacity. 3. **Latency** * Respond within a **maximum latency of 250ms** per request. Latencies exceeding this threshold are considered unacceptable. 4. **Quality** * Provide a consistent and positive experience to merchants. 5. **Security & Certifications** * Use **Transport Layer Security (TLS)** for all communication to ensure a secure channel. * Obtain **PII compliance certification** to proceed with agreements as Chargebee shares customers’ data. 7. **Concurrency Handling** * Ensure your application can handle **concurrent requests** effectively for seamless operation during peak loads. 8. **Webhooks to Chargebee** * If the SPI implementation supports sending webhook events to Chargebee, ensure that your app's IP address is whitelisted to allow secure communication. ## Go Live Steps 1. **Fill Configuration & Capability** * Fill in the configuration and capabilities of your adapter by referring to the [JSON Schema](https://github.com/chargebee/cb-partner-spi/tree/main/spec/capabilities) provided by Chargebee. 2. **Submit Details to Chargebee** * Send the completed configurations, capabilities details, and test suite results to the Chargebee team at **[taxation@chargebee.com](mailto:taxation@chargebee.com)**. 3. **Internal Review & Testing** * Reach out to the [Partnership Team](mailto:partnerships@chargebee.com) for access to the Chargebee production sandbox site. * In parallel develop and test the app service based on the requirements mentioned here: [Developing an App to Integrate with Chargebee](#developing-an-app-to-integrate-with-chargebee). * Once submitted, Chargebee's internal review team will test your integration through a combination of **manual and automated testing**. * Your integration will also undergo **stress testing** to ensure it can handle Chargebee’s peak loads. 4. **Marketplace Listing Form** * After the review team approves your app, fill out the marketplace listing form which will be provided by Chargebee team. This form will include: * Details to be published on your app’s landing page on the Chargebee marketplace. * Product screenshots or videos as required. 5. **Accept the Marketplace Agreement** * Review and accept the **marketplace agreement** with Chargebee. *** ## Publishing Your App on the Marketplace ### Why Publish on the [Chargebee Marketplace](https://marketplace.chargebee.com/)? * **Visibility**: The marketplace is a platform where merchants discover and install apps to extend Chargebee’s capabilities. * **Ease of Use**: By listing your app, merchants can install it with a single click and start using it immediately. * **Promotion**: Leverage Chargebee’s marketing channels to reach a broader audience of merchants. ### Publication Process 1. **Private App Launch** * Initially, your app will be published as a **private app** on the marketplace. * Merchants can access private apps through a **private URL**, enabled via backend configuration. To gain access, merchants must contact [Chargebee support](https://support.chargebee.com/support/home). 2. **Transition to Public App** * Once at least **five merchants** actively use your integration, you can request to make your app public by contacting **[taxation@chargebee.com](mailto:taxation@chargebee.com)**. * Chargebee’s team will review your request and approve your app for public listing. By following these steps, your app will be successfully published on the Chargebee marketplace, reaching a wider audience and enhancing its visibility and usage.\ will review your request and make your app public.