Import Data in Bulk

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

Imports or updates multiple records with a single API query.

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
              }
            ],
            "contacts": [
              {
                "customer_external_id": "scus_0001",
                "external_id": "cont_0001",
                "first_name": "Andrew",
                "last_name": "Jones",
                "title": "CEO",
                "email": "[email protected]",
                "phone": "+1234567890"
              }
            ],
            "customer_notes": [
              {
                "customer_external_id": "scus_0001",
                "type": "note",
                "author_email": "[email protected]",
                "text": "Customer interested in upgrading plan.",
                "created_at": "2023-06-01T10:00:00Z"
              }
            ],
            "tasks": [
              {
                "customer_external_id": "scus_0001",
                "task_details": "Follow up on upgrade discussion",
                "assignee": "[email protected]",
                "due_date": "2023-06-15"
              }
            ],
            "opportunities": [
              {
                "customer_external_id": "scus_0001",
                "owner": "[email protected]",
                "pipeline": "New Business",
                "pipeline_stage": "Discovery",
                "estimated_close_date": "2023-09-01",
                "amount_in_cents": 100000,
                "currency": "USD"
              }
            ],
            "customer_tags": [
              {
                "customer_external_id": "scus_0001",
                "tags": ["important", "enterprise"]
              }
            ],
            "custom_attributes": [
              {
                "type": "String",
                "key": "industry",
                "associated_object": "customer"
              }
            ],
            "custom_attribute_values": [
              {
                "associated_object": "customer",
                "key": "industry",
                "value": "Technology",
                "associated_object_identifier": {
                  "method": "external_id",
                  "value": "scus_0001"
                }
              }
            ]
        }'

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

This endpoint enables the import or update of multiple records with a single API query. You can import or update 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 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 or Create a Line Item
Transactions	Import Invoices or Create a Transaction
Subscription events	Create a Subscription Event
Contacts	Create a Contact
Notes & Call Logs	Create a Note or Call Log
Tasks	Create a Task
Opportunities	Create an Opportunity
Customer Tags	Add Tags to a Customer
Custom Attributes	Add Custom Attributes to a Customer

data_source_uuid as a path or body parameter.

The data_source_uuid can be provided either as a URL path parameter (/data_sources/{DATA_SOURCE_UUID}/json_imports) or as a JSON body parameter using the /v1/json_imports endpoint. Use the body parameter when importing objects that are not data source-scoped (such as notes and call logs, tasks, opportunities, and customer tags), or when you want to mix data source-scoped and non-scoped objects in a single request.

Path parameters

data_source_uuid string optional: The ChartMogul UUID of the source where you want to store the imported objects. Required if data_source_uuid is not provided in the request body.

Body parameters

external_id string required

A unique identifier specified by you for the import.

data_source_uuid string optional

The ChartMogul UUID of the source where you want to store the imported objects. Required if data_source_uuid is not provided as a URL path parameter.

customers array(object) optional

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.; Use an existing external ID to update a customer rather than create a new one.
company string optional: The customer's company or organisation.
country string optional: Country code of customer's location as per ISO-3166 alpha-2 standard.
state string optional: 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 optional: City of the customer's location.
zip string optional: Zip code of the customer's location.
lead_created_at datetime optional: 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 optional: 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) optional

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 optional: 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.; Use an existing external ID to update a plan rather than create a new one.

invoices array(object) optional

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.

Use an existing external ID to update an invoice rather than create a new one.

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 optional

The date by 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 optional

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

collection_method string optional default: "automatic"

Specifies how the payment for the invoice is collected.

automatic—Payments are processed within the billing system without manual intervention (e.g., credit cards, PayPal, direct debits).

manual—Payments are handled outside the billing system and require customer or business action (e.g., checks, manual bank transfers).

line_items array(object) optional

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 subscription, one_time, or trial.

On October 2, 2025, we introduced trial as an invoice line item type. We’re gradually making the functionality available to all accounts. Learn more.

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 optional

A unique identifier specified by you for the line item. Typically an identifier from your internal system. Accepts alphanumeric characters.

Use an existing external ID to update a line item rather than create a new one.

subscription_external_id string optional

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 optional

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 optional

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 optional

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 optional

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

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. When there's a plan change, differential behaves like full and does not take previously calculated MRR and subscription quantity into consideration.

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 the previously calculated subscription quantity.

If set to differential_always, prorated line items are always classified as an upgrade or downgrade and added to previously calculated MRR and subscription quantity, even when there's a plan change.

Accepted for subscription line items. Irrelevant for one_time line items.

description string optional

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

If a discount has been applied to this line item, then an optional reference code to identify the discount.

tax_amount_in_cents int32 optional 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 optional

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 optional

The three-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 optional

A short description of discount_amount_in_cents.

event_order int32 optional

A numeric value that determines the sequence in which events are processed when multiple events occur at the same timestamp.

transactions array(object) optional

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 payment or refund.
result string required: Either 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 optional: A unique identifier specified by you for the transaction. Typically an identifier from your internal system. Accepts alphanumeric characters.; Use an existing external ID to update a transaction rather than create a new one.
amount_in_cents int32 optional: 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) optional

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 optional: A reference identifier for a set of subscriptions in order to group several subscriptions into one set.
external_id string optional: A unique identifier specified by you for the subscription event. Typically an identifier from your internal system. Accepts alphanumeric characters.; Use an existing external ID to update a subscription event rather than create a new one.
plan_external_id string optional: 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 optional: The three-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 optional: 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 optional 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 optional default: 0: The tax in cents that has been applied to subscription addressed by this subscription event. Defaults to 0.
retracted_event_id string optional: Required for subscription_event_retracted event type. Refers to the event id of the scheduled subscription event that is being retracted.

contacts array(object) optional

Array of contact objects to import.

customer_external_id string required: A unique identifier specified by you for the customer to associate the contact with. Typically an identifier from your internal system. Accepts alphanumeric characters.
external_id string optional: A unique identifier specified by you for the contact. Typically an identifier from your internal system. Accepts alphanumeric characters.
position integer optional: Sets the position of the contact in the UI. The first contact has a position of 1. If the number is higher than the number of contacts associated with this customer then the position itself is used as-is.
first_name string optional: The first name of the contact.
last_name string optional: The last name of the contact.
title string optional: The job title of the contact, e.g. "CEO".
email string optional: The contact's email address. Needs to be unique for the customer.
phone string optional: The contact's phone number.
linked_in string optional: The URL of the contact's LinkedIn profile.
twitter string optional: The URL of the contact's Twitter profile.
notes string optional: Additional notes or comments about the contact. Newline can be appended with \n in the string.
last_seen string optional: A timestamp of when the contact was last active, in the ISO 8601 format.

customer_notes array(object) optional

Array of note and call log objects to import.

customer_external_id string required: A unique identifier specified by you for the customer to associate the note or call log with. Typically an identifier from your internal system. Accepts alphanumeric characters.
type string required: The type of customer note. Can be either note or call.
author_email string optional: The email of the author of the note or call log. The email has to match a team member who belongs to the account.
text string optional: Contents of the note or call log as plain text or HTML.
call_duration integer optional: Relevant for type call. Duration of the call in seconds. Defaults to 60 seconds if not provided.
created_at string optional: The date and time when this note or call was made. Defaults to now if not provided. Must be an ISO 8601-formatted time in the past. The timezone defaults to UTC unless otherwise specified.

tasks array(object) optional

Array of task objects to import.

customer_external_id string required: A unique identifier specified by you for the customer associated with the task. Typically an identifier from your internal system. Accepts alphanumeric characters.
task_details string required: A description of the task up to 255 characters.
assignee string required: The email address of the team member assigned to the task.
due_date string required: The date when the task is due. Must be an ISO 8601-formatted date.
completed_at string optional: The date when the task was completed. Must be an ISO 8601-formatted date in the past.

opportunities array(object) optional

Array of opportunity objects to import.

customer_external_id string required: A unique identifier specified by you for the customer associated with the opportunity. Typically an identifier from your internal system. Accepts alphanumeric characters.
owner string required: The email address of the team member with a CRM Pro seat who is the primary salesperson responsible for this opportunity.
pipeline string required: The sales pipeline name. The pipeline must already exist in ChartMogul. Use one of the default sales pipelines: New Business or Renewals, or set up a new one.
pipeline_stage string required: The name of the current deal stage within the sales pipeline.
estimated_close_date string required: The date when the opportunity is expected to close. Must be an ISO 8601-formatted date.
amount_in_cents integer required: Amount in cents (or pence for GBP, etc.) of expected close value of this opportunity.
currency string required: The three-letter currency code of the currency of the expected close value, e.g. USD, EUR, or GBP. Read the full list of supported currencies.
type string optional: The opportunity type. Both recurring and arr represent recurring revenue opportunities. Use recurring when the value is expressed as MRR, and arr when it is expressed as ARR. Use one-time for opportunities expected to convert into one-time deals.
forecast_category string optional: The opportunity's grouping based on its likelihood of closing. One of five pre-defined forecast categories: pipeline, best_case, committed, lost, or won. If not provided, it is set to the default forecast category for a given pipeline stage.
win_likelihood integer optional: An integer between 0 and 100 representing the likelihood (as a percentage) that this opportunity will successfully close. If not provided, it is set to the default win likelihood for a given pipeline stage.

customer_tags array(object) optional

Array of customer tag objects to import.

customer_external_id string required: A unique identifier specified by you for the customer to add tags to. Typically an identifier from your internal system. Accepts alphanumeric characters.
tags array(string) required: An array of tags to be added to the customer.

custom_attributes array(object) optional

Array of custom attribute schema definitions. Use this to define new custom attributes before setting their values via custom_attribute_values.

key string required: The name of the custom attribute. Accepts alphanumeric characters and underscores.
type string required: The data type of the custom attribute. Can be one of String, Integer, Decimal, Timestamp, or Boolean.
associated_object string required: The type of object this custom attribute is associated with. One of customer, contact, or opportunity.

custom_attribute_values array(object) optional

Array of custom attribute value objects. Sets the value of a custom attribute on a specific customer, contact, or opportunity.

associated_object string required

The type of object to set the custom attribute value on. One of customer, contact, or opportunity.

key string required

The name of the custom attribute. Must match an existing custom attribute key for the given associated_object.

value string required

The value of the custom attribute. Must match the data type specified for this attribute.

associated_object_identifier object required

Identifies the specific object to set the custom attribute value on.

method string required: The method used to identify the object. For customer and contact, one of uuid, email, or external_id. For opportunity, only uuid is supported.
value string required: The identifier value corresponding to the chosen method.

source string optional

Optional label indicating the origin of this custom attribute value, e.g. the name of an integration or script. Not included in the response.