API Data Provider - Online Help

Connecting to ChartMogul

Using API Key Authentication

ChartMogul uses API Key authentication. To obtain an API Key:

  1. Log in to your ChartMogul account at https://app.chartmogul.com
  2. Navigate to Settings > API Keys
  3. Click "Add API Key" to generate a new key
  4. Copy the generated API Key (it will only be shown once)

After obtaining your API Key, set the following connection properties:

  • AuthScheme: Set this to APIKey.
  • APIKey: Set this to your ChartMogul API Key.

Example Connection String

Profile=C:\profiles\ChartMogul.apip;AuthScheme=APIKey;APIKey=your_api_key;

Connecting to ChartMogul

Once the authentication is configured, you can connect to ChartMogul and read, insert, update, and delete data across the available tables such as Customers, Invoices, Plans, Opportunities, and Tasks.

Available Tables

The ChartMogul API Profile provides access to the following tables:

  • Account: Retrieve account or company information including currency and timezone settings
  • Activities: Retrieve revenue activities across all customers with MRR movement tracking
  • ActivitiesExport: Retrieve export status for bulk activity downloads (requires Id)
  • BulkImportStatus: Retrieve status of bulk data import operations (requires DataSourceUuid and ImportId)
  • Contacts: Create, update, and delete contact persons associated with customer accounts
  • CustomerActivities: Retrieve revenue activities for a specific customer (requires CustomerUuid)
  • CustomerAttributes: Add and update customer attributes including tags and custom fields (requires CustomerUuid)
  • CustomerInvoices: Retrieve and create invoices for a specific customer (requires CustomerUuid)
  • CustomerNotes: Create, update, and delete notes and call logs associated with customers
  • CustomerSearch: Search for customers by email address (requires Email)
  • Customers: Create, update, and delete customer records with subscription and revenue data
  • DataSources: Create and delete data source connections to billing systems
  • InvoiceLineItems: Create, update, and delete individual line items from invoices with pricing details
  • Invoices: Create, update, and delete invoice records with line items and transaction details
  • MetricsAll: Retrieve combined metrics including MRR, ARR, ARPA, ASP, LTV, and churn rates (requires StartDate and EndDate)
  • MetricsARPA: Retrieve Average Revenue Per Account metrics over time (requires StartDate and EndDate)
  • MetricsARR: Retrieve Annual Run Rate metrics over time (requires StartDate and EndDate)
  • MetricsASP: Retrieve Average Sale Price metrics over time (requires StartDate and EndDate)
  • MetricsChurnRate: Retrieve customer churn rate metrics over time (requires StartDate and EndDate)
  • MetricsCustomerCount: Retrieve active customer count metrics over time (requires StartDate and EndDate)
  • MetricsLTV: Retrieve Customer Lifetime Value metrics over time (requires StartDate and EndDate)
  • MetricsMRR: Retrieve Monthly Recurring Revenue metrics over time (requires StartDate and EndDate)
  • MetricsMRRChurnRate: Retrieve MRR churn rate metrics over time (requires StartDate and EndDate)
  • Opportunities: Create, update, and delete sales opportunities with deal tracking and forecasting
  • PlanGroupPlans: Retrieve plans within a specific plan group (requires PlanGroupUuid)
  • PlanGroups: Create, update, and delete collections of related billing plans
  • Plans: Create, update, and delete billing plans with pricing and interval configuration
  • SubscriptionEvents: Create, update, and delete subscription lifecycle events with revenue impact tracking
  • Subscriptions: Retrieve customer subscriptions with billing and revenue details (requires CustomerUuid)
  • Tasks: Create, update, and delete customer-related tasks with assignment and due date tracking
  • Transactions: Create, update, and delete payment and refund transactions with fees

Important Notes

  • The ChartMogul API uses cursor-based pagination for most endpoints to efficiently handle large datasets.
  • Metrics endpoints require StartDate and EndDate parameters to retrieve time-series data.
  • Some tables like Subscriptions and PlanGroupPlans require parent identifiers (e.g., CustomerUuid, PlanGroupUuid) for querying.
  • Date fields use ISO-8601 format, and revenue amounts are represented in cents.
  • Rate limiting applies - refer to ChartMogul API documentation for current limits.
  • The CustomerAttributes table uses different formats for the Custom column depending on the operation. For INSERT, Custom must be an array of objects with type, key, and value fields (e.g. [{"type":"String","key":"plan","value":"Gold"}]). For UPDATE, Custom must be a simple key-value object (e.g. {"plan":"Gold"}). Supplying the wrong format will result in an API error.
  • For the CustomerAttributes table, INSERT requires exactly one of Tags or Custom - specifying both or neither will result in an error. Tags cannot be updated; use INSERT to add tags.

API Documentation

For more information about the ChartMogul API, see the official ChartMogul API documentation.

Usage Examples

Account: 

SELECT * FROM Account

Activities: 

SELECT * FROM Activities

ActivitiesExport: 

SELECT * FROM ActivitiesExport WHERE Id = 'export_123abc'

BulkImportStatus: 

SELECT * FROM BulkImportStatus WHERE DataSourceUuid = 'ds_uuid123' AND ImportId = 'import_456'

Contacts: 

SELECT * FROM Contacts

INSERT INTO Contacts (CustomerUuid, DataSourceUuid, FirstName, LastName, Email, Title, Phone, LinkedIn, Twitter, Notes, Position, Custom) VALUES ('cus_abc123', 'ds_uuid123', 'Jane', 'Smith', '[email protected]', 'VP of Sales', '+1-555-0100', 'https://linkedin.com/in/janesmith', '@janesmith', 'Key contact for account', 1, '[{"key":"tier","value":"gold"}]')

UPDATE Contacts SET Email = '[email protected]', FirstName = 'Jane', LastName = 'Smith', Title = 'VP of Sales', Phone = '+1-555-0100', LinkedIn = 'https://linkedin.com/in/janesmith', Twitter = '@janesmith', Notes = 'Updated contact notes', Position = 1, Custom = '[{"key":"tier","value":"gold"}]' WHERE Uuid = 'con_abc123'

DELETE FROM Contacts WHERE Uuid = 'con_abc123'

CustomerActivities: 

SELECT * FROM CustomerActivities WHERE CustomerUuid = 'cus_abc123'

CustomerAttributes: 

SELECT * FROM CustomerAttributes WHERE CustomerUuid = 'cus_abc123'

INSERT INTO CustomerAttributes (CustomerUuid, Tags) VALUES ('cus_abc123', '["enterprise","annual"]')

UPDATE CustomerAttributes SET Custom = '{"plan_type":"enterprise"}' WHERE CustomerUuid = 'cus_abc123'

CustomerInvoices: 

SELECT * FROM CustomerInvoices WHERE CustomerUuid = 'cus_abc123'

INSERT INTO CustomerInvoices (CustomerUuid, ExternalId, InvoiceDate, Currency, LineItems, DueDate, Transactions) VALUES ('cus_abc123', 'inv-ext-001', '2024-01-15T00:00:00Z', 'USD', '[{"type":"subscription","amount_in_cents":9900}]', '2024-02-15T00:00:00Z', '[{"type":"payment","result":"successful","date":"2024-01-15T00:00:00Z"}]')

CustomerNotes: 

SELECT * FROM CustomerNotes

INSERT INTO CustomerNotes (CustomerUuid, Type, Text, CallDuration, Author) VALUES ('cus_abc123', 'note', 'Discussed renewal terms and pricing.', 0, '[email protected]')

UPDATE CustomerNotes SET Text = 'Updated renewal discussion notes.', CallDuration = 0 WHERE Uuid = 'note_abc123'

DELETE FROM CustomerNotes WHERE Uuid = 'note_abc123'

CustomerSearch: 

SELECT * FROM CustomerSearch WHERE Email = '[email protected]'

Customers: 

SELECT * FROM Customers

INSERT INTO Customers (DataSourceUuid, ExternalId, Name, Email, Company, Status, City, Country, State, Zip, WebsiteUrl, Owner, FreeTrialStartedAt, LeadCreatedAt, Attributes) VALUES ('ds_uuid123', 'cust-ext-001', 'Acme Corp', '[email protected]', 'Acme Corp', 'Active', 'New York', 'US', 'NY', '10001', 'https://acme.com', '[email protected]', '2024-01-01T00:00:00Z', '2024-01-01T00:00:00Z', '{"tags":["enterprise"],"custom":[]}')

UPDATE Customers SET Name = 'Acme Corporation', Email = '[email protected]', Company = 'Acme Corporation', Status = 'Active', City = 'New York', Country = 'US', State = 'NY', Zip = '10001', WebsiteUrl = 'https://acme.com', Owner = '[email protected]', FreeTrialStartedAt = '2024-01-01T00:00:00Z', LeadCreatedAt = '2024-01-01T00:00:00Z', Attributes = '{"tags":["enterprise"],"custom":[]}' WHERE Uuid = 'cus_abc123'

DELETE FROM Customers WHERE Uuid = 'cus_abc123'

DataSources: 

SELECT * FROM DataSources

INSERT INTO DataSources (Name) VALUES ('My Custom Billing System')

DELETE FROM DataSources WHERE Uuid = 'ds_uuid123'

InvoiceLineItems: 

SELECT * FROM InvoiceLineItems WHERE Uuid = 'li_abc123'

INSERT INTO InvoiceLineItems (InvoiceUuid, Type, AmountInCents, PlanUuid, ProrationType, ServicePeriodStart, ServicePeriodEnd, AccountCode, IsBalanceTransfer, DiscountAmountInCents, DiscountCode, ExternalId, PlanExternalId, IsProrated, Quantity, SubscriptionExternalId, SubscriptionSetExternalId, TaxAmountInCents, TransactionFeesInCents) VALUES ('inv_abc123', 'subscription', 9900, 'pl_abc123', 'full', '2024-01-01T00:00:00Z', '2024-01-31T00:00:00Z', 'ACC-001', false, 0, 'PROMO10', 'li-ext-001', 'plan-pro-monthly', false, 1, 'sub-ext-001', 'sub-set-ext-001', 0, 0)

UPDATE InvoiceLineItems SET Type = 'subscription', AmountInCents = 9900, PlanUuid = 'pl_abc123', ProrationType = 'full', ServicePeriodStart = '2024-01-01T00:00:00Z', ServicePeriodEnd = '2024-01-31T00:00:00Z', DiscountAmountInCents = 0, DiscountCode = 'PROMO10', ExternalId = 'li-ext-001', IsProrated = false, Quantity = 1, SubscriptionExternalId = 'sub-ext-001', TaxAmountInCents = 0, TransactionFeesInCents = 0 WHERE Uuid = 'li_abc123'

DELETE FROM InvoiceLineItems WHERE Uuid = 'li_abc123'

Invoices: 

SELECT * FROM Invoices

INSERT INTO Invoices (CustomerUuid, ExternalId, InvoiceDate, Currency, LineItems, DueDate, Transactions) VALUES ('cus_abc123', 'inv-ext-001', '2024-01-15T00:00:00Z', 'USD', '[{"type":"subscription","amount_in_cents":9900}]', '2024-02-15T00:00:00Z', '[{"type":"payment","result":"successful","date":"2024-01-15T00:00:00Z"}]')

UPDATE Invoices SET InvoiceDate = '2024-02-01T00:00:00Z', Currency = 'USD', DueDate = '2024-02-15T00:00:00Z', CollectionMethod = 'automatic' WHERE Uuid = 'inv_abc123'

DELETE FROM Invoices WHERE Uuid = 'inv_abc123'

MetricsAll: 

SELECT * FROM MetricsAll WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsARPA: 

SELECT * FROM MetricsARPA WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsARR: 

SELECT * FROM MetricsARR WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsASP: 

SELECT * FROM MetricsASP WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsChurnRate: 

SELECT * FROM MetricsChurnRate WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsCustomerCount: 

SELECT * FROM MetricsCustomerCount WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsLTV: 

SELECT * FROM MetricsLTV WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsMRR: 

SELECT * FROM MetricsMRR WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

MetricsMRRChurnRate: 

SELECT * FROM MetricsMRRChurnRate WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

Opportunities: 

SELECT * FROM Opportunities

INSERT INTO Opportunities (CustomerUuid, Owner, Pipeline, PipelineStage, EstimatedCloseDate, AmountInCents, Currency, ForecastCategory, Type, WinLikelihood, Custom) VALUES ('cus_abc123', '[email protected]', 'New Business', 'Qualification', '2024-06-30', 500000, 'USD', 'best_case', 'recurring', 70, '[{"key":"deal_source","value":"inbound"}]')

UPDATE Opportunities SET Owner = '[email protected]', Pipeline = 'New Business', PipelineStage = 'Proposal', EstimatedCloseDate = '2024-07-31', AmountInCents = 600000, Currency = 'USD', ForecastCategory = 'committed', Type = 'recurring', WinLikelihood = 85, Custom = '[{"key":"deal_source","value":"inbound"}]' WHERE Uuid = 'op_abc123'

DELETE FROM Opportunities WHERE Uuid = 'op_abc123'

PlanGroupPlans: 

SELECT * FROM PlanGroupPlans WHERE PlanGroupUuid = 'plg_abc123'

PlanGroups: 

SELECT * FROM PlanGroups

INSERT INTO PlanGroups (Name, Plans) VALUES ('Professional Plans', '["pl_abc123","pl_def456"]')

UPDATE PlanGroups SET Name = 'Professional Plans Updated', Plans = '["pl_abc123","pl_def456","pl_ghi789"]' WHERE Uuid = 'plg_abc123'

DELETE FROM PlanGroups WHERE Uuid = 'plg_abc123'

Plans: 

SELECT * FROM Plans

INSERT INTO Plans (DataSourceUuid, Name, IntervalCount, IntervalUnit, ExternalId) VALUES ('ds_uuid123', 'Professional Monthly', 1, 'month', 'plan-pro-monthly')

UPDATE Plans SET Name = 'Professional Monthly', IntervalCount = 1, IntervalUnit = 'month' WHERE Uuid = 'pl_abc123'

DELETE FROM Plans WHERE Uuid = 'pl_abc123'

SubscriptionEvents: 

SELECT * FROM SubscriptionEvents

INSERT INTO SubscriptionEvents (DataSourceUuid, CustomerExternalId, EventType, PlanExternalId, SubscriptionExternalId, EffectiveDate, EventDate, AmountInCents, Currency, Quantity, ExternalId, EventOrder, RetractedEventId, SubscriptionSetExternalId, TaxAmountInCents) VALUES ('ds_uuid123', 'cust-ext-001', 'subscription_start', 'plan-pro-monthly', 'sub-ext-001', '2024-01-01T00:00:00.000Z', '2024-01-01T00:00:00.000Z', 9900, 'USD', 1, 'evt-ext-001', 1, 'evt-prior-001', 'sub-set-ext-001', 0)

UPDATE SubscriptionEvents SET Id = 12345, ExternalId = 'evt-ext-001', EffectiveDate = '2024-02-01T00:00:00.000Z', EventDate = '2024-02-01T00:00:00.000Z', AmountInCents = 9900, Currency = 'USD', EventOrder = 1, Quantity = 1, SubscriptionSetExternalId = 'sub-set-ext-001', TaxAmountInCents = 0 WHERE Id = 12345

DELETE FROM SubscriptionEvents WHERE Id = 12345

Subscriptions: 

SELECT * FROM Subscriptions WHERE CustomerUuid = 'cus_abc123'

Tasks: 

SELECT * FROM Tasks

INSERT INTO Tasks (CustomerUuid, TaskDetails, Assignee, DueDate, CompletedAt) VALUES ('cus_abc123', 'Follow up on renewal quote', '[email protected]', '2024-03-15T00:00:00.000Z', '2024-03-15T09:00:00.000Z')

UPDATE Tasks SET TaskDetails = 'Follow up on renewal and upsell', Assignee = '[email protected]', DueDate = '2024-03-20T00:00:00.000Z', CompletedAt = '2024-03-20T10:00:00.000Z' WHERE TaskUuid = 'task_abc123'

DELETE FROM Tasks WHERE TaskUuid = 'task_abc123'

Transactions: 

SELECT * FROM Transactions WHERE Uuid = 'tr_abc123'

INSERT INTO Transactions (InvoiceUuid, Type, Result, TransactionDate, AmountInCents, ExternalId, TransactionFeesCurrency, TransactionFeesInCents) VALUES ('inv_abc123', 'payment', 'successful', '2024-01-15T00:00:00Z', 9900, 'txn-ext-001', 'USD', 30)

UPDATE Transactions SET Type = 'payment', Result = 'successful', TransactionDate = '2024-01-15T00:00:00Z', AmountInCents = 9900, ExternalId = 'txn-ext-001', TransactionFeesCurrency = 'USD', TransactionFeesInCents = 30 WHERE Uuid = 'tr_abc123'

DELETE FROM Transactions WHERE Uuid = 'tr_abc123'

Connection Properties

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider.

Property Description
APIKey Your ChartMogul API Key.
AuthScheme The scheme used for authentication. Accepted entries are APIKey or None.
Allowed values are: BASIC, NONE, NTLM, OAUTH, APIKEY, OAUTH_CLIENT, OAUTH_PASSWORD

Copyright (c) 2026 CData Software, Inc. - All rights reserved.
Build 26.0.9770.0