Update a Customer

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

Updates certain modifiable attributes of a customer object in your ChartMogul account.

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": "2023-01-01 00:00:00",
            "free_trial_started_at": "2023-06-13 15:45:13",
            "city": "San Francisco",
            "country": "US",
            "state": "US-CA",
            "owner": "[email protected]",
            "attributes": {
              "tags": [ "high-value" ],
              "custom": {
                "CAC": 25,
                "channel": { "value": "Twitter", "source": "integration2" }
              }
            },
            "primary_contact":{
              "first_name": "Anna",
              "last_name": "Gardner",
              "email": "[email protected]",
              "title": "CFO",
              "phone": "+123456789",
              "linked_in": "https://linkedin.com/example",
              "twitter": "https://twitter.com/example",
              "notes": "Heading\nBody\nFooter"
            },
            "website_url": "https://example.com"
        }'

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

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

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

customer.city = "San Francisco"

customer.country = "US"

customer.state = "US-CA"

customer.attributes[:tags] = ["high-value"]

customer.attributes[:custom] = {
  "CAC": 25,
  "channel": {
    "value": "Twitter",
    "source": "integration2",
  },
}

customer.website_url = "https://example.com"

customer.update!

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

const data = {
  lead_created_at: "2023-01-01 00:00:00",
  free_trial_started_at: "2023-06-13 15:45:13",
  city: "San Francisco",
  country: "US",
  state: "US-CA",
  attributes: {
    tags: ["high-value"],
    custom: {
      CAC: 25,
      channel: { value: "Twitter", source: "integration2" },
    },
    website_url: "https://example.com",
  },
};

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

ChartMogul\Customer::update(
  ["customer_uuid" => "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"],
  [
    "lead_created_at" => "2023-01-01 00:00:00",
    "free_trial_started_at" => "2023-06-13 15:45:13",
    "city" => "San Francisco",
    "country" => "US",
    "state" => "US-CA",
    "attributes" => [
      "tags" => ["high-value"],
      "custom" => [
        "CAC" => 25,
        "channel" => ["value" => "Twitter", "source" => "integration2"]
      ]
    ],
    "website_url" => "https://example.com"
  ]
);

api.UpdateCustomer(&cm.Customer{
  LeadCreatedAt:      "2023-01-01 00:00:00",
  FreeTrialStartedAt: "2023-06-13 15:45:13",
  City:               "San Francisco",
  Country:            "US",
  State:              "US-CA",
  Attributes: &cm.Attributes{
      Tags: []string{"high-value"},
      Custom: map[string]interface{}{
          "CAC": 25,
          "channel": cm.AttributeWithSource{
              Value: "Twitter",
              Source: "integration2",
          },
      },
  WebsiteUrl:         "https://example.com",
  }
}, "cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

chartmogul.Customer.modify(
  config,
  uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  data={
    "lead_created_at": "2023-01-01 00:00:00",
    "free_trial_started_at": "2023-06-13 15:45:13",
    "city": "San Francisco",
    "country": "US",
    "state": "US-CA",
    "attributes": {
      "tags": ["high-value"],
      "custom": {
        "CAC": 25,
        "channel": {"value": "Twitter", "source": "integration2"},
      },
    },
    "website_url": "https://example.com",
  },
)

{
  "id": 12150249,
  "uuid": "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  "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": "Ben",
  "email": "[email protected]",
  "company": "Example Company",
  "city": "San Francisco",
  "country": "US",
  "state": "CA",
  "zip": "99801",
  "lead_created_at": "2023-01-01T00:00:00.000Z",
  "free_trial_started_at": "2023-06-13T15:45:13.000Z",
  "customer-since": "2023-06-19T13:16:00-04:00",
  "status": "Active",
  "address": {
    "address_zip": "99801",
    "city": "San Francisco",
    "country": "US",
    "state": "CA"
  },
  "attributes": {
    "custom": {
      "CAC": 25,
      "SalesRep": "Mike"
    },
    "stripe": {},
    "tags": ["high-value"]
  },
  "mrr": 3000,
  "arr": 36000,
  "billing-system-url": "",
  "chartmogul-url": "https://app.chartmogul.com/#customers/12150249-Example_Company",
  "billing-system-type": "Custom",
  "currency": "USD",
  "currency-sign": "$",
  "owner": "[email protected]",
  "website_url": "https://example.com"
}

#<ChartMogul::Customer:0x0000000349d6a0
  @address={
    :country=>"United States",
    :state=>"California",
    :city=>"San Francisco",
    :address_zip=>"99801"},
  @arr=36000,
  @attributes={
    :custom=>{:CAC=>25, :SalesRep=>"Mike"},
    :stripe=>{},
    :tags=>["high-value"]},
  @billing_system_type="Custom",
  @billing_system_url=nil,
  @chartmogul_url="https://app.chartmogul.com/#customers/12150249-Example_Company",
  @city="San Francisco",
  @company="Example Company",
  @country="US",
  @currency="USD",
  @currency_sign="$",
  @customer_since=2023-06-19 13:16:00 +0000,
  @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  @data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  @email="[email protected]",
  @external_id="34916129",
  @external_ids=["34916129"],
  @free_trial_started_at=2023-06-13 15:45:13 UTC,
  @id=12150249,
  @lead_created_at=2023-01-01 00:00:00 UTC,
  @mrr=3000,
  @name="Ben",
  @state="CA",
  @status="Active",
  @uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  @zip="99801",
  @website_url="https://example.com"
>

{
  id: 12150249,
  uuid: "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  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: "Ben",
  email: "[email protected]",
  company: "Example Company",
  city: "San Francisco",
  country: "US",
  state: "CA",
  zip: "99801",
  lead_created_at: "2023-01-01T00:00:00.000Z",
  free_trial_started_at: "2023-06-13T15:45:13.000Z",
  "customer-since": "2023-06-19T13:16:00-04:00",
  status: "Active",
  address: {
    address_zip: "99801",
    city: "San Francisco",
    country: "US",
    state: "CA"
  },
  attributes: {
    custom: {
      CAC: 25,
      SalesRep: "Mike"
    },
    stripe: {},
    tags: ["high-value"]
  },
  mrr: 3000,
  arr: 36000,
  "billing-system-url": "",
  "chartmogul-url": "https://app.chartmogul.com/#customers/12150249-Example_Company",
  "billing-system-type": "Custom",
  currency: "USD",
  "currency-sign": "$",
  owner: "[email protected]",
  website_url: "https://example.com"
}

ChartMogul\Customer::__set_state(array(
  "id" => 12150249,
  "uuid" => "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  "external_id" => "34916129",
  "name" => "Ben",
  "email" => "[email protected]",
  "company" => "Example Company",
  "status" => "Active",
  "customer_since" => "2023-06-19T15:29:46.000Z",
  "attributes" =>
  array(
    "custom" =>
    array(
      "CAC" => 25,
      "channel" => "Facebook",
    ),
    "stripe" =>
    array(),
    "tags" =>
    array(
      0 => "high-value",
    ),
  ),
  "address" =>
  array(
    "country" => "United States",
    "state" => "California",
    "city" => "San Francisco",
    "address_zip" => "99801",
  ),
  "mrr" => 3000,
  "arr" => 36000,
  "billing_system_url" => NULL,
  "chartmogul_url" => "https://app.chartmogul.com/#customers/12150249-Example_Company",
  "billing_system_type" => "Custom",
  "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 => "34916129",
  ),
  "city" => "San Francisco",
  "country" => "US",
  "state" => "CA",
  "zip" => "99801",
  "lead_created_at" => "2023-01-01T00:00:00.000Z",
  "free_trial_started_at" => "2023-06-13T15:45:13.000Z",
  "website_url" => "https://example.com"
));

(*chartmogul.Customer)(0xc04207e840)({
  ID: (uint32) 12150249,
  DataSourceUUID: (string) (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  UUID: (string) (len=40) "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  ExternalID: (string) (len=8) "34916129",
  Name: (string) (len=3) "Ben",
  Email: (string) (len=15) "[email protected]",
  Status: (string) (len=6) "Active",
  CustomerSince: (string) (len=25) "2023-06-19T13:16:00-04:00",
  Attributes: (*chartmogul.Attributes)(0xc042089950)({
   Tags: ([]string) (len=1) {
    (string) (len=10) "high-value"
   },
   Stripe: (*chartmogul.Stripe)(0xc042041ec0)({
   }),
   Clearbit: (*chartmogul.Clearbit)(0xc04203ec00)({
   }),
   Custom: (map[string]interface {}) (len=2) {
    (string) (len=3) "CAC": (float64) 25,
    (string) (len=8) "SalesRep": (string) (len=4) "Mike"
   }
  }),
  Address: (*chartmogul.Address)(0xc0420485c0)({
   AddressZIP: (string) (len=6) "99801",
   City: (string) (len=13) "San Francisco",
   State: (string) (len=2) "CA",
   Country: (string) (len=2) "US"
  }),
  Mrr: (float64) 3000,
  Arr: (float64) 36000,
  BillingSystemURL: (string) "",
  ChartmogulURL: (string) (len=62) "https://app.chartmogul.com/#customers/12150249-Example_Company",
  BillingSystemType: (string) (len=10) "Custom",
  Currency: (string) (len=3) "USD",
  CurrencySign: (string) (len=1) "$",
  Company: (string) "Example Company",
  Country: (string) (len=2) "US"
  State: (string) (len=2) "CA",
  City: (string) (len=13) "San Francisco",
  Zip: (string) (len=6) "99801",
  LeadCreatedAt: (string) (len=24) "2023-01-01T00:00:00.000Z",
  FreeTrialStartedAt: (string) (len=24) "2023-06-13T15:45:13.000Z",
  WebsiteUrl: (string) (len=19) "https://example.com",
  Errors: (chartmogul.Errors) chartmogul: map[]
 })

<Customer{
  address=<Address{
    address_zip="99801", 
    city="San Francisco", 
    country="US", 
    state="CA"}>, 
  arr=36000.0, 
  attributes=<Attributes{
    custom={
      "CAC": 25, 
      "SalesRep": "Mike"}, 
    stripe=<Stripe{
    }>, 
    tags=["high-value"]}>, 
  billing_system_type="Custom", 
  billing_system_url=None, 
  chartmogul_url="https://app.chartmogul.com/#customers/12150249-Example_Company", 
  city="San Francisco", 
  company="Example Company", 
  country="US", 
  currency="USD", 
  currency_sign="$", 
  customer_since=datetime.datetime(2023, 11, 1, 0, 0), 
  data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
  data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"], 
  email="[email protected]",
  external_id="34916129", 
  external_ids=["34916129"], 
  free_trial_started_at=datetime.datetime(2023, 6, 13, 15, 45, 13), 
  id=12150249, 
  lead_created_at=datetime.datetime(2023, 1, 1, 0, 0), 
  mrr=3000.0, 
  name="Ben", 
  state="CA", 
  status="Active", 
  uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571", 
  website_url="https://example.com",
  zip="99801"
}>

Path parameters

customer_uuid string required: The ChartMogul UUID of the customer that needs to be updated. Specified as part of the URL.

Body parameters

name string optional deprecated

The customer's name for display purposes. Instead of the customer name, use the contact object to import the first and last name of a contact person.

email string optional deprecated

The customer's email address. Instead of the customer email, use the contact object to import the email of a contact person.

company string optional

The customer's company or organization.

lead_created_at string optional

Time at which this customer was established as a lead. Must be an ISO 8601-formatted time in the past. The timezone defaults to UTC unless otherwise specified.

free_trial_started_at string optional

Time at which this customer started a free trial of your product or service. Must be an ISO 8601-formatted time in the past. The timezone defaults to UTC unless otherwise specified. This is expected to be the same as or after the lead_created_at value.

zip string optional

Zip code of the customer's location.

city string optional

City of the customer's location.

state string optional

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

country string optional

Country code of customer's location as per ISO-3166 alpha-2 standard.

attributes object optional

An object containing the customer’s tags and custom attributes as described below. The tags and custom attributes contained in the payload will overwrite the existing ones. Any tags and custom attributes not specified in this object will be deleted.

tags array(string) optional: An array of tags for the customer. This will overwrite all tags already on the customer; the tags given here are used as-is.
custom object optional: An object with key-value pairs of custom attributes to be used for this customer. This will overwrite all custom attributes; attributes that exist on the customer but are not specified in the payload are removed. The key must match one of the attribute names listed under Data & Config > Custom Attributes > Customers. To add a custom attribute outside of this list, first create it in ChartMogul or use the Add Custom Attributes to a Customer endpoint.

owner string optional

Email address of the user.

primary_contact object optional

Primary contact (with position set to 1) specified for this customer. Use the Contact API endpoint to add more than one contact per customer.

first_name string optional: The first name of the contact
last_name string optional: The last name of the contact
email string optional: The contact's email address
title string optional: The job title of the contact, e.g. "CEO"
phone string optional: The contact's phone number
linked_in string optional: The URL of the contact's LinkedIn profile
twitter string optional: The URL of the contact's Twitter profile
notes string optional: Additional notes or comments about the contact. Newline can be appended with \n in the string.

status string optional

The customer’s status. One of the four lead statuses: New Lead, Working Lead, Qualified Lead or Unqualified Lead. You can only update a customer’s lead status. ChartMogul updates a customer’s subscription status (Active, Past Due or Cancelled) automatically depending on their subscription. Learn more.

website_url string optional

The URL of the customer’s website, starting with either “https://” or “http://”. If you provide the domain name only, such as “example.com”, ChartMogul will add “https://” at the beginning.

Updating tags and custom attributes. When updating tags and custom attributes, the attributes object must contain the existing tags and custom attribute values in addition to the ones you want to add or modify. If you only provide new tags and custom attribute values, the existing ones will be deleted.

Let’s say a customer has a tag vip and the following custom attributes: Marketing_channel set to Facebook and Number_of_support_requests set to 1. To add a tag webinar and update Number_of_support_requests to 2, you must provide all four values in the attributes object:

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 '{
            "attributes": {
              "tags": ["vip", "webinar"],
              "custom": {
                "Marketing_channel": "Facebook",
                "Number_of_support_requests": 2
              }
            }
         }'

This method only allows you to modify existing customer attribute values. To add new custom attributes, use the Add Custom Attributes to a Customer endpoint.

Response

In the response, the JSON object contains the following data:

id

The internal ChartMogul ID of the customer object.

uuid

The UUID of the customer object generated by ChartMogul.

data_source_uuid

The UUID of the data source that this customer belongs to. If this is a merged customer, then this will show the external identifier for the customer you chose to merge into.

data_source_uuids

An Array of the UUIDs of all data sources that contribute data to this customer.

external_id

The unique external identifier for this customer, as specified by you. If this is a merged customer, then this will show the external identifier for the customer you chose to merge into.

external_ids

An Array of the external identifiers of all customers that have been merged into this customer.

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, as specified by you.

country

The country of the customer, as specified by you.

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 of the customer, as specified by you.

zip

The zip code of the customer, as specified by you.

lead_created_at

The time at which this customer was established as a lead, as per the ISO 8601 standard.

free_trial_started_at

The time at which this customer started a free trial of your product or service, as per the ISO 8601 standard.

customer-since

An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.

status

The status of this customer. One of New Lead, Working Lead, Qualified Lead, Unqualified Lead, Active, Past Due or Cancelled.

address

A JSON object representing this customer's address containing the following data:

address_zip: The zip code of this customer's address.
city: The city of this customer's address.
state: The state from this customer's address.
country: The country code of this customer's address as per the ISO-3166-2 standard.

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.

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 €.

owner

The user who is responsible for the customer relationship. Returns a 400 error if the user does not have a ChartMogul CRM seat,

website_url

The URL of the customer’s website.