List Customers

Returns a list of all customer objects in your ChartMogul account.

Examples
curl -X GET "https://api.chartmogul.com/v1/customers?per_page=50" \
     -u YOUR_API_KEY:
ChartMogul::Customer.all(per_page: 50)
ChartMogul.Customer.all(config, {
   per_page: 50
   });
<?php

ChartMogul\Customer::all([
    "per_page" => 50
]);
?>
api.ListCustomers(&cm.ListCustomersParams{Cursor: cm.Cursor{PerPage: 50}})
chartmogul.Customer.all(config, per_page=50)
Result Format
{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "name": "Example Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2023-06-09T13:16:00-04:00",
      "attributes": {
        "tags": ["engage", "unit loss", "discountable"],
        "stripe": {
          "uid": 7,
          "coupon": true
        }, 
        "clearbit": {},
        "custom": {
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2023-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address": {
        "address_zip": "0185128",
        "city": "Nowhereville",
        "state": "Alaska",
        "country": "US"
      },
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
      "external_ids": ["34916129"],
      "company": "",
      "country": "US",
      "state": "AK",
      "city": "Nowhereville",
      "zip": "0185128",
      "lead_created_at": null,
      "free_trial_started_at": null,
      "mrr": 3000,
      "arr": 36000,
      "billing-system-url": "https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https://app.chartmogul.com/#customers/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$"
    },
    // ...and more
  ],
  "per_page": 50, // deprecated in response, but can be used as query parameter
  "page": 1, // deprecated
  "current_page": 1, // deprecated
  "total_pages": 4, // deprecated
  "cursor": "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more": true
}
#<ChartMogul::Customers:0x007fe7e09ca7c8 
@entries=[
  #<ChartMogul::Customer:0x007fe7e09ca408 
  @id=25647, 
  @uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  @data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  @external_id="34916129",
  @external_ids=["34916129"],
  @name="Example Company", 
  @email="[email protected]", 
  @status="Active",
  @lead_created_at=null,
  @free_trial_started_at=null,
  @customer_since=2023-06-09 13:16:00 -04:00:00,
  @country="US",
  @state="AK",
  @city="Nowhereville",
  @zip="0185128",
  @attributes={
    :tags=>["engage", "unit loss", "discountable"], 
    :stripe=>{
      :uid=>7,
      :coupon=>true
    },
    :clearbit=>{},
    :custom=>{
      :CAC=> 213,
      :utmCampaign=> "social media 1",
      :convertedAt=> "2023-09-08 00:00:00",
      :pro=> false,
      :salesRep=> "Gabi"
    }
  }, 
  @address={
    :address_zip=>"0185128",
    :city=>"Nowhereville",
    :state=>"Alaska", 
    :country=>"US"
  }, 
  @mrr=3000, 
  @arr=36000, 
  @billing_system_url="https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb", 
  @chartmogul_url="https://app.chartmogul.com/#customers/25647-Example_Company", 
  @billing_system_type="Stripe", 
  @currency="USD", 
  @currency_sign="$"
  >,
  # // ...and more
], 
@per_page=50, # deprecated with version 4.0.0, but can be used as query parameter
@page=1, # deprecated with version 4.0.0
@current_page=1, # deprecated with version 4.0.0
@total_pages=3, # deprecated with version 4.0.0
@cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
@has_more=true
>
{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "name": "Example Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2023-06-09T13:16:00-04:00",
      "attributes": {
        "tags": ["engage", "unit loss", "discountable"],
        "stripe": {
          "uid": 7,
          "coupon": true
        }, 
        "clearbit": {},
        "custom": {
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2023-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address": {
        "address_zip": "0185128",
        "city": "Nowhereville",
        "state": "Alaska",
        "country": "US"
      },
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
      "external_ids": ["34916129"],
      "company": "",
      "country": "US",
      "state": "AK",
      "city": "Nowhereville",
      "zip": "0185128",
      "lead_created_at": null,
      "free_trial_started_at": null,
      "mrr": 3000,
      "arr": 36000,
      "billing-system-url": "https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https://app.chartmogul.com/#customers/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$"
    },
    // ...and more
  ],
  "per_page": 50, // deprecated with version 3.0.0, but can be used as query parameter
  "page": 1, // deprecated with version 3.0.0
  "current_page": 1, // deprecated with version 3.0.0
  "total_pages": 4, // deprecated with version 3.0.0
  "cursor": "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more": true
}
<?php
ChartMogul\Customers::__set_state(array(
    "current_page" => 1, # deprecated with version 6.0.0
    "total_pages" => 3, # deprecated with version 6.0.0
    "per_page" => 50, # deprecated with version 6.0.0, but can be used as query parameter
    "page" => 1, # deprecated with version 6.0.0
    "cursor" => "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
    "has_more" => true,
    "entries" =>
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" =>
    array (
      0 =>
      ChartMogul\Customer::__set_state(array(
         "id" => 25647,
        "uuid" => "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
        "external_id" => "34916129",
        "name" => "Example Company",
        "email" => "[email protected]",
        "status" => "Active",
        "customer_since" => "2023-06-09T13:16:00-04:00",
        "attributes" =>
        array (
          "custom" =>
          array (
            "CAC" => 213,
            "utmCampaign" => "social media 1",
            "convertedAt" => "2023-09-08 00 =>00 =>00",
            "pro" => false,
            "salesRep" => "Gabi"
          ),
          "clearbit" =>
          array (
          ),
          "stripe" =>
          array (
            "uid" => 7,
            "coupon" => true
          ),
          "tags" =>
          array (
            0 => "engage",
            1 => "unit loss",
            2 => "discountable"
          ),
        ),
        "address" =>
        array (
          "address_zip" => "0185128",
          "city" => "Nowhereville",
          "state" => "Alaska",
          "country" => "US"
        ),
        "mrr" => 3000,
        "arr" => 36000,
        "billing_system_url" => "https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
        "chartmogul_url" => "https://app.chartmogul.com/#customers/25647-Example_Company",
        "billing_system_type" => "Stripe",
        "currency" => "USD",
        "currency_sign" => "$",
        "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
        "data_source_uuids" =>
        array (
          0 => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
        ),
        "external_ids" =>
        array (
          0 => "cus_0001",
        ),
        "city" => "Nowhereville",
        "country" => "US",
        "state" => "AK",
        "zip" => "0185128",
        "lead_created_at" => null,
        "free_trial_started_at" => null,
        "company" => ""
    )),
    // ...and more
  )))
));
?>
(*chartmogul.Customers)(0xc042088b40)({
 Entries: ([]*chartmogul.Customer) (len=2) {
  (*chartmogul.Customer)(0xc0421e6160)({
    ID: (uint32) 25647,
    DataSourceUUID: (string) (len=39) "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
    DataSourceUUIDs: ([]string) {
      (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
    },
    UUID: (string) (len=40) "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
    ExternalID: (string) (len=8) "cus_0001",
    ExternalIDs: ([]string) {
      (len=8) "cus_0001"
    },
    Name: (string) (len=10) "Adam Smith",
    Email: (string) (len=14) "[email protected]",
    Status: (string) (len=6) "Active",
    CustomerSince: (string) (len=25) "2023-06-09T13:16:00-04:00",
    Attributes: (*chartmogul.Attributes)(0xc042132b10)({
      Tags: ([]string) {
      },
      Stripe: (*chartmogul.Stripe)(0xc04212f5d0)({
      UID: (uint64) 0,
      Coupon: (bool) false
      }),
      Clearbit: (*chartmogul.Clearbit)(0xc0420f8cc0)({
      }),
      Custom: (map[string]interface {}) {
      }
    }),
    Address: (*chartmogul.Address)(0xc042009800)({
      AddressZIP: (string) "",
      City: (string) (len=8) "New York",
      State: (string) "",
      Country: (string) (len=13) "United States"
    }),
    Mrr: (float64) 4100,
    Arr: (float64) 49200,
    BillingSystemURL: (string) "",
    ChartmogulURL: (string) (len=54) "https://app.chartmogul.com/#customers/25647-Example_Company",
    BillingSystemType: (string) (len=10) "Custom",
    Currency: (string) (len=3) "USD",
    CurrencySign: (string) (len=1) "$",
    Company: (string) "",
    Country: (string) (len=2) "US",
    State: (string) "",
    City: (string) (len=8) "New York",
    Zip: (string) "",
    LeadCreatedAt: (string) "",
    FreeTrialStartedAt: (string) "",
    Errors: (chartmogul.Errors) chartmogul: map[]
  }),
  // ...and more
 },
 Page: (uint32) 1, // deprecated with version v4
 PerPage: (uint32) 50, // deprecated with version v4, but can be used as query parameter
 CurrentPage: (int32) 1, // deprecated with version v4
 TotalPages: (int32) 7, // deprecated with version v4
 Cursor: (string) (len=44) "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
 HasMore: (bool) true
})
Customers(entries=[<Customer{
    address=<Address{
        address_zip=None, 
        city='New York', 
        country='United States', 
        state=None}>, 
    arr=49200.0, 
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>, 
        custom={
        }, 
        stripe=<Stripe{
        }>, 
        tags=[]}>, 
    billing_system_type='Custom', 
    billing_system_url=None, 
    chartmogul_url='https://app.chartmogul.com/#customers/25647-Example_Company', 
    city='New York', 
    company='', 
    country='US', 
    currency='USD', 
    currency_sign='$', 
    customer_since=datetime.datetime(2023, 6, 9, 13, 16), 
    data_source_uuid='ds_fef05d54-47b4-431b-aed2-eb6b9e545430', 
    data_source_uuids=['ds_fef05d54-47b4-431b-aed2-eb6b9e545430'], 
    email='[email protected]', 
    external_id='cus_0001', 
    external_ids=['cus_0001'], 
    free_trial_started_at=None, 
    id=25647, 
    lead_created_at=None, 
    mrr=4100.0, 
    name='Adam Smith', 
    state=None, 
    status='Active', 
    uuid='cus_de305d54-75b4-431b-adb2-eb6b9e546012', 
    zip=None},
    # ...and more
    ],
per_page=50, # deprecated with version 4.0.0, but can be used as query parameter
page=1, # deprecated with version 4.0.0
current_page=1, # deprecated with version 4.0.0
total_pages=7, # deprecated with version 4.0.0
cursor='AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k',
has_more=True)

In the response, entries contains an array of customer objects with the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer.
  • external_ids - An array containing the unique external identifiers of all customer records that have been merged into this customer.
  • data_source_uuid - The ChartMogul UUID of the data source of this customer.
  • data_source_uuids - An array containing the ChartMogul UUIDs of all data sources that contribute data to this customer. This is most relevant for merged customers.
  • name - The name of this customer.
  • email - This customer's email address.
  • company - This customer's company name.
  • status - The status of this customer. One of New Lead, Working Lead, Qualified Lead, Unqualified Lead, Active, Past Due, or Cancelled.
  • lead_created_at - The time at which this customer was established as a lead, as specified by you.
  • free_trial_started_at - The time at which this customer started a free trial of your product or service, as specified by you.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • country - The country from the customer's address.
  • state - The US state where the customer is located — the last two letters of the US state code as per the ISO-3166-2 standard. For example, CA or NY.
  • city - The city from the customer's address.
  • zip - The zip code from the customer's address.
  • attributes - A JSON object representing this customer's attributes containing the following data:
    • tags - An Array of tags that you have added to this customer.
    • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
    • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit. This is a legacy field. ChartMogul no longer utilizes Clearbit.
    • custom - A JSON object representing custom attributes that you have added to this customer.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code from this customer's address.
    • city - The city from this customer's address.
    • state - The state from this customer's address.
    • country - The country code from this customer's address as per the ISO-3166 alpha-2 standard.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Custom.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

The other keys represent pagination attributes:

  • cursor - A value that should be used in the next API request to fetch next page of customers. Request for the next page should be initiated only if has_more is set to true indicating that there are more customers to list.
  • has_more - One of true or false depending on whether there are more pages with results for this request.
  • per_page - DEPRECATED The number of results in this response.
  • page - DEPRECATED The page number of this response.
  • total_pages - DEPRECATEDThe total number of pages with results for this request.
  • current_page - DEPRECATEDThe page number of this response.

📘

Retrieving customers created using the API

You can use one of two filters to retrieve a list of customers created using the API.

  • use the data_source_uuid filter to retrieve customers belonging to a specific Custom data source, or
  • use the system filter and specify the value as Custom to retrieve customers belonging to all Custom data sources.
Language
Authorization
Basic
base64
: