Bulk Import

The Bulk Import endpoint allows you to import multiple customers, plans, invoices, line items, transactions and subscription events with a single API query.

The Bulk Import endpoint is an alternative to importing data via Import API single-object endpoints (such as Create a Customer or Import Invoices).

The Bulk Import endpoint is useful when:

You only want to import data without listing, updating or deleting objects
You need to import many objects at once (e.g. more than 100)

Use Import API single-object endpoints (or a combination of the Bulk Import and single-object endpoints) when:

In addition to importing data, you want to list, update or delete objects
You need to import a relatively small number of objects (e.g. fewer than 100)

Comparison of the Bulk Import and single-object endpoints. Importing 100 customers with corresponding invoices, plans and subscription events requires 200–300 single-object API requests. Importing these objects with the Bulk Import endpoint uses one API query.

Importing multiple records for a customer. When using the Bulk Import endpoint, group all records and payloads for the same customer in a single API request. Send subsequent requests for this customer only after all previous API requests containing records for this customer have finished processing.

Here’s the list of differences between the Bulk Import endpoint and Import API single-object endpoints:

Functionality	Bulk Import	Import API single-object endpoints
Object validation	Validation of imported objects runs asynchronously after the import. Invalid objects are imported and marked as `Failed` in ChartMogul.	Validation runs synchronously during the API request. API requests with invalid objects are rejected immediately with an appropriate HTTP response.
Multiple objects in a single API request	Yes, which substantially reduces the number of API requests.	Only some endpoints (e.g. Import Invoices) allow multiple objects of the same type in a single API query.
Objects referencing ChartMogul UUIDs or external IDs	Objects that reference another object (e.g. an invoice requiring a reference to the invoiced customer) are referenced solely by external IDs.	API query parameters and objects that reference other objects require ChartMogul UUIDs. In most cases, this means you need an additional `List` API request to fetch the generated UUID.
Import/List/Update/Delete	Supports only the import of objects. Does not support listing, updating or deleting imported objects.	Supports the import of objects as well as listing, updating and deleting imported objects.