KintsugiKintsugi

Connect a chargebee account

POST/connections/chargebee/connect

Create or update a Chargebee connection for a site, or (with multipleBusinessEntityEnabled) one business entity under that site. Re-submitting for the same site (or the same site + business entity) updates the stored key rather than creating a second connection. Returns 400 if the credentials or business entity id are invalid, or if multipleBusinessEntityEnabled is true without a businessEntityId. A multi-org credential must send an Organization-Id, Connection-Id or Entity-Id selector, or gets a 400.

Authorization

Api-KeystringRequired

Your secret API key. Include it with every request.

Headers

Api-Versiondate

Release date, as YYYY-MM-DD. Defaults to 2026-07-21.

Organization-Idstring

Target organization id (Organization-Id selector).

Connection-Idstring

Target connection id; resolves to its organization.

Entity-Idstring

Platform entity id; resolves to a connection's organization.

Entity-Sourcestring

Optional source to disambiguate an Entity-Id.

Body

siteIdstringRequired

Chargebee site id.

urlstringRequired

Chargebee site URL.

apiKeystringRequired

Chargebee API key.

businessEntityIdstring

Business entity id; required when multipleBusinessEntityEnabled.

businessEntityNamestring

Business entity display name.

multipleBusinessEntityEnabledboolean

Connect one business entity rather than the whole site.

historicalSyncStartDatestring

Import floor for a brand-new connection, as YYYY-MM-DD. Ignored on reconnect. null imports all available history.

Response

idstringRequired

Kintsugi's unique identifier for the connection.

organizationIdstringRequired

Id of the organization this connection belongs to.

platformEntityIdstring

The platform's own identifier for the entity this connection points at (e.g. a QuickBooks realm id, D365 company id, NetSuite subsidiary id). Use it to resolve a connection from an id you already hold. null until captured on (re)connect or backfilled.

externalIdstringRequired

The connection's own external identifier: an Apideck consumer id for a Vault-backed source, or the platform-specific value the connector stores (e.g. a Shopify shop id, a Stripe publishable key).

sourcestringRequired

Origin platform of the connection (e.g. SHOPIFY, QUICKBOOKS). Any origin outside the published values is reported as OTHER.

Available options:ACUMATICAAIRWALLEXAMAZONAPIAPPLE_APP_STOREBESTBUYBIGCOMMERCEBILL_COMBUNNYCAMPFIRECHARGEBEECHECKOUTCHAMPDEELDUALENTRYEBAYECWIDETSYFACEBOOKFAIREFRESHBOOKSGOOGLE_APP_STOREGOOGLE_EXPRESSGROUPONGUSTOHYPERLINEINSTAGRAMINTUIT_ENTERPRISE_SUITEKICKSTARTERKILL_BILLMACYSMAGENTOMAXIOMERCADO_LIBREMICROSOFT_DYNAMICS_365MODALYSTNETSUITENEWEGGNOCNOCNORDSTROMODOOOPENMETERORBORDWAYOTHERPAYPALPINTERESTPLENTYONEQUICKBOOKSRECURLYRILLETRIPPLINGSAGE-INTACCTSALESFORCESHOPIFYSHOPLINESHOPWARESQUARESPACESTRIPETARGETTIKTOKVERTEX_O_SERIESWALMARTWAYFAIRWISHWIXWOOCOMMERCEXEROZENSKARZOHOZUORA
statusPublicConnectionStatusEnumRequired

Lifecycle status of the connection.

Available options:ACTIVEINACTIVECONNECTION_ERROR
storeNamestring

Human-readable store or account name for the connection; an empty string when the connection has none.

urlstring

Public shop/account URL when the source exposes one; not a secret.

createdAtstringRequired

When the connection was created.

updatedAtstring

When the connection was last updated.

lastSyncedstring

When this connection last completed a successful sync.

initialImportCompleteboolean

True once the initial historical import has finished.

recordsSyncedinteger

Approximate count of records synced so far.

taxCalculationReadyboolean

True when this connection meets the prerequisites for L2 tax-engine enablement.

taxCalculationEnabledboolean

L2 flag: whether tax calculation is enabled on this connection.

taxCalculationEnabledAtstring

When taxCalculationEnabled last flipped from false to true. Preserved across a later disable and restamped on re-enable.

taxCollectionOptedOutAtstring

When this connection opted out of L2 tax collection; null when not opted out.

needsUpdateboolean

True when the connection needs re-authorization or reconfiguration.

vertexEnabledboolean

True when Vertex O Series tax is enabled for this connection.

defaultCountrystring

Default tax country for this connection (ISO 3166-1 alpha-2); null when unset.

marketplaceIdstring

Amazon marketplace id; null for every non-Amazon connection.

netsuiteSyncModePublicNetsuiteSyncModeEnum

Which NetSuite transaction types this connection syncs. null for every non-NetSuite connection.

Available options:INVOICE_ONLYSALES_ORDER_ONLYSALES_ORDER_AND_INVOICECASH_SALE_ONLYINVOICE_AND_CASH_SALEALL
netsuiteCashSaleSyncEnabledboolean

True when NetSuite cash-sale sync is enabled; null for every non-NetSuite connection.

netsuiteAccountIdstring

NetSuite account id; null for every non-NetSuite connection.

netsuiteSubsidiaryIdstring

NetSuite subsidiary id; null for every non-NetSuite connection.

isOneworldAccountboolean

True for a NetSuite OneWorld account; null for every non-NetSuite connection.

microsoftD365HistoricalSyncStartDatestring

Import floor for this D365 connection, as YYYY-MM-DD. null for every non-D365 connection, or when unset.

airwallexHistoricalSyncStartDatestring

Import floor for this Airwallex connection, as YYYY-MM-DD. null for every non-Airwallex connection, or when unset.

woocommerceHistoricalSyncStartDatestring

Import floor for this WooCommerce connection, as YYYY-MM-DD. null for every non-WooCommerce connection, or when unset.

amazonHistoricalSyncStartDatestring

Import floor for this Amazon connection, as YYYY-MM-DD. null for every non-Amazon connection, or when unset.

xeroHistoricalSyncStartDatestring

Import floor for this Xero connection, as YYYY-MM-DD. null for every non-Xero connection, or when unset.

zuoraVertexTaxEngineIdstring

Zuora Vertex tax engine id; null for every non-Zuora connection.

zuoraVertexTaxCompanyIdstring

Zuora Vertex tax company id; null for every non-Zuora connection.

apideckConnectionStatestring

Raw Apideck Vault connection state (e.g. callable) for a Vault-backed source; null otherwise.

rilletWebhookTokenSetboolean

True once a Rillet webhook signing token has been saved.

odooHmacSecretSetboolean

True once an Odoo HMAC secret has been saved.

campfireWebhookSecretSetboolean

True once a Campfire webhook signing secret has been saved.

killbillHmacSecretSetboolean

True once a Kill Bill HMAC secret has been saved.

ordwayWebhookSecretSetboolean

True once an Ordway webhook secret has been saved.

ordwayWebhookLastReceivedAtstring

Timestamp of the last Ordway webhook callback received, as reported by Ordway; null if none yet.

billComWebhookConfiguredboolean

True once Bill.com webhook delivery has been configured.

plentyoneUsernamestring

PlentyONE username; null for every non-PlentyONE connection.

plentyoneHistoricalSyncStartDatestring

Import floor for this PlentyONE connection, as YYYY-MM-DD. null for every non-PlentyONE connection, or when unset.

plentyoneHistoricalSyncEndDatestring

Import ceiling for this PlentyONE connection, as YYYY-MM-DD. null for every non-PlentyONE connection, or when unset.

plentyoneMarketplaceOrdersstring

How this PlentyONE connection handles marketplace orders. null for every non-PlentyONE connection.

Available options:skiptag
200

Successful Response

400

The request was invalid.

401

Authentication failed or was missing.

403

The credential is not permitted for this request.

404

The requested resource was not found.

422

The request failed validation.

cURL
POST /connections/chargebee/connect
-H "Api-Key: ***"
-H "Api-Version: 2026-07-21"
{
"siteId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"url": "https://www.example.com",
"apiKey": "********",
"businessEntityId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"businessEntityName": "Acme Corp",
"multipleBusinessEntityEnabled": false,
"historicalSyncStartDate": "2026-07-21"
}
Response
{
"id": "conn_2mNpQr7Ls8f3k",
"organizationId": "orgn_2mNpQr7Ls8f3k",
"platformEntityId": "realm_1234567890",
"externalId": "order-1001",
"source": "QUICKBOOKS",
"status": "ACTIVE",
"storeName": "Acme Store",
"url": "https://www.example.com",
"createdAt": "2026-07-28T12:00:00Z",
"updatedAt": "2026-07-28T12:00:00Z",
"lastSynced": "2026-07-28T12:00:00Z",
"initialImportComplete": false,
"recordsSynced": 0,
"taxCalculationReady": false,
"taxCalculationEnabled": false,
"taxCalculationEnabledAt": "2026-07-28T12:00:00Z",
"taxCollectionOptedOutAt": "2026-07-28T12:00:00Z",
"needsUpdate": false,
"vertexEnabled": false,
"defaultCountry": "US",
"marketplaceId": "mktpl_2mNpQr7Ls8f3k",
"netsuiteSyncMode": "INVOICE_ONLY",
"netsuiteCashSaleSyncEnabled": false,
"netsuiteAccountId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"netsuiteSubsidiaryId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"isOneworldAccount": false,
"microsoftD365HistoricalSyncStartDate": "2026-07-21",
"airwallexHistoricalSyncStartDate": "2026-07-21",
"woocommerceHistoricalSyncStartDate": "2026-07-21",
"amazonHistoricalSyncStartDate": "2026-07-21",
"xeroHistoricalSyncStartDate": "2026-07-21",
"zuoraVertexTaxEngineId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"zuoraVertexTaxCompanyId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"apideckConnectionState": "apideck connection state",
"rilletWebhookTokenSet": false,
"odooHmacSecretSet": false,
"campfireWebhookSecretSet": false,
"killbillHmacSecretSet": false,
"ordwayWebhookSecretSet": false,
"ordwayWebhookLastReceivedAt": "2026-07-21T15:30:00Z",
"billComWebhookConfigured": false,
"plentyoneUsername": "Acme Corp",
"plentyoneHistoricalSyncStartDate": "2026-07-21",
"plentyoneHistoricalSyncEndDate": "2026-07-21",
"plentyoneMarketplaceOrders": "skip"
}
Connect a chargebee account (2026-07-21) | Kintsugi API Reference