Retrieve a Customer

GET https://api.chartmogul.com/v1/customers/{CUSTOMER_UUID}

Retrieves a customer object from your ChartMogul account.

curl -X GET "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012?with_overrides=true&attributes_with_history=website_url,custom.salesRep" \
     -u YOUR_API_KEY:

ChartMogul::Customer.retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012")

ChartMogul.Customer.retrieve(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012");

ChartMogul\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");

api.RetrieveCustomer("cus_de305d54-75b4-431b-adb2-eb6b9e546012")

chartmogul.Customer.retrieve(config, uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012")

{
  "id": 25647,
  "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  "external_id": "34916129",
  "external_ids": ["34916129"],
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  "name": "Example Company",
  "email": "[email protected]",
  "company": "",
  "status": "Active",
  "lead_created_at": null,
  "free_trial_started_at": null,
  "lead_status": "Qualified Lead",
  "free_subscriber_status": "Never a Free Subscriber",
  "trial_subscriber_status": "Never had Trial",
  "paid_subscriber_status": "Active Paid Subscriber",
  "customer-since": "2023-06-09T13:16:00-04:00",
  "zip": "0185128",
  "city": "Nowhereville",
  "state": "AK",
  "country": "US",
  "address": {
    "address_zip": "0185128",
    "city": "Nowhereville",
    "state": "Alaska",
    "country": "US"
  },
  "attributes": {
    "tags": ["engage", "unit loss", "discountable"],
    "custom": {
      "CAC": 213,
      "utmCampaign": "social media 1",
      "convertedAt": "2023-09-08 00:00:00",
      "pro": false,
      "salesRep": "Gabi"
    },
    "stripe": { "uid": 7, "coupon": true }
  },
  "mrr": 3000,
  "arr": 36000,
  "billing-system-type": "Stripe",
  "billing-system-url": "https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
  "chartmogul-url": "https://app.chartmogul.com/#/customers/25647-Example_Company",
  "currency": "USD",
  "currency-sign": "$",
  "owner": null,
  "website_url": "https://example.com",
  "last_seen": "2026-01-01T16:58:58.000Z",
  "overrides": {
    "website_url": true,
    "attributes": { "custom": { "salesRep": true } }
  },
  "historical_values": {
    "website_url": [
      { "value": "https://example.com", "update_performed_at": "2026-07-15T09:14:31Z", "update_performed_by": "Sylvia Kingsley", "initial": false },
      { "value": null, "update_performed_at": null, "update_performed_by": null, "initial": true }
    ],
    "attributes": {
      "custom": {
        "salesRep": [
          { "value": "Gabi", "update_performed_at": "2026-06-02T11:20:05Z", "update_performed_by": "API", "initial": false },
          { "value": null, "update_performed_at": null, "update_performed_by": null, "initial": true }
        ]
      }
    }
  }
}

#<ChartMogul::Customer:0x007faf03b02d68 
  @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]",
  @company="",
  @status="Active",
  @lead_created_at=null,
  @free_trial_started_at=null,
  @customer_since=2023-06-09 13:16:00 -04:00:00,
  @zip="0185128",
  @city="Nowhereville",
  @state="AK",
  @country="US",
  @address={
    :address_zip=>"0185128",
    :city=>"Nowhereville",
    :state=>"Alaska", 
    :country=>"US",
  },
  @attributes={
    :tags=>["engage", "unit loss", "discountable"], 
    :custom=>{
      :CAC=>213,
      :utmCampaign=>"social media 1",
      :convertedAt=>"2023-09-08 00:00:00",
      :pro=>false,
      :salesRep=>"Gabi",
    },
    :stripe=>{:uid=>7, :coupon=>true}
  },
  @mrr=3000, 
  @arr=36000, 
  @billing_system_type="Stripe", 
  @billing_system_url="https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb", 
  @chartmogul_url="https://app.chartmogul.com/#customers/25647-Example_Company", 
  @currency="USD", 
  @currency_sign="$",
  @owner=nil,
  @website_url="https://example.com"
>

{
  id: 25647,
  uuid: "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  external_id: "34916129",
  external_ids: ["34916129"],
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  data_source_uuids: ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  name: "Example Company",
  email: "[email protected]",
  company: "",
  status: "Active",
  lead_created_at: null,
  free_trial_started_at: null,
  "customer-since": "2023-06-09T13:16:00-04:00",
  zip: "0185128",
  city: "Nowhereville",
  state: "AK",
  country: "US",
  address: {
    address_zip: "0185128",
    city: "Nowhereville",
    state: "Alaska",
    country: "US"
  },
  attributes: {
    tags: ["engage", "unit loss", "discountable"],
    custom: {
      CAC: 213,
      utmCampaign: "social media 1",
      convertedAt: "2023-09-08 00:00:00",
      pro: false,
      salesRep: "Gabi"
    },
    stripe: { uid: 7, coupon: true }
  },
  mrr: 3000,
  arr: 36000,
  "billing-system-type": "Stripe",
  "billing-system-url": "https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
  "chartmogul-url": "https://app.chartmogul.com/#/customers/25647-Example_Company",
  currency: "USD",
  "currency-sign": "$",
  owner: null,
  website_url: "https://example.com"
}

ChartMogul\Customer::__set_state(array(
  "id" => 25647,
  "uuid" => "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  "external_id" => "34916129",
  "external_ids" => array(
    0 => "34916129",
  ),
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids" => array(
    0 => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ),
  "name" => "Example Company",
  "email" => "[email protected]",
  "company" => "",
  "status" => "Active",
  "lead_created_at" => null,
  "free_trial_started_at" => null,
  "customer_since" => "2023-06-09T13:16:00-04:00",
  "zip" => "0185128",
  "state" => "AK",
  "country" => "US",
  "city" => "Nowhereville",
  "address" => array(
    "address_zip" => "0185128",
    "city" => "Nowhereville",
    "state" => "Alaska",
    "country" => "US"
  ),
  "attributes" => array(
    "tags" => array(
      0 => "engage",
      1 => "unit loss",
      2 => "discountable",
    ),
    "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,
    ),
  ),
  "mrr" => 3000,
  "arr" => 36000,
  "billing_system_type" => "Stripe",
  "billing_system_url" => "https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
  "chartmogul_url" => "https://app.chartmogul.com/#customers/25647-Example_Company",
  "currency" => "USD",
  "currency_sign" => "$",
  "owner" => null,
  "website_url" => "https://example.com",
));

(*chartmogul.Customer)(0xc04207e6e0)({
  ID: (uint32) 25647,
  UUID: (string) (len=40) "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  ExternalID: (string) (len=8) "34916129",
  ExternalIDs: ([]string) {
    (len=8) "34916129"
  },
  DataSourceUUID: (string) (len=39) "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
  DataSourceUUIDs: ([]string) {
    (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
  },
  Name: (string) (len=10) "Adam Smith",
  Email: (string) (len=15) "[email protected]",
  Company: (string) "",
  Status: (string) (len=6) "Active",
  LeadCreatedAt: (string) "",
  FreeTrialStartedAt: (string) "",
  CustomerSince: (string) (len=25) "2023-06-09T13:16:00-04:00",
  Zip: (string) "",
  City: (string) (len=8) "New York",
  State: (string) "",
  Country: (string) (len=2) "US",
  Address: (*chartmogul.Address)(0xc042009800)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) "",
    Country: (string) (len=13) "United States",
  }),
  Attributes: (*chartmogul.Attributes)(0xc042132b10)({
    Tags: ([]string) {
      (len=6) "engage",
      (len=9) "unit loss",
      (len=12) "discountable", 
    },
    Custom: (map[string]interface {}) (len=2) {
      (string) (len=3) "CAC": (float64) 213,
      (string) (len=11) "utmCampaign": (string) (len=14) "social media 1",
      (string) (len=11) "convertedAt": (string) (len=19) "2023-09-08 00:00:00",
      (string) (len=3) "pro": (bool) false,
      (string) (len=8) "salesRep": (string) (len=4) "Gabi",
    },
    Stripe: (map[string]interface {}) (len=2) {
      (string) (len=3) "UID": (uint64) 0,
      (string) (len=6) "Coupon": (bool) false,
    },
    Clearbit: (map[string]interface {}) {}, // deprecated
  }),
  Mrr: (float64) 4100,
  Arr: (float64) 49200,
  BillingSystemType: (string) (len=10) "Custom",
  BillingSystemURL: (string) "",
  ChartmogulURL: (string) (len=54) "https://app.chartmogul.com/#customers/25647-Example_Company",
  Currency: (string) (len=3) "USD",
  CurrencySign: (string) (len=1) "$",
  Owner: (string) "",
  WebsiteUrl: (string) (len=19) "https://example.com",
  Errors: (chartmogul.Errors) chartmogul: map[],
})

<Customer{
  id=25647, 
  uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012", 
  external_id="cus_0001", 
  external_ids=["cus_0001"], 
  data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
  data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"], 
  name="Adam Smith", 
  email="[email protected]",
  company="", 
  status="Active", 
  free_trial_started_at=None, 
  lead_created_at=None, 
  customer_since=datetime.datetime(2023, 6, 9, 13, 16), 
  zip=None,
  city="New York", 
  state=None, 
  country="US", 
  address=<Address{
    address_zip=None,
    city="New York",
    state=None,
    country="United States", 
  }>,
  attributes=<Attributes{
    tags=["engage", "unit loss", "discountable"],
    custom: {
      CAC: 213,
      utmCampaign: "social media 1",
      convertedAt: "2023-09-08 00:00:00",
      pro: False,
      salesRep: "Gabi",
    },
    stripe={uid: 7, coupon: True},
  }>,
  mrr=4100.0, 
  arr=49200.0, 
  billing_system_type="Custom", 
  billing_system_url="https://dashboard.stripe.com/customers/cus_4Z2ZpyJFuQ0XMb",
  chartmogul_url="https://app.chartmogul.com/#customers/25647-Example_Company", 
  currency="USD", 
  currency_sign="$", 
  owner=None,
  website_url="https://example.com",
}>

Path parameters

customer_uuid string required: The ChartMogul UUID of the customer you are retrieving.

Query parameters

with_overrides boolean optional default: false: When true, the response includes an overrides object flagging the customer’s currently overridden fields.
attributes_with_history string optional: A comma-separated list of attribute names. The response then includes a historical_values object with the edit history of each listed attribute. Standard fields are named as in this reference — company, owner, website_url, lead_created_at, free_trial_started_at, status, and address, which covers city, state, country, and zip as one attribute; custom attributes go by their namespaced name, e.g. custom.channel. Unknown names fail the request with a 422.

Response

The response object contains the following data:

id

The internal ChartMogul ID for the customer object.

uuid

The ChartMogul UUID for the customer.

external_id

The unique external identifier for the customer. It usually originates from a billing system outside of ChartMogul.

external_ids

An array containing the unique external identifiers of both the customer itself as well as all customer records that have been merged into it.

data_source_uuid

The ChartMogul UUID for the source the customer is from.

data_source_uuids

An array containing the ChartMogul UUIDs for the source the customer is from as well as the UUIDs for the sources of customers merged into it.

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

The customer’s company name.

status

A combined field reflecting either the customer’s lead status or subscription status. One of New Lead, Working Lead, Qualified Lead, Unqualified Lead, Active, Past Due, or Cancelled.

lead_created_at

The time the customer was established as lead. This is given as ISO 8601-formatted string, except in the Ruby and Python libraries (where they are given as datetime objects).

free_trial_started_at

The time at which the customer started a free trial. This is given as ISO 8601-formatted string, except in the Ruby and Python libraries (where they are given as datetime objects).

lead_status

The customer’s lead status. One of New Lead, Working Lead, Qualified Lead, or Unqualified Lead.

free_subscriber_status

The customer’s free subscriber status. One of Active Free Subscriber, Cancelled Free Subscriber, or Never a Free Subscriber.

paid_subscriber_status

The customer’s paid subscriber status. One of Active Paid Subscriber, Cancelled Subscriber, Past-Due Subscriber, or Never a Paid Subscriber.

trial_subscriber_status

The customer’s trial status. One of Active Free Trial, Active Paid Trial, Expired Free Trial, Expired Paid Trial, or Never had Trial.

customer-since

The time at which the customer started their first subscription. This is given as ISO 8601-formatted string, except in the Ruby and Python libraries (where they are given as datetime objects).

zip

The zip code from the customer’s address, as a string.

city

The city from the customer’s address.

state

The US state where the customer is located—the US state code as per the ISO-3166 alpha-2 standard. For example, US-CA or US-NY.

country

The country from customer’s address, as ISO 3166-1 alpha-2-formatted string.

address

An object containing the customer’s address.

address_zip: The zip code from the customer’s address.
city: The full name for the city from the customer’s address.
state: The full name for the state from the customer’s address.
country: The full name for the country from the customer’s address.

attributes

An object containing tags, custom attributes, and Stripe metadata.

tags: An array of tags on the customer.
custom: An object containing the custom attributes on the custom, as key-value pairs.
stripe: An object with the customer’s Stripe metadata. An empty object if the customer is not a Stripe customer.

mrr

The current monthly recurring revenue for this customer, expressed in your account currency, as an integer number of cents. For the actual amount, divide by 100.

arr

The current annual run rate for this customer, expressed in your account currency, as an integer number of cents. For the actual amount, divide by 100.

billing-system-type

The billing system the customer was imported from. For example Stripe, Recurly, Custom, etc.

billing-system-url

A URL for this customer linking to the customer record in your billing system, if available.

chartmogul-url

A URL for this customer linking to the customer record in ChartMogul.

currency

Your account currency. This is used to express MRR and ARR in.

currency-sign

The symbol(s) used to represent the currency, e.g. $ or €.

owner

The team member responsible for the customer relationship.

website_url

The URL of the customer’s website.

last_seen

A timestamp of when the customer was last active, based on the most recent activity across all associated contacts, in the ISO 8601 format. Currently unavailable for our client libraries.

overrides

An object flagging the customer’s currently overridden fields with true, custom attributes nested under attributes, e.g. {"company": true, "attributes": {"custom": {"channel": true}}}. Overridden values are protected from being overwritten by updates from your billing system. Fields are overridden from the ChartMogul UI or with the overrides parameter of the customer write endpoints. Only included when with_overrides is true.

historical_values

Up to the 10 most recent edit history entries per attribute named in attributes_with_history, newest first, custom attributes nested under attributes. Each entry carries the attribute’s value at that point (in the field’s public representation, e.g. the owner’s email), update_performed_at, update_performed_by (a team member’s name, an integration’s name, or API), and initial — true on the entry holding the attribute’s initial value, whose update_performed_at and update_performed_by are null. Values that an override blocked also appear: the attempt is recorded in the edit history even though it was never applied, and removing the override reverts to the latest recorded value. Only included when attributes_with_history is given.