Importing leads and trials

Importing lead and trial data into ChartMogul lets you benefit from the following Leads and Conversion charts.

Chart	Description
Leads	Charts the number of individuals or businesses who have entered your sales pipeline (and may eventually become subscribers) over time.
Free Trials	Charts the number of individuals or businesses who have started free trials over time. If your account supports trial line items, this chart is called “Trials” and includes both free and paid trials.
Trial-to-Paid Conversion Rate	Charts the percentage of customers who start a trial and subsequently start a paid subscription. If your account supports trial line items, this chart is called “Trial-to-Paid Conversions”.
Trial-to-Free-or-Paid Conversions	Charts the percentage of customers who start a trial and subsequently start a free or paid subscription. This chart is only available for accounts that support trial line items.
Pipeline Funnel Analysis	Provides an overview of your sales funnel and gives insight into how effectively your business is converting leads.
Average Sales Cycle Length	Charts the average number of days it takes for a lead to become a subscriber over time.

Do I need to set up lead tracking in ChartMogul?

ChartMogul imports lead and trial data automatically from select integrations, including Stripe, Braintree and Recurly. View the full list here. If you track leads using one of these integrations, then no additional setup is required.

If you need to set up lead and trial tracking in ChartMogul, the method you’ll use depends on how you import your customer data:

If you’ve built an integration using our ChartMogul API, follow our tutorial for tracking leads and free trials using the ChartMogul API.
If you manage lead and trial data outside of your integration, or ChartMogul does not import leads and trials from your integration, follow our tutorial for tracking leads and trials outside an integration.

Tracking leads and trials using the ChartMogul API

If you’ve built an integration using our API to import your customers into ChartMogul, modify your integration to add lead and trial data.

To track leads, include lead dates on customer records.

ChartMogul supports two methods for tracking trials:

Trial dates — Using the free_trial_started_at field on customer records.
Trial line items — Using the trial invoice line item type. This functionality was introduced on October 2, 2025 and is being gradually made available to all accounts.

Tracking leads and trials using lead and trial dates

Track leads and free trials by including two additional fields when creating customer records using the Create a Customer endpoint:

lead_created_at — Time at which this customer was established as a lead.
free_trial_started_at — Time at which this customer started a free trial of your product or service. Omit this field if you track trials using trial line items.

# Create a customer with lead_created_at and free_trial_started_at

curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "external_id": "cus_0001",
            "name": "Jellytech",
            "country": "US",
            "lead_created_at": "2025-11-01 00:00:00",
            "free_trial_started_at": "2025-11-02 00:00:00"
         }'

# Create a customer with lead_created_at and free_trial_started_at

ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Jellytech",
  country: "US",
  city: "New York",
  lead_created_at: Time.utc(2025, 10, 14),
  free_trial_started_at: Time.utc(2025, 11, 1),
)

// Create a customer with lead_created_at and free_trial_started_at

ChartMogul.Customer.create(config, {
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Jellytech",
  country: "US",
  city: "New York",
  lead_created_at: "2025-10-14",
  free_trial_started_at: "2025-11-01",
});

// Create a customer with lead_created_at and free_trial_started_at

ChartMogul\Customer::create([
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "external_id" => "cus_0001",
  "name" => "Jellytech",
  "country" => "US",
  "city" => "New York",
  "lead_created_at" => "2025-10-14",
  "free_trial_started_at" => "2025-11-01"
]);

// Create a customer with lead_created_at and free_trial_started_at

api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID:     "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:         "cus_0001",
  Name:               "Jellytech",
  Country:            "US",
  City:               "New York",
  LeadCreatedAt:      "2025-10-14",
  FreeTrialStartedAt: "2025-11-01",
})

# Create a customer with lead_created_at and free_trial_started_at

chartmogul.Customer.create(
  config,
  data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
    "name": "Jellytech",
    "country": "US",
    "city": "New York",
    "lead_created_at": "2025-10-14",
    "free_trial_started_at": "2025-11-01",
  },
)

Next, populate the lead and free trial timestamps for customers you’ve already imported into ChartMogul using the Update a Customer endpoint.

# Update a customer with lead_created_at and free_trial_started_at

curl -X PATCH "https://api.chartmogul.com/v1/customers/cus_ab223d54-75b4-431b-adb2-eb6b9e234571" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "lead_created_at": "2025-01-01 00:00:00",
            "free_trial_started_at" : "2025-06-13 15:45:13"
         }'

# Update a customer with lead_created_at and free_trial_started_at

customer = Customer.retrieve("cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

customer.lead_created_at = Time.utc(2025, 1, 1)

customer.free_trial_started_at = Time.utc(2025, 6, 13, 15, 45, 13)

customer.update!

// Update a customer with lead_created_at and free_trial_started_at

const customerUuid = "cus_ab223d54-75b4-431b-adb2-eb6b9e234571";

const data = {
  lead_created_at: "2025-01-01 00:00:00",
  free_trial_started_at: "2025-06-13 15:45:13",
};

ChartMogul.Customer.modify(config, customerUuid, data);

// Update a customer with lead_created_at and free_trial_started_at

ChartMogul\Customer::update(
  ["customer_uuid" => "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"],
  [
    "lead_created_at" => "2025-01-01T00:00:00.000Z",
    "free_trial_started_at" => "2025-06-13T15:45:13.000Z"
  ]
);

// Update a customer with lead_created_at and free_trial_started_at

api.UpdateCustomer(&cm.Customer{
  LeadCreatedAt:      "2025-01-01 00:00:00",
  FreeTrialStartedAt: "2025-06-13 15:45:13",
}, "cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

# Update a customer with lead_created_at and free_trial_started_at

chartmogul.Customer.update(
  config,
  uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  data={
    "lead_created_at": "2025-01-01 00:00:00",
    "free_trial_started_at": "2025-06-13 15:45:13",
  },
)

Once you complete the above steps, you’ve set up lead tracking and can benefit from our Leads and Conversion charts.

How can I accurately report inbound leads that start as free trials? For SaaS businesses, it’s typical to have inbound leads start as free trials. For such leads, simply set the timestamp for free_trial_started_at. If this timestamp is set, and lead_created_at is empty, then ChartMogul will automatically set lead_created_at to the same value, so both fields have the same timestamp. This will accurately report leads that start as free trials.

Set lead and free trial timestamps upon creation. We highly recommend importing leads and free trials into your ChartMogul account as soon as they are created to ensure you have the most accurate real-time measurement of your trial-to-paid conversion rate and sales cycle length.

Tracking trials using trial line items

On October 2, 2025, we introduced a trial invoice line item type as a more flexible way of creating trials. We’re gradually making the functionality available to all accounts.

The trial line item type allows you to create trials irrespective of the customer’s free_trial_started_at date.

When creating trials with this method:

Trials are linked to specific plans.
Customers can have multiple trials for different plans.
Both free and paid trials are supported, depending on the amount_in_cents value.
Trial periods are defined by service_period_start and service_period_end, independent of the customer’s free_trial_started_at date.

To create a trial line item, add an invoice using the Import Invoices endpoint. You'll need the customer’s UUID and basic invoice information such as date, currency, and external ID.

In the line-items object, include a line item of the trial type, specifying the plan, service period, amount and other details.

# Create an invoice with a trial line item

curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "invoices": [
              {
                "external_id": "inv_trial_001",
                "date": "2025-01-01 00:00:00",
                "currency": "USD",
                "due_date": "2025-01-01 00:00:00",
                "line_items": [
                  {
                    "type": "trial",
                    "amount_in_cents": 0,
                    "quantity": 1,
                    "external_id": "trial_001",
                    "subscription_external_id": "sub_trial_001",
                    "plan_uuid": "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
                    "service_period_start": "2025-01-01T00:00:00.000Z",
                    "service_period_end": "2025-01-15T00:00:00.000Z"
                  }
                ]
              }
            ]
          }'

# Create an invoice with a trial line item

invoice = ChartMogul::Invoice.new(
  external_id: "inv_trial_001",
  date: Time.utc(2025, 1, 1),
  currency: "USD",
  due_date: Time.utc(2025, 1, 1),
  line_items: [
    {
      type: "trial",
      amount_in_cents: 0,
      quantity: 1,
      external_id: "trial_001",
      subscription_external_id: "sub_trial_001",
      plan_uuid: "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
      service_period_start: "2025-01-01T00:00:00.000Z",
      service_period_end: "2025-01-15T00:00:00.000Z"
    }
  ]
)

ChartMogul::CustomerInvoices.create!(
  customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  invoices: [invoice]
)

// Create an invoice with a trial line item

const invoices = {
  invoices: [
    {
      external_id: "inv_trial_001",
      date: "2025-01-01 00:00:00",
      currency: "USD",
      due_date: "2025-01-01 00:00:00",
      line_items: [
        {
          type: "trial",
          amount_in_cents: 0,
          quantity: 1,
          external_id: "trial_001",
          subscription_external_id: "sub_trial_001",
          plan_uuid: "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
          service_period_start: "2025-01-01T00:00:00.000Z",
          service_period_end: "2025-01-15T00:00:00.000Z"
        }
      ]
    }
  ]
};

ChartMogul.Invoice.create(
  config,
  "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  invoices
);

// Create an invoice with a trial line item

$invoice = new ChartMogul\Invoice([
  "external_id" => "inv_trial_001",
  "date" => "2025-01-01 00:00:00",
  "currency" => "USD",
  "due_date" => "2025-01-01 00:00:00",
  "line_items" => [
    [
      "type" => "trial",
      "amount_in_cents" => 0,
      "quantity" => 1,
      "external_id" => "trial_001",
      "subscription_external_id" => "sub_trial_001",
      "plan_uuid" => "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
      "service_period_start" => "2025-01-01T00:00:00.000Z",
      "service_period_end" => "2025-01-15T00:00:00.000Z"
    ]
  ]
]);

ChartMogul\CustomerInvoices::create([
  "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "invoices" => [$invoice]
]);

// Create an invoice with a trial line item

api.CreateInvoices([]*cm.Invoice{
  &cm.Invoice{
    ExternalID: "inv_trial_001",
    Date:       "2025-01-01 00:00:00",
    Currency:   "USD",
    DueDate:    "2025-01-01 00:00:00",
    LineItems: []*cm.LineItem{
      &cm.LineItem{
        Type:                   "trial",
        AmountInCents:          0,
        Quantity:               1,
        ExternalID:             "trial_001",
        SubscriptionExternalID: "sub_trial_001",
        PlanUUID:               "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
        ServicePeriodStart:     "2025-01-01T00:00:00.000Z",
        ServicePeriodEnd:       "2025-01-15T00:00:00.000Z",
      },
    },
  },
}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

# Create an invoice with a trial line item

chartmogul.Invoice.create(
  config,
  uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  data={
    "invoices": [
      {
        "external_id": "inv_trial_001",
        "date": "2025-01-01 00:00:00",
        "currency": "USD",
        "due_date": "2025-01-01 00:00:00",
        "line_items": [
          {
            "type": "trial",
            "amount_in_cents": 0,
            "quantity": 1,
            "external_id": "trial_001",
            "subscription_external_id": "sub_trial_001",
            "plan_uuid": "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
            "service_period_start": "2025-01-01T00:00:00.000Z",
            "service_period_end": "2025-01-15T00:00:00.000Z"
          }
        ]
      }
    ]
  }
)

You can also use the Create a Line Item endpoint to add a trial line item to an existing invoice.

# Add a trial line item to the invoice

curl -X POST "https://api.chartmogul.com/v1/import/invoices/inv_cf35bc9c-fceb-4008-98b0-a7f89edc3191/line_items" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "type": "trial",
            "amount_in_cents": 0,
            "quantity": 1,
            "external_id": "trial_001",
            "subscription_external_id": "sub_trial_001",
            "plan_uuid": "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
            "service_period_start": "2025-01-01T00:00:00.000Z",
            "service_period_end": "2025-01-15T00:00:00.000Z"
          }'

Tracking leads and trials outside an integration

If you store lead and trial data outside of your integration (such as a database or the backend of your SaaS product), or if ChartMogul does not import leads and trials from your integration (such as PayPal), set up lead tracking and use the merge customers endpoint for accurate reporting.

Let’s imagine that your business is using its own database to track leads and manages subscriptions using Stripe. The following customer journey occurs:

You meet a representative of Jellytech at a conference, and they’re interested in your product. A lead record is created in your database on January 5, 2025.
After lead nurturing, Jellytech signs up for a free trial of your product on February 10, 2025.
Folks at Jellytech like your product and purchase a monthly subscription on February 25, 2025 using Stripe.

Note: this tutorial uses the following UUIDs:

The “Leads” custom source: ds_fef05d54-47b4-431b-aed2-eb6b9e545430
Jellytech (lead record): cus_f466e33d-ff2b-4a11-8f85-417eb02157a7
Jellytech (paying customer record): cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6

To enable lead and trial reporting for Jellytech in ChartMogul:

1. Create a custom source

First, create a custom source to track leads in ChartMogul.

Use the Create a Source endpoint:

curl -X POST "https://api.chartmogul.com/v1/data_sources" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Leads"
        }'

ChartMogul::DataSource.create!(name: "Leads")

ChartMogul.DataSource.create(config, {
  name: "Leads",
});

ChartMogul\DataSource::create([
  "name" => "Leads"
]);

api.CreateDataSource("Leads")

chartmogul.DataSource.create(config, data={"name": "Leads"})

ChartMogul creates the custom source and generates a unique UUID (data_source_uuid in the response). Make a note of this UUID for the next steps.

2. Create a customer

Next, use the Create a Customer endpoint to create the customer in ChartMogul. When a lead is imported, ChartMogul creates a customer record. For Jellytech, use the custom source you created in step 1 and create a customer record in ChartMogul on January 5, 2025.

Set the external_id for this customer record as the unique identifier from your database. For Jellytech, let’s say the unique identifier is cus_0001.

# Create a customer record for Jellytech with lead_created_at

curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "external_id": "cus_0001",
            "name": "Jellytech",
            "country": "US",
            "lead_created_at": "2025-01-05 00:00:00"
         }'

# Create a customer record for Jellytech with lead_created_at

ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Jellytech",
  country: "US",
  lead_created_at: Time.utc(2025, 1, 5),
)

// Create a customer record for Jellytech with lead_created_at

ChartMogul.Customer.create(config, {
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Jellytech",
  country: "US",
  lead_created_at: "2025-01-05",
});

// Create a customer record for Jellytech with lead_created_at

ChartMogul\Customer::create([
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "external_id" => "cus_0001",
  "name" => "Jellytech",
  "country" => "US",
  "city" => "New York",
  "lead_created_at" => "2025-01-05"
]);

// Create a customer record for Jellytech with lead_created_at

api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:     "cus_0001",
  Name:           "Jellytech",
  Country:        "US",
  LeadCreatedAt:  "2025-01-05",
})

# Create a customer record for Jellytech with lead_created_at

chartmogul.Customer.create(
  config,
  data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
    "name": "Jellytech",
    "country": "US",
    "lead_created_at": "2025-01-05",
  },
)

3. Update the customer when they start a free trial

This step is specific to the customer journey in this example. Skip this step if:

You do not want to track free trials in ChartMogul.
You do not offer free trials of your product or service.
Your only source of leads is through trials, and you set the free_trial_started_at date when creating the customer.

The previous step will have returned the full data for the newly created customer, including a new UUID. This UUID is used to refer to the customer when interfacing with the API, so we’ll need it to create a trial for Jellytech.

To do so, update the free_trial_started_at field on their customer record using the Update a Customer endpoint:

# Update the customer record with free_trial_started_at

curl -X PATCH "https://api.chartmogul.com/v1/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "free_trial_started_at" : "2025-02-10 00:00:00"
         }'

# Update the customer record with free_trial_started_at

customer = Customer.retrieve("cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

customer.free_trial_started_at = Time.utc(2025, 2, 10, 0, 0, 0)

customer.update!

// Update the customer record with free_trial_started_at

const customerUuid = "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7";

const data = {
  free_trial_started_at: "2025-02-10 00:00:00",
};

ChartMogul.Customer.modify(config, customerUuid, data);

// Update the customer record with lead_created_at and free_trial_started_at

ChartMogul\Customer::update(
  ["customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"],
  ["free_trial_started_at" => "2025-02-10T00:00:00.000Z"]
);

// Update the customer record with free_trial_started_at

api.UpdateCustomer(&cm.Customer{
  FreeTrialStartedAt: "2025-02-10 00:00:00",
}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

# Update the customer record with free_trial_started_at

chartmogul.Customer.update(
  config,
  uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  data={"free_trial_started_at": "2025-02-10 00:00:00"},
)

Or, if you have this feature enabled, create an invoice with a trial line item using the Import Invoices endpoint:

# Create an invoice with a trial line item

curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "invoices": [
              {
                "external_id": "inv_trial_001",
                "date": "2025-02-10 00:00:00",
                "currency": "USD",
                "due_date": "2025-02-10 00:00:00",
                "line_items": [
                  {
                    "type": "trial",
                    "amount_in_cents": 0,
                    "quantity": 1,
                    "external_id": "trial_001",
                    "subscription_external_id": "sub_trial_001",
                    "plan_uuid": "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
                    "service_period_start": "2025-02-10T00:00:00.000Z",
                    "service_period_end": "2025-02-25T00:00:00.000Z"
                  }
                ]
              }
            ]
          }'

# Create an invoice with a trial line item

invoice = ChartMogul::Invoice.new(
  external_id: "inv_trial_001",
  date: Time.utc(2025, 2, 10),
  currency: "USD",
  due_date: Time.utc(2025, 2, 10),
  line_items: [
    {
      type: "trial",
      amount_in_cents: 0,
      quantity: 1,
      external_id: "trial_001",
      subscription_external_id: "sub_trial_001",
      plan_uuid: "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
      service_period_start: "2025-02-10T00:00:00.000Z",
      service_period_end: "2025-02-25T00:00:00.000Z"
    }
  ]
)

ChartMogul::CustomerInvoices.create!(
  customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  invoices: [invoice]
)

// Create an invoice with a trial line item

const invoices = {
  invoices: [
    {
      external_id: "inv_trial_001",
      date: "2025-02-10 00:00:00",
      currency: "USD",
      due_date: "2025-02-10 00:00:00",
      line_items: [
        {
          type: "trial",
          amount_in_cents: 0,
          quantity: 1,
          external_id: "trial_001",
          subscription_external_id: "sub_trial_001",
          plan_uuid: "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
          service_period_start: "2025-02-10T00:00:00.000Z",
          service_period_end: "2025-02-25T00:00:00.000Z"
        }
      ]
    }
  ]
};

ChartMogul.Invoice.create(
  config,
  "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  invoices
);

// Create an invoice with a trial line item

$invoice = new ChartMogul\Invoice([
  "external_id" => "inv_trial_001",
  "date" => "2025-02-10 00:00:00",
  "currency" => "USD",
  "due_date" => "2025-02-10 00:00:00",
  "line_items" => [
    [
      "type" => "trial",
      "amount_in_cents" => 0,
      "quantity" => 1,
      "external_id" => "trial_001",
      "subscription_external_id" => "sub_trial_001",
      "plan_uuid" => "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
      "service_period_start" => "2025-02-10T00:00:00.000Z",
      "service_period_end" => "2025-02-25T00:00:00.000Z"
    ]
  ]
]);

ChartMogul\CustomerInvoices::create([
  "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "invoices" => [$invoice]
]);

// Create an invoice with a trial line item

api.CreateInvoices([]*cm.Invoice{
  &cm.Invoice{
    ExternalID: "inv_trial_001",
    Date:       "2025-02-10 00:00:00",
    Currency:   "USD",
    DueDate:    "2025-02-10 00:00:00",
    LineItems: []*cm.LineItem{
      &cm.LineItem{
        Type:                   "trial",
        AmountInCents:          0,
        Quantity:               1,
        ExternalID:             "trial_001",
        SubscriptionExternalID: "sub_trial_001",
        PlanUUID:               "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
        ServicePeriodStart:     "2025-02-10T00:00:00.000Z",
        ServicePeriodEnd:       "2025-02-25T00:00:00.000Z",
      },
    },
  },
}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

# Create an invoice with a trial line item

chartmogul.Invoice.create(
  config,
  uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  data={
    "invoices": [
      {
        "external_id": "inv_trial_001",
        "date": "2025-02-10 00:00:00",
        "currency": "USD",
        "due_date": "2025-02-10 00:00:00",
        "line_items": [
          {
            "type": "trial",
            "amount_in_cents": 0,
            "quantity": 1,
            "external_id": "trial_001",
            "subscription_external_id": "sub_trial_001",
            "plan_uuid": "pl_3eb4efb2-d101-4dce-a664-be271b0da4de",
            "service_period_start": "2025-02-10T00:00:00.000Z",
            "service_period_end": "2025-02-10T00:00:00.000Z"
          }
        ]
      }
    ]
  }
)

4. Identify the lead and paying customer records

When Jellytech pays for his monthly subscription on February 25, 2025, ChartMogul receives a webhook with this information from Stripe. ChartMogul creates a new customer record for Jellytech using the Stripe source in your ChartMogul account and classifies Jellytech as Active.

When your servers receive notification of successful payment from Stripe, use the information to identify and retrieve Jellytech’s lead record and the paying customer record from ChartMogul using the Retrieve a Customer endpoint.

To identify them, first, we’ll fetch the customer that we manually imported as a lead, through the external_id from your database:

# Identify and retrieve the lead record using the data_source_UUID and external_id

curl -X GET "https://api.chartmogul.com/v1/customers?data_source_uuid=ds_fef05d54-47b4-431b-aed2-eb6b9e545430&external_id=cus_0001" \
     -u YOUR_API_KEY:

# Identify and retrieve the lead record using the data_source_UUID and external_id

ChartMogul::Customer.all(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
)

// Identify and retrieve the lead record using the data_source_UUID and external_id

ChartMogul.Customer.all(config, {
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
});

// Identify and retrieve the lead record using the data_source_UUID and external_id

ChartMogul\Customer::all([
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "external_id" => "cus_0001"
]);

// Identify and retrieve the lead record using the data_source_UUID and external_id

api.ListCustomers(&cm.ListCustomersParams{
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:     "cus_0001",
})

# Identify and retrieve the lead record using the data_source_UUID and external_id

chartmogul.Customer.all(
  config,
  data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
  },
)

Also, we need the customer generated by the integration (Stripe, in this case) using Stripe’s external_id:

# Identify and retrieve the paying customer record using the customer ID
# returned by Stripe for Jellytech

curl -X GET "https://api.chartmogul.com/v1/customers?external_id=cus_9TSLDKbqG2iKgK" \
     -u YOUR_API_KEY:

# Identify and retrieve the paying customer record using the customer ID
# returned by Stripe for Jellytech

ChartMogul::Customer.all(external_id: "cus_9TSLDKbqG2iKgK")

// Identify and retrieve the paying customer record using the customer ID
// returned by Stripe for Jellytech

ChartMogul.Customer.all(config, {
  external_id: "cus_9TSLDKbqG2iKgK",
});

// Identify and retrieve the paying customer record using the customer ID
// returned by Stripe for Jellytech

ChartMogul\Customer::findByExternalId("cus_9TSLDKbqG2iKgK");

// Identify and retrieve the paying customer record using the customer ID
// returned by Stripe for Jellytech

api.ListCustomers(&cm.ListCustomersParams{
  ExternalID: "cus_9TSLDKbqG2iKgK",
})

# Identify and retrieve the paying customer record using the customer ID
# returned by Stripe for Jellytech

chartmogul.Customer.all(config, data={"external_id": "cus_9TSLDKbqG2iKgK"})

Customer retrieval latency. It can take ChartMogul up to ten minutes to process webhooks from integrations. Therefore, you may need to retry the customer retrieval request. We recommend building in a lookup retry every minute until successful, for about 20 minutes. If you are not able to successfully retrieve the customer within 20 minutes and can confirm that the payment has gone through successfully in the integration, please contact support.

When you retrieve the above records from the API, ChartMogul returns UUIDs for each record. We’ll use these customer UUIDs (one for the lead record and one for the paying customer record) to merge them.

5. Merge the lead and paying customer records

Now that we have the customer UUIDs of the two records for Jellytech in your ChartMogul account, use the Merge Customers endpoint to merge the lead record into the paying customer record.

# Merge the customer records using customer UUIDs

curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
     -u YOUR_API_KEY:
     -H "Content-Type: application/json"
     -d '{
            "from": {"customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"},
            "into": {"customer_uuid": "cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6"}
         }'

# Merge the customer records using customer UUIDs

from_customer = ChartMogul::Customer.retrieve("cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

into_customer = ChartMogul::Customer.retrieve("cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6")

from_customer.merge_into!(into_customer)

// Merge the customer records using customer UUIDs

ChartMogul.Customer.merge(config, {
  from: {
    customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  },
  into: {
    customer_uuid: "cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6",
  },
});

// Merge the customer records using customer UUIDs

ChartMogul\Customer::merge(
  ["customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"],
  ["customer_uuid" => "cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6"]
);

// Merge the customer records using customer UUIDs

api.MergeCustomers(&cm.MergeCustomersParams{
  From: cm.CustID{CustomerUUID: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"},
  To:   cm.CustID{CustomerUUID: "cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6"},
})

# Merge the customer records using customer UUIDs

chartmogul.Customer.merge(
  config,
  data={
    "from": {"customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"},
    "into": {"customer_uuid": "cus_ba1ca03c-9d09-11e5-b921-4318215bcbf6"},
  },
)

Additional data for merged customers in an invoice. When an invoice is sent for a customer that has been merged, the invoice object is required to contain customer_external_id and data_source_uuid. These fields determine which customer of the merged records receives invoice data. For more information, see the Merge Customers endpoint.

Next steps

Head over to your ChartMogul account and make use of Leads and Conversion charts.

Add contacts to your customers using the create a contact endpoint.

Make trial-to-paid conversion rates more meaningful with cohorts. Learn more on our help center.