Import CSV into a Source

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

Imports data such as customers, contacts, plans, invoices, and more into a source from a CSV file.

curl -X POST \
  "https://api.chartmogul.com/v1/data_sources/ds_ade45e52-47a4-231a-1ed2-eb6b9e541213/uploads/" \
  -u "YOUR_API_KEY:" \
  -F "file=@./customers.csv;type=text/csv" \
  -F "type=customer" \
  -F "batch_name=march_2026_import"

{
  "id": 12345,
  "status": "queued",
  "created_at": "2026-03-19T10:00:00Z",
  "updated_at": "2026-03-19T10:00:00Z",
  "error_count": 0,
  "processed_count": 0
}

This endpoint uses multipart/form-data instead of a JSON request body, allowing a CSV file to be sent alongside accompanying parameters. The CSV file must be UTF-8 encoded and match the type you specify. For example, if type is customer, the file should contain customer data.

Path parameters

DATA_SOURCE_UUID string required: The ChartMogul UUID of the source where you want to upload data.

Form parameters

file file required: The path to the UTF-8-encoded CSV file to import. When using curl, append ;type=text/csv to the file path to set the MIME type explicitly.
type string required: The type of data contained in the CSV file: customer, contact, plan, invoice, line_item, transaction, subscription_event, manual_subscription_event, customer_note, or customers_contacts_enrichment. See Supported types for required column headers per type.
batch_name string optional: An optional name for the upload batch, useful for organizing and tracking imports.

Supported types

The type parameter determines which dataset you’re uploading. Each type maps to a specific data table in ChartMogul and expects a CSV with specific column headers.

The datasets you need and the order in which to upload them depend on your use case. Learn more.

For column descriptions and valid values, see the CSV formatting guide.

Sample files are available for most types to use as templates.

`customer`

Companies or individuals with a current, past, or potential relationship with your business. Upload customers before uploading contacts, invoices, invoice line items, transactions, subscription events, or manual subscriptions.

Column	Required?
`Name`	Required
`Email`	Optional
`Company`	Optional
`Country`	Optional
`State`	Optional
`City`	Optional
`Zip`	Optional
`External ID`	Required
`Lead created at`	Optional
`Free trial started at`	Optional
`Website URL`	Optional

See the full column reference for field descriptions, valid values, and formatting requirements.

`contact`

Individuals whose contact details you want to store in ChartMogul.

Column	Required?
`Customer External ID`	Required
`External ID`	Optional
`First Name`	Optional
`Last Name`	Optional
`Email`	Optional
`Position`	Optional
`Title`	Optional
`Phone`	Optional
`LinkedIn`	Optional
`Twitter`	Optional
`Note`	Optional
`Last Active At`	Optional

See the full column reference for field descriptions, valid values, and formatting requirements.

`plan`

Products or services you offer on a subscription basis. Upload plans before uploading invoices, invoice line items, subscription events, or manual subscriptions.

Column	Required?
`Name`	Required
`Interval count`	Required
`Interval unit`	Required
`Plan ID`	Required

See the full column reference for field descriptions, valid values, and formatting requirements.

`invoice`

Documents that record the sale of products and services to a customer and are used to collect payment. Upload invoices before uploading invoice line items or transactions.

Column	Required?
`Customer external ID`	Required
`Invoice external ID`	Required
`Invoiced date`	Required
`Due Date`	Optional
`Currency`	Required
`Status`	Optional
`Collection Method`	Optional

See the full column reference for field descriptions, valid values, and formatting requirements.

`line_item`

Individual charges within an invoice.

Column	Required?
`Invoice external ID`	Required
`External ID`	Optional
`Subscription external ID`	Conditional
`Subscription set external ID`	Optional
`Type`	Required
`Amount in cents`	Required
`Plan`	Conditional
`Service period start`	Conditional
`Service period end`	Conditional
`Quantity`	Optional
`Proration`	Required
`Proration type`	Optional
`Discount code`	Optional
`Discount amount`	Optional
`Tax amount`	Optional
`Description`	Optional
`Discount description`	Optional
`Transaction fee`	Optional
`Transaction fees currency`	Optional
`Account Code`	Optional
`Event order`	Optional
`Balance transfer`	Optional

Conditional columns (Subscription external ID, Plan, Service period start, Service period end) are required for line items with Type set to Subscription or Trial.

See the full column reference for field descriptions, valid values, and formatting requirements.

`transaction`

Payment and refund records linked to invoices.

Column	Required?
`Invoice external ID`	Required
`External ID`	Optional
`Type`	Required
`Result`	Required
`Date`	Required
`Amount in cents`	Optional
`Exclude tax on refund`	Optional
`Exclude discount on refund`	Optional
`Exclude fees on refund`	Optional
`Transaction fee`	Optional
`Transaction fees currency`	Optional
`Attached refund invoice number`	Optional

See the full column reference for field descriptions, valid values, and formatting requirements.

`subscription_event`

Events that record changes to subscriptions, such as starts, cancellations, and updates.

Column	Required?
`Customer external ID`	Required
`Subscription external ID`	Conditional
`Subscription set external ID`	Optional
`External ID`	Optional
`Event Type`	Required
`Retracted event ID`	Optional
`Date`	Required
`Effective Date`	Required
`Plan external ID`	Conditional
`Currency`	Conditional
`Amount in Cents`	Conditional
`Quantity`	Conditional
`Event Order`	Optional

Subscription external ID is not required for subscription_event_retracted. Plan external ID, Currency, Amount in Cents, and Quantity are required for start and update event types.

See the full column reference for field descriptions, valid values, and formatting requirements.

`manual_subscription_event`

Direct subscription records for accounts that don’t use invoice data. Learn more.

Column	Required?
`External ID`	Optional
`Subscription external ID`	Required
`Customer external ID`	Required
`Plan external ID`	Conditional
`Date`	Required
`Effective Date`	Required
`Event Type`	Required
`Currency`	Conditional
`Amount in Cents`	Conditional
`Quantity`	Conditional
`Report Cash Flow`	Required

Plan external ID, Currency, Amount in Cents, and Quantity are required for manual_subscription_started and manual_subscription_updated event types.

See the full column reference for field descriptions, valid values, and formatting requirements.

`customer_note`

Notes and call logs attached to a customer. Learn more.

Column	Required?
`Customer external ID`	Required
`External ID`	Optional
`Kind`	Required
`Text`	Optional
`Call Duration`	Optional
`Author Name`	Optional
`Author Email`	Optional

`customers_contacts_enrichment`

Upload customer and contact information simultaneously. Equivalent to flexible CSV import in the app.

Column headers are matched case-insensitively against a long alias list, so you can mix whatever aliases your source CRM produces. Header matching is also whitespace-insensitive, so " Customer external ID " is treated the same as "Customer external ID". Column order doesn’t matter.

Column	Required?
`Customer ID`	Required
`Organization`	Optional
`Country`	Optional
`ZIP`	Optional
`City`	Optional
`First Name`	Optional
`Last Name`	Optional
`Email`	Optional
`Phone`	Optional
`Job Title`	Optional
`Website`	Optional
`Lead Status`	Optional
`Notes`	Optional

Response

id: The unique identifier for the upload.
status: The current status of the upload (queued, processing, completed, or failed).
created_at: The date and time when the upload was created.
updated_at: The date and time when the upload was last updated.
error_count: The number of errors encountered during processing.
processed_count: The number of records successfully processed.

Sample files

Download sample CSV files to use as templates when building your import.

Download all files as a zip:

Invoice data — customers, contacts, plans, invoices, invoice line items, transactions, and subscription events
Manual subscription data — customers, contacts, plans, and manual subscriptions

Or download individual files: