Import Data in Bulk

POST https://api.chartmogul.com/v1/data_sources/{data_source_uuid}/json_imports

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

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
              }
            ]
        }'

{
  "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"
}

Path parameters

data_source_uuid string required: The ChartMogul UUID of the data source where you want to store this imported objects.

Body parameters

external_id string required

A unique identifier specified by you for the import.

customers array(object)

Array of customer objects to import under the specified data_source.

external_id string required: A unique identifier specified by you for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters.
company string: The customer's company or organisation.
country string: Country code of customer's location as per ISO-3166 alpha-2 standard.
state string: The US state where the customer is located — the US state code as per the ISO-3166-2 standard. For example, US-CA or US-NY.
city string: City of the customer's location.
zip string: Zip code of the customer's location.
lead_created_at datetime: Time at which this customer was established as a lead. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified.
free_trial_started_at datetime: Time at which this customer started a free trial of your product or service. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified. This is expected to be the same as or after the lead_created_at value.

plans array(object)

Array of plan objects to import under the specified data_source.

name string required: Display name of the plan. Accepts alphanumeric characters.
interval_count int32 required: The frequency of billing interval. Accepts integers greater than 0. eg. 6 for a half-yearly plan.
interval_unit string required: The unit of billing interval. One of day, month or year. eg. month for the above half-yearly plan.
external_id string: A unique identifier specified by you for the plan. Typically an identifier from your internal system. Accepts alphanumeric characters. If not provided, ChartMogul will automatically generate one.

invoices array(object)

Array of invoice objects to import under the specified data_source.

customer_external_id string required: A unique identifier specified by you for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters.
external_id string required: A unique identifier specified by you for the invoice. Typically the Invoice Number in your system. Accepts alphanumeric characters.
date datetime required: The date on which this invoice was raised. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
due_date datetime: The date within which this invoice must be paid. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
currency string: The 3-letter currency code of the currency in which this invoice is being billed, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies.

line_items array(object)

Array of line_item objects to import under the specified data_source.

invoice_external_id string required: A unique identifier specified by you for the invoice to which this line item belongs to. Typically the Invoice Number in your system. Accepts alphanumeric characters.
type string required: One of either subscription or one_time.
amount_in_cents int32 required: The final amount charged towards this line item, for the specified quantity and service period, after discounts, taxes and fees have been applied. Expected in cents (or pence for GBP, etc.). This is the amount that is primarily used to calculate MRR.
external_id string: A unique identifier specified by you for the line item. Typically an identifier from your internal system. Accepts alphanumeric characters.
subscription_external_id string: A reference identifier for the subscription in your system. Accepts alphanumeric characters. Required for subscription line items. Irrelevant for one_time line items.
subscription_set_external_id string: A reference identifier for a set of subscriptions in order to group several subscriptions into one set. Only relevant for subscription line items
plan_external_id string: A unique identifier specified by you for the plan. Typically an identifier from your internal system. Accepts alphanumeric characters. If Plan external_id is not provided during Plan creation, ChartMogul will automatically generate one and you'll need to fetch the Plan to find the automatically generated Plan external_id.
service_period_start datetime: The start of the service period for which this subscription is being charged. Required for subscription line items. Irrelevant for one_time line items. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
service_period_end datetime: The end of the service period for which this subscription is being charged. Required for subscription line items. Irrelevant for one_time line items. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
prorated boolean default: false: If this is a prorated line_item, then set this attribute to true. Accepted for subscription line items. Irrelevant for one_time line items.
proration_type string: If not provided, or set to differential, prorated line items are classified as an upgrade or downgrade and added to previously calculated MRR and subscription quantity. If set to full, prorated line items have a partial service period and do not take previously calculated MRR and subscription quantity into consideration. If set to differential_mrr, the amount from this prorated line item behaves like differential proration, which means it is added to previously calculated MRR. The quantity from this prorated line item behaves like full proration, which means it is not added to previously calculated subscription quantity. Accepted for subscription line items. Irrelevant for one_time line items.
description string: A short description of the non-recurring item being charged to the customer. Accepted for one_time line items. Ignored for subscription line items.
quantity int32 default: 1: The quantity/seats of the subscription being billed by this line item. Can be any non-zero integer. Defaults to 1. Quantity value does not impact calculation of MRR. It is used for additional segmentation by subscription quantity and generating Subscription Quantity charts.
discount_amount_in_cents int32 default: 0: If any discount has been applied to this line item, then the discount amount in cents. Defaults to 0. Discount amount does not impact calculation of MRR.
discount_code string: If a discount has been applied to this line item, then an optional reference code to identify the discount.
tax_amount_in_cents int32 default: 0: The tax that has been applied to this line item, in cents. Defaults to 0. If specified, we exclude tax amount from MRR.
transaction_fees_in_cents int32: The final total transaction fees paid to billing provider and/or payment processor for this line item. Expected in cents (or pence for GBP, etc.).
transaction_fees_currency string: The 3-letter currency code for transaction_fees_in_cents, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies.
discount_description string: A short description of discount_amount_in_cents.
event_order int32: Used for ordering events that happen at the same time.

transactions array(object)

Array of transaction objects to import under the specified data_source.

invoice_external_id string required: A unique identifier specified by you for the invoice to which this transaction belongs to. Typically the Invoice Number in your system. Accepts alphanumeric characters.
type string required: Either one of payment or refund.
result string required: Either one of successful or failed.
date datetime required: The timestamp of when the transaction was attempted. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
external_id string: A unique identifier specified by you for the transaction. Typically an identifier from your internal system. Accepts alphanumeric characters.
amount_in_cents int32: The partial amount paid/refunded for this invoice. Expected in cents (or pence for GBP, etc.). If this field is not mentioned it will default to full amount. The sum of the partial payments/refunds should not exceed the invoiced amount.

subscription_events array(object)

Array of subscription_event objects to import under the specified data_source.

customer_external_id string required: A unique identifier specified by you for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters.
event_type string required: One of the ten subscription event types. See table here for details.
event_date datetime required: The date when this event was raised. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
effective_date datetime required: The date when this event takes effect. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
subscription_external_id string required: A unique identifier specified by you for the subscription which the subscription event is being added. Typically an identifier from your internal system. Accepts alphanumeric characters. Required for all subscription event types except subscription_event_retracted event type.
subscription_set_external_id string: A reference identifier for a set of subscriptions in order to group several subscriptions into one set.
external_id string: A unique identifier specified by you for the subscription event. Typically an identifier from your internal system. Accepts alphanumeric characters.
plan_external_id string: A unique identifier specified by you for the plan. Typically an identifier from your internal system. Accepts alphanumeric characters. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
currency string: The 3-letter currency code of the currency in which this subscription is being billed, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
amount_in_cents int32: The final amount charged towards this subscription on subscription start or subscription update, for the specified quantity and plan, after discounts, taxes and fees have been applied. Expected in cents (or pence for GBP, etc.). Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
quantity int32 default: 1: The quantity of subscription addressed by this subscription event. Can be any non-zero integer. Defaults to 1. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
tax_amount_in_cents int32 default: 0: The tax in cents that has been applied to subscription addressed by this subscription event. Defaults to 0.
retracted_event_id string: Required for subscription_event_retracted event type. Refers to the event id of the scheduled subscription event that is being retracted.