List Customers

GET https://api.chartmogul.com/v1/customers

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

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 });

ChartMogul\Customer::all(["per_page" => 50]);

api.ListCustomers(&cm.ListCustomersParams{Cursor: cm.Cursor{PerPage: 50}})

chartmogul.Customer.all(config, per_page=50)

{
  "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
        },
        "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 a 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
        },
        :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
        },
        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 a 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
}

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"
          ),
          "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=16) "[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{
        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
)

Query parameters

data_source_uuid string: The ChartMogul UUID of the data source with which you want to filter this customer list.
external_id string: A unique external identifier of the customer that you want to retrieve.
status string: The current status of the customers you want to retrieve. For leads, use one of New_Lead, Working_Lead, Qualified_Lead or Unqualified_Lead. For customers, use Active, Past_Due or Cancelled.
system string: The billing system that the customers belong to. For example, Stripe, Recurly or Custom. Returns all customers that have billing data from the specified system. This parameter is case-sensitive.
cursor string: A value that fetches the next page of Customers. To fetch the next page of Customers, set cursor to the value received in the previous page response.
per_page int32 default: 200: A limit on number of customers to return per page. The default and maximum value is 200.
page int32 default: 1 deprecated: The page number for pagination of results.

Response

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 deprecated

The customer's name. This parameter is getting deprecated. Instead, use the first_name and last_name of the contact object when importing data into ChartMogul.

email deprecated

The customer's email address. This parameter is getting deprecated. Instead, use the email of the contact object when importing data into ChartMogul.

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.
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 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 deprecated: The total number of pages with results for this request.
current_page deprecated: The 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.