Skip to content

Merge two customers

POST
/stores/{storeRef}/customers/{customerId}/merge
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/customers/1/merge \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "absorbed_id": "example", "keep": { "name": "survivor", "email": "survivor", "phone": "survivor", "default_address_id": 1 }, "reason": "example" }'

Folds one customer into another. The path names the customer that remains; absorbed_id in the body names the one folded in. Irreversible: the absorbed customer is deleted, and its orders, addresses, sign-in identities and metafield values move to the surviving customer. keep chooses, field by field, whose name, email and phone win. Merging a customer into itself is refused.

Required scopes: write:customers

customerId
required
integer

The customer ID.

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
absorbed_id
required

ID of the customer folded in and deleted. The path names the customer that remains.

string
keep

Which customer each conflicting field is taken from. A field left out keeps the surviving customer’s value.

object
name

Whose name the surviving customer keeps.

string
Allowed values: survivor absorbed
email

Whose email the surviving customer keeps.

string
Allowed values: survivor absorbed
phone

Whose phone number the surviving customer keeps.

string
Allowed values: survivor absorbed
default_address_id

ID of the address that becomes the default. It must belong to one of the two customers.

number
reason

Why the customers are being merged. Recorded on the customer timeline.

string
<= 500 characters
Media typeapplication/json
object
survivor_id
required

ID of the customer that remains.

number
merged_ids
required

IDs of the customers that were folded in and deleted.

Array<number>
moved_orders
required

Orders moved to the surviving customer.

number
moved_addresses
required

Addresses moved to the surviving customer.

number
moved_identities
required

Sign-in identities moved to the surviving customer.

number

Example generated

{
"survivor_id": 1,
"merged_ids": [
1
],
"moved_orders": 1,
"moved_addresses": 1,
"moved_identities": 1
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}