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. |