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