(Legacy) Customer Profile API (v0)

Download OpenAPI specification:Download

Represents a customer, identified by a customer id in NewStore. You can use this resource to manage customers and also for clienteling activities in NewStore applications.

Typically, customers are created automatically when they place an order online or when they provide their email address during an in-store purchase.

Warning: This API version is deprecated and will sunset on March 31st, 2025. We recommend that all new integrations use the latest Customer Profile API v2. Please use the migration guide to migrate from this version to the new version.

List full customers Deprecated

Returns a filtered list of customers.

Note: The pagination is limited to 500 items.

Related methods:

Get customer
Update customer

Authorizations:

newStoreAccessToken

query Parameters

q	string The search term to filter customers. The term is compared to the values in the `email`, `first_name`, `last_name`, and `phone_number` fields. A partial match is also considered a match. Note: A partial match is considered a match only on first_name and last_name. However, on the email, a full match may still return multiple results. For example, `jan.doer@example.com` will return `bojan.doer@example.com` and `jan.doer@example.com.uk` as well.
sort	string Sorts the returned values. Takes two values separated by the pipe character (`\|`), the field to sort and the sort order.
filter[created_by]	string ID of the associate who created the consumer profile.
filter[extended_attributes.name]	string Name of a specific extended attribute. Should be used in combination with the `extended_attributes.value` filter.
filter[extended_attributes.value]	string Value of a specific extended attribute. Should be used in combination with the `extended_attributes.name` filter.
offset	integer >= 0 Default: 0 The page offset.
count	integer [ 1 .. 500 ] Default: 10 The number of requested documents.

Responses

Response samples

200

Content type

application/json

{"items": [{"email": "john@example.com",
"id": "6932760230624376023466",
"first_name": "John",
"last_name": "Smith",
"phone_number": "+555555555555",
"country_code": "US",
"addresses": [{"type": "billing",
"company": "ACME",
"first_name": "John",
"last_name": "Smith",
"address_line_1": "137 W 67th St",
"address_line_2": "",
"zip_code": "",
"city": "",
"state": "",
"country_code": "AD",
"contact_phone": "",
"id": "",
"created_at": "2020-01-24T10:39:22.655Z",
"updated_at": "2020-01-24T10:39:22.655Z",
"revision": 1
}
],
"created_by": "",
"created_by_name": "",
"store_id": "7c9f2605-9fb3-5444-8fee-47fe51608efe",
"store_name": "NYC_1_5thave",
"created_at": "2020-01-24T10:39:22.656Z",
"updated_at": "2020-02-24T10:39:22.656Z",
"revision": 1
}
],
"pagination_info": {"count": 1,
"total": 20,
"offset": 1
}
}

Create customer Deprecated

Creates a customer based on a given unique email addresss.

Note: Typically, customers are created automatically when they place an order online or when they provide their email address, during an in-store purchase.

Related methods:

Request customer deletion
Get customer

Authorizations:

newStoreAccessToken

Request Body schema: application/json

required	string or string Main e-mail of the consumer.
first_name	string First name of the consumer.
last_name	string Last name of the consumer.
phone_number	string Phone number of the consumer.
country_code	string Phone number country code of the consumer.
	object Details of chosen billing address.
	object Details of chosen shipping address.
	Array of objects <= 20 items [ items <= 2 properties ] List of all extended attributes for this profile.

Responses

Request samples

Payload

Content type

application/json

{"email": "jaydoubleyou@example.com",
"first_name": "Jay",
"last_name": "DoubleYou",
"phone_number": "202-555-0182",
"extended_attributes": [{"name": "shirt_fit",
"value": "slim"
}
]
}

Response samples

200
409

Content type

application/json

{"addresses": [ ],
"country_code": "US",
"created_at": "2022-05-20T08:48:28.640Z",
"created_by": "7eaa5282f74749d0b2658154dcce2e20",
"created_by_name": "Clienteling, Tim",
"display_id": "JO2MDZ",
"email": "jaydoubleyou@example.com",
"extended_attributes": [{"name": "shirt_fit",
"value": "slim"
}
],
"first_name": "Jay",
"id": "4e3e504f-a3e9-4f41-a493-1c8124c12253",
"last_name": "DoubleYou",
"phone_number": "(202) 555-0182",
"revision": "1,",
"store_id": "7c9f2605-9fb3-5444-8fee-47fe51608efe",
"store_name": "New York 5th Avenue"
}

List simplified customers Deprecated

Returns a filtered list of customers.

Note: The pagination is limited to 500 items.

Related methods:

Get customer
Update customer

Authorizations:

newStoreAccessToken

query Parameters

q	string The search term to filter customers. The term is compared to the values in the `email`, `first_name`, `last_name`, and `phone_number` fields. A partial match is also considered a match. Note: A partial match is considered a match only on first_name and last_name. However, on the email, a full match may still return multiple results. For example, `jan.doer@example.com` will return `bojan.doer@example.com` and `jan.doer@example.com.uk` as well.
sort	string Sorts the returned values. Takes two values separated by the pipe character (`\|`), the field to sort and the sort order.
filter[created_by]	string ID of the associate who created the consumer profile.
filter[extended_attributes.name]	string Name of a specific extended attribute. Should be used in combination with the `extended_attributes.value` filter.
filter[extended_attributes.value]	string Value of a specific extended attribute. Should be used in combination with the `extended_attributes.name` filter.
offset	integer >= 0 Default: 0 The page offset.
count	integer [ 1 .. 500 ] Default: 10 The number of requested documents.

Responses

Response samples

200

Content type

application/json

{"items": [{"email": "john@example.com",
"id": "6932760230624376023466",
"first_name": "John",
"last_name": "Smith",
"phone_number": "+555555555555",
"country_code": "US",
"created_by_name": "Someone",
"store_name": "NYC_1_5thave",
"created_at": "2020-01-24T10:39:22.656Z",
"display_id": "GSDFEA"
}
],
"pagination_info": {"count": 1,
"total": 20,
"offset": 1
}
}

List opted in customers to clienteling

Gets a list of all opted in customers to clienteling for the given store ID.

Authorizations:

newStoreAccessToken

path Parameters

store_id

required

string

The identifier of the store onboarded to clienteling.

Responses

Response samples

200

Content type

application/json

{"count": 0,
"total": 0,
"offset": 0,
"consumers": [{"id": "string",
"name": "string",
"phone_number": "string",
"opt_in_date": "string",
"store_id": "string"
}
]
}

Update customer Deprecated

Updates an existing customer. The customer details are used for clienteling in NewStore applications.

Related methods:

Update address

Authorizations:

newStoreAccessToken

path Parameters

id

required

string

To retrieve the customer id, use the List customers method.

Request Body schema: application/json

first_name required	string First name of the customer.
last_name required	string Last name of the customer.
phone_number	string Phone number of the customer.
email	object E-mail address of the customer.
required	Array of objects <= 20 items [ items <= 2 properties ] List of all extended attributes for this profile.
revision required	integer multiple of 1 >= 0 Revision of the profile.

Responses

Request samples

Payload

Content type

application/json

{"first_name": "string",
"last_name": "string",
"phone_number": "string",
"email": { },
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"revision": 0
}

Response samples

200
409

Content type

application/json

{"id": "string",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"phone_number": "string",
"country_code": "string",
"addresses": [{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"revision": 0
}
],
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"created_by": "string",
"created_by_name": "string",
"store_id": "string",
"store_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"revision": 0,
"display_id": "string"
}

Get customer Deprecated

Returns the customer matching the specified ID.

Authorizations:

newStoreAccessToken

path Parameters

id

required

string

To retrieve the customer id, use the List customers method.

Responses

Response samples

200

Content type

application/json

{"id": "string",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"phone_number": "string",
"country_code": "string",
"addresses": [{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"revision": 0
}
],
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"created_by": "string",
"created_by_name": "string",
"store_id": "string",
"store_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"revision": 0,
"display_id": "string"
}

Request customer deletion Deprecated

Requests the deletion of the specified customer.

The deletion is GDPR-compliant.

Important: It may take up to 30 days for the customer profile to be deleted from the platform.

After deletion is complete, it is not possible to restore original profile.

Related methods:

Delete address

Authorizations:

newStoreAccessToken

path Parameters

id

required

string

To retrieve the customer id, use the List customers method.

Responses

Create address Deprecated

Creates an address for a customer.

Authorizations:

newStoreAccessToken

path Parameters

id

required

string

To retrieve the customer id, use the List customers method.

Request Body schema: application/json

type required	string Enum: "billing" "shipping" Describes which type the address is referring to. e.g. billing or shipping address.
company	string Company name.
first_name	string First name.
last_name	string Last name.
address_1	string First line of the address. Typically, the street and house number.
address_2	string Second line of the address. Typically, the apartment number or PO box
zip_code	string Postal code of the address.
city	string The city/town of the address.
state	string State/province or region of the address.
country_code	string Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW" Country code in ISO 3166-1 alpha-2 format.
contact_phone	string Contact phone number chosen by the consumer.
profile_revision	integer multiple of 1 >= 0 Revision of the consumer profile.

Responses

Request samples

Payload

Content type

application/json

{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"profile_revision": 0
}

Response samples

200

Content type

application/json

{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"profile_revision": 0
}

Update address Deprecated

Updates the address for a customer.

Authorizations:

newStoreAccessToken

path Parameters

address_id required	string Unique ID for the address.
id required	string To retrieve the customer `id`, use the List customers method.

Request Body schema: application/json

type	string Enum: "billing" "shipping" Describes which type the address is referring to. e.g. billing or shipping address.
company	string Company name.
first_name	string First name.
last_name	string Last name.
address_1	string First line of the address. Typically, the street and house number.
address_2	string Second line of the address. Typically, the apartment number or PO box
zip_code	string Postal code of the address.
city	string The city/town of the address.
state	string State/province or region of the address.
country_code	string Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW" Country code in ISO 3166-1 alpha-2 format.
contact_phone	string Contact phone number chosen by the consumer.
profile_revision	integer multiple of 1 >= 0 Updated revision of the consumer profile.

Responses

Request samples

Payload

Content type

application/json

{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"profile_revision": 0
}

Response samples

200

Content type

application/json

{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"profile_revision": 0
}

Delete address Deprecated

Deletes the address for a customer.

Authorizations:

newStoreAccessToken

path Parameters

address_id required	string Unique ID for the address.
id required	string To retrieve the customer `id`, use the List customers method.

Request Body schema: application/json

profile_revision

required

integer multiple of 1 >= 0

Revision of the consumer profile.

Responses

Request samples

Payload

Content type

application/json

{"profile_revision": 0
}

Get address Deprecated

Gets the address for a customer.

Authorizations:

newStoreAccessToken

path Parameters

address_id required	string Unique ID for the address.
id required	string To retrieve the customer `id`, use the List customers method.

Responses

Response samples

200

Content type

application/json

{"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string",
"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"profile_revision": 0
}

List customer orders Deprecated

Lists orders for a customer.

Authorizations:

newStoreAccessToken

path Parameters

id

required

string

The customer id returned in the response to the Create customer method.

query Parameters

offset	integer >= 0 Default: 0 The page offset.
count	integer [ 1 .. 500 ] Default: 10 The number of requested documents.

Responses

Response samples

200

Content type

application/json

{"count": 0,
"total": 0,
"offset": 0,
"items": [{"order_uuid": "stringstringstringstringstringstring",
"order_id": "string",
"external_order_id": "string",
"customer_uuid": "stringstringstringstringstringstring",
"external_customer_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"created_by_label": "string",
"taxation": "net",
"status_label": "string",
"status_description": "string",
"shipping_address": {"title": "string",
"suffix": "string",
"salutation": "string",
"first_name": "string",
"second_name": "string",
"last_name": "string",
"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"phone": "string"
},
"billing_address": {"title": "string",
"suffix": "string",
"salutation": "string",
"first_name": "string",
"second_name": "string",
"last_name": "string",
"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"phone": "string",
"email": "string"
},
"payments": [{"uuid": "stringstringstringstringstringstring",
"currency": "str",
"method": "string",
"payment_detail": "string",
"credit_card_number": "stri",
"status_label": "string",
"status_description": "string"
}
],
"totals": {"merchandise_total": 0,
"shipping_total": 0,
"shipping_taxes": 0,
"taxes": 0,
"order_total": 0,
"gift_wrapping_taxes": 0,
"gift_wrapping_total": 0,
"grand_total": 0,
"currency": "str"
},
"shipments": [{"shipment_uuid": "stringstringstringstringstringstring",
"shipping_from": "string",
"links": {"return_label": "string",
"invoice": "string",
"sales_receipt": "string"
},
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str"
},
"totals": {"merchandise_total": 0,
"shipping_total": 0,
"shipping_taxes": 0,
"taxes": 0,
"order_total": 0,
"gift_wrapping_taxes": 0,
"gift_wrapping_total": 0,
"grand_total": 0,
"currency": "str"
},
"details": {"carrier": "string",
"method": "string",
"delivery_forecast_at": "2019-08-24T14:15:22Z",
"delivery_status_label": "string",
"delivery_status_id": "pending",
"delivery_status_date": "2019-08-24T14:15:22Z",
"delivered_at": "2019-08-24T14:15:22Z",
"shipping_packages": [{"shipment_id": "string",
"tracking_code": "string",
"tracking_url": "http://example.com",
"delivery_from": "2019-08-24T14:15:22Z",
"delivery_to": "2019-08-24T14:15:22Z",
"delivered_at": "2019-08-24T14:15:22Z",
"product_ids": ["string"
],
"links": {"return_label": "string",
"return_form": "string"
}
}
]
},
"items": [{"id": "string",
"name": "string",
"image": "string",
"quantity": 0,
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str",
"catalog": 0
},
"category": "string",
"variation_color_value": "string",
"variation_size_value": "string",
"variation_attribute_1_value": "string",
"variation_attribute_2_value": "string",
"product_sku": "string",
"custom_attributes": [{"name": "string",
"value": "string"
}
],
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
]
}
],
"returns": [{"return_id": "string",
"items": [{"product_id": "string",
"quantity": 0,
"return_reason": "string",
"return_code": "string",
"returned_at": "2019-08-24T14:15:22Z"
}
],
"refund_note": "string"
}
],
"accounting_entity": {"id": "string",
"accounting_address": {"type": "billing",
"company": "string",
"first_name": "string",
"last_name": "string",
"address_1": "string",
"address_2": "string",
"zip_code": "string",
"city": "string",
"state": "string",
"country_code": "AD",
"contact_phone": "string"
}
},
"store_address": {"address_line_1": "string",
"address_line_2": "string",
"province": "string",
"state": "string",
"zip_code": "string",
"city": "string",
"country_code": "AD",
"latitude": 0,
"longitude": 0
},
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
]
}
],
"value_added_services": [{"service_type": "string",
"options": { },
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str"
}
}
],
"ordered_products": [{"id": "string",
"name": "string",
"image": "string",
"quantity": 0,
"price": {"net": 0,
"tax": 0,
"gross": 0,
"base": 0,
"adjustment": 0,
"adjusted_total": 0,
"currency": "str",
"catalog": 0
},
"category": "string",
"variation_color_value": "string",
"variation_size_value": "string",
"variation_attribute_1_value": "string",
"variation_attribute_2_value": "string",
"product_sku": "string",
"custom_attributes": [{"name": "string",
"value": "string"
}
],
"extended_attributes": [{"name": "string",
"value": "string"
}
],
"discounts": [{"promotion_uuid": "stringstringstringstringstringstring",
"price_adjustment": 0,
"reason": "string",
"action": "fixed",
"value": 0,
"level": "item",
"coupon_code": "string",
"external_ref": "string"
}
]
}
],
"channel": "string",
"channel_type": "string",
"extended_attributes": [{"name": "string",
"value": "string"
}
]
}
]
}