Imports multiple customers, plans, invoices, line items, transactions, and subscription events with a single API query.
This endpoint enables the import of multiple objects with a single API query. You can import different types of objects at the same time.
The Import Data in Bulk endpoint is an alternative to importing data via Import API single-object endpoints (such as Create a Customer or Import Invoices).
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.
Payload size and number of records per Bulk Import API request
The JSON payload size should not exceed 5MB.
There’s no exact limit on the number of customers (and corresponding records) you can import in a single Bulk Import API request. It depends on multiple factors, such as upload speed on the requester side, the data set size, or the number of records (such as invoices, line items, transactions, subscription events, etc.) per customer.
Our recommendation is to test the import in a test data source to fine-tune the number of customers (and corresponding records) per API query. In most cases, it’s optimal to import between 100 and 1,000 customers (and corresponding records such as invoices, line items, etc.) per Bulk Import API query.
Here’s the list of object types you can import:
| Type of object | Corresponding single-object endpoint |
|---|---|
| Customers | Create a Customer |
| Plans | Create a Plan |
| Invoices | Import Invoices |
| Line items | Import Invoices |
| Transactions | Import Invoices or Import an Invoice Transaction |
| Subscription events | Create a Subscription Event |
Examples
curl -X POST "https://api.chartmogul.com/v1/data_sources/ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba/json_imports" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"external_id": "ds_import_1",
"customers": [
{
"external_id": "scus_0001",
"name": "Andrew Jones",
"email": "[email protected]",
"country": "US",
"state": "California",
"city": "San Francisco",
"zip": "90210",
"company": "CA Printing Company",
"lead_created_at": "2023-05-14 00:00:00",
"free_trial_started_at": "2023-06-01 00:00:00"
}
],
"plans": [
{
"name": "Gold Biannual",
"external_id": "gold_biannual",
"interval_count": 6,
"interval_unit": "month"
}
],
"invoices": [
{
"external_id": "inv_001",
"date": "2023-04-02 21:37:00",
"due_date": "2023-05-02 21:37:00",
"currency": "USD",
"customer_external_id": "scus_0001"
},
{
"external_id": "inv_002",
"date": "2023-05-02 21:37:00",
"due_date": "2023-06-02 21:37:00",
"currency": "USD",
"customer_external_id": "scus_0001"
},
{
"external_id": "inv_003",
"date": "2023-06-02 21:37:00",
"due_date": "2023-07-02 21:37:00",
"currency": "USD",
"customer_external_id": "scus_0001"
}
],
"line_items": [
{
"type": "subscription",
"amount_in_cents": 1000,
"quantity": 1,
"invoice_external_id": "inv_001",
"plan_external_id": "gold_biannual",
"subscription_external_id": "sub_0001",
"service_period_start": "2023-04-02 21:37:00",
"service_period_end": "2023-05-02 21:37:00"
},
{
"type": "subscription",
"amount_in_cents": 1000,
"quantity": 1,
"invoice_external_id": "inv_002",
"plan_external_id": "gold_biannual",
"subscription_external_id": "sub_0001",
"service_period_start": "2023-05-02 21:37:00",
"service_period_end": "2023-06-02 21:37:00"
},
{
"type": "subscription",
"amount_in_cents": 1500,
"quantity": 1,
"invoice_external_id": "inv_003",
"plan_external_id": "gold_biannual",
"subscription_external_id": "sub_0001",
"service_period_start": "2023-06-02 21:37:00",
"service_period_end": "2023-07-02 21:37:00"
}
],
"transactions": [
{
"invoice_external_id": "inv_001",
"external_id": "trans_0001",
"type": "payments",
"result": "successful",
"date": "2023-04-02 21:37:00"
},
{
"invoice_external_id": "inv_002",
"external_id": "trans_0002",
"type": "payment",
"result": "failed",
"date": "2023-05-02 21:37:00"
},
{
"invoice_external_id": "inv_002",
"external_id": "trans_0003",
"type": "payment",
"result": "successful",
"date": "2005-05-03 21:37:00"
},
{
"invoice_external_id": "inv_003",
"external_id": "trans_0004",
"type": "payment",
"result": "successful",
"date": "2023-06-03 21:37:00"
}
],
"subscription_events": [
{
"external_id": "event_0001",
"subscription_set_external_id": "set_0001",
"subscription_external_id": "sub_001",
"customer_external_id": "scus_0001",
"plan_external_id": "gold_biannual",
"event_date": "2023-04-02 21:37:00",
"effective_date": "2023-04-02 21:37:00",
"event_type": "subscription_start",
"currency": "USD",
"amount_in_cents": 150000,
"quantity": 1
}
]
}'
Result Format
{
"id": "4815d987-1234-11ee-a987-978df45c5114",
"data_source_uuid": "1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"status": "queued",
"external_id": "ds_import_1",
"status_details": {},
"created_at": "2023-06-01T23:55:23Z",
"updated_at": "2023-06-01T23:55:23Z"
}