Import Data in Bulk

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 objectCorresponding single-object endpoint
CustomersCreate a Customer
PlansCreate a Plan
InvoicesImport Invoices
Line itemsImport Invoices
TransactionsImport Invoices or Import an Invoice Transaction
Subscription eventsCreate 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": "scus_0001",
              "subscription_set_external_id": "sub_0001b",
              "subscription_external_id": "evnt_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"
}
Language