Skip to main content

Migrating from customer profile API v0 to v1

To read more about the two versions of the Customer Profile API, see the OpenAPI specifications provided here:

Pre-requisites​

Before you start the migration process, ensure that you have:

  1. Checked current API calls to customer_profile from your integration
  2. Found the impacted fields as listed in the sections below.

List of changes​

Name fields​

Concatenate the name fields and use just one field when creating or updating a customer profile.

If you are using the name field of the customer profile, find the places you are using it and change to use the new full_name field instead of the pair of fields first_name and last_name in the old version of the API.

Phone numbers​

Add error handling for phone number validation to your code if you create or update a profile.

The country code of the phone number is now part of the phone number. The field country_code in the old version of the API is now obsolete and is not returned. Use the phone_number field as is in v1.

More obsolete fields​

For store_name,

Use the field store_id and this method to get the required details.

For created_by_name,

Use the field created_by and this endpoint to get the required details.

For addresses,

Use the GET addresses Endpoint to get the addresses for a customer profile.

Extended attributes​

The format for extended attributes has now changed from an array to a map.

In v0 this looked like:

[
    {
        "name": "string",
        "value": "string"
    }
]

In v1, the extended attributes look like this:

{
    "loyalty_id": {
        "data_type": "string",
        "value": "0123456789"
    }
}

A new field data_type has been added to represent the data returned. The value is always stored as a string, but you can now specify the type of data you are storing in the value field.

Updating a customer profile​

When updating a customer profile, use the HTTP PATCH method in v1 instead of the PUT method in v0.

You no longer need to provide a value for the revision field for the update. Instead, you must include a last_updated_at field, which will be compared with the current value of the updated_at field in the profile.

The 2 fields must have the same value, otherwise the server returns a 409 conflict error, as shown here:

{
"message": "conflict",
"request_id": "7b2e635a-3a02-49df-98fb-46438e3fe842"
}

FAQs​

This section describes the Frequently Asked Questions on the impact of migration on retailers.

What changes do you expect in the event stream?​

There are no changes in the event stream. The first step is to move the API to a newer version.

If moved to v1:

  • The full_name field is split by the first space. Everything before the first space is saved as first_name, and everything after that is saved as last_name.
  • The address type is set to shipping.

What happens when you inject orders with customer profiles?​

The order injection feature is integrated with the new API and it is correctly importing profiles. Contact the support team for any help with troubleshooting.

What happens when you inject orders with shipping and billing addresses?​

The order injection feature is integrated with the new API and it is correctly importing addresses. Contact the support team for any help with troubleshooting.

How the data migration affects the names and phone numbers?​

  • The migration of customer names is not needed. We have changed only the API layer for now. The persistence layer will follow after we migrate all interfaces.

  • The migration of customer phone numbers is not needed. Even if invalid phone numbers are present (the API returns invalid phone numbers, if available), Omnichannel Manager and Associate App are not affected. However, if you try to create and update customer profiles with invalid phone numbers, they show error messages.

Related topics