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_uuidstring required- The ChartMogul UUID of the customer that needs to be updated. Specified as part of the URL.
Body parameters
namestring 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.
emailstring deprecated-
The customer's email address. Instead of the customer email, use the contact object to import the email of a contact person.
companystring-
The customer's company or organization.
lead_created_atstring-
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_atstring-
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_atvalue. zipstring-
Zip code of the customer's location.
citystring-
City of the customer's location.
statestring-
The US state where the customer is located — the US state code as per the ISO-3166-2 standard. For example,
US-CAorUS-NY. countrystring-
Country code of customer's location as per ISO-3166 alpha-2 standard.
attributesobject-
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.
tagsarray(string)- An array of tags for the customer. This will overwrite all tags already on the customer; the tags given here are used as-is.
customobject- 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.
ownerstring-
Email address of the user.
primary_contactobject-
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_namestring- The first name of the contact
last_namestring- The last name of the contact
emailstring- The contact's email address
titlestring- The job title of the contact, e.g. "CEO"
phonestring- The contact's phone number
linked_instring- The URL of the contact's LinkedIn profile
twitterstring- The URL of the contact's Twitter profile
notesstring- Additional notes or comments about the contact. Newline can be appended with
\nin the string.
statusstring-
The customer’s status. One of the four lead statuses:
New Lead,Working Lead,Qualified LeadorUnqualified Lead. You can only update a customer’s lead status. ChartMogul updates a customer’s subscription status (Active,Past DueorCancelled) automatically depending on their subscription. Learn more. website_urlstring-
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.
namedeprecated-
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.
emaildeprecated-
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 DueorCancelled. 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,RecurlyorCustom. 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.