About Customer

Access scope

Multiple access scopes needed — refer to each endpoint for access scope requirements.

The customer module helps merchants maintain and analyze customer relationships. Genstore provides RESTful interfaces for managing online store customer information. Through these interfaces, merchants can efficiently handle customer information, including contact details, order history, and email marketing preferences.

Core Features

• Create Customer: Create new customer records.
• Delete Customer: Remove existing customer records.
• Query Customer: Retrieve specific customer details.
• List Customers: Get a list of store customers.

TIP

Before using the Customer APIs, please ensure your account has sufficient permissions to perform interface operations.

Use Cases

• Customer Profile Sync: CRM systems can sync customer data changes in real-time using the query interface.
• Marketing Segmentation: Marketing platforms can create targeted campaigns using customer attributes from the list interface.

Endpoints

EVENT customers/create: Customer creates message

EVENT customers/update: Customer updates

EVENT customers/delete: Customer deletes message

EVENT customers/merge: Customer merges messages

Customer Object

Create and manage customers

Properties

customerobject

Represents the personal information of a customer.

- Hide child properties

idnumber

Customer's unique identifier.

emailstring

The customer's email address.

createTimestring

Customer creation time (ISO 8601 format).

updateTimestring

Customer update time (ISO 8601 format).

phonestring

Customer's phone number.

verifiedEmailboolean

Whether the customer verifies the email address.

statestring

The state of the customer's account with the shop. Enumeration values: DECLINED - user declined to become a customer; DISABLED - invalid account; ENABLED - active customer; INVITED - customer under invitation.

firstNamestring

The customer's first name.

lastNamestring

The customer's last name.

notesstring

A note about the customer.

ordersCountobject

The number of orders that the customer has made at the store in their lifetime.

totalSpentobject

The total amount that the customer has spent on orders in their lifetime.

taxExemptboolean

Whether the customer is exempt from being charged taxes on their orders.

taxExemptionsobject

The list of tax exemptions applied to the customer.

+ Show child properties

smsMarketingConsentobject

The current SMS marketing state for the customer's phone number.

+ Show child properties

tagsarray

A list of tags that have been added to the customer.

emailMarketingConsentobject

The current email marketing state for the customer.

+ Show child properties

defaultAddressobject

The default address associated with the customer.

+ Show child properties

addressesarray

The addresses associated with the customer.

+ Show child properties

Customer Object

{
  "customer": {
    "lastName": "li",
    "addresses": [
      {
        "zip": "23456",
        "firstName": "heihei",
        "lastName": "du",
        "address2": "上海闵行",
        "city": "上海",
        "phone": "2345653464",
        "address1": "上海嘉定",
        "countryCode": "CN",
        "provinceCode": "SH",
        "company": "公司地址",
        "isDefaultAddress": "false",
        "id": "879"
      }
    ],
    "notes": "this is new customer",
    "totalSpent": "13",
    "taxExempt": "true",
    "taxExemptions": {
      "applyToAllRegion": "true",
      "taxExemptionRegions": [
        {
          "country": "US",
          "applyToAllSubdivision": "false",
          "subdivisions": "["NYC"]"
        }
      ]
    },
    "updateTime": "2024-18-12T08:18:49",
    "smsMarketingConsent": {
      "state": "SUBSCRIBED",
      "consentUpdateTime": "2024-11-12T08:18:49.125"
    },
    "tags": "[ "xinsheng",          "human" ]",
    "emailMarketingConsent": {
      "state": "SUBSCRIBED",
      "consentUpdateTime": "2024-11-12T08:18:49.125"
    },
    "firstName": "test23",
    "ordersCount": "2",
    "createTime": "2024-18-12T08:18:49",
    "phone": "13315034487",
    "id": "1020000013062",
    "state": "DECLINED",
    "email": "[email protected]",
    "verifiedEmail": "true",
    "defaultAddress": {
      "zip": "20000",
      "firstName": "heihei",
      "lastName": "chen",
      "address2": "cao he jing",
      "city": "shanghai",
      "phone": "13315035578",
      "address1": "xu hui",
      "countryCode": "CN",
      "provinceCode": "FJ",
      "company": "demo",
      "isDefaultAddress": "true",
      "id": "878"
    }
  }
}

EVENT Customer creates message

Customer creates message

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/create 

Event Data

customerobject

Represents the personal information of a customer.

- Hide child properties

idnumber

Customer's unique identifier.

emailstring

The customer's email address.

createTimestring

Customer creation time (ISO 8601 format).

updateTimestring

Customer update time (ISO 8601 format).

phonestring

Customer's phone number.

verifiedEmailboolean

Whether the customer verifies the email address.

statestring

The state of the customer's account with the shop. Enumeration values: DECLINED - user declined to become a customer; DISABLED - invalid account; ENABLED - active customer; INVITED - customer under invitation.

firstNamestring

The customer's first name.

lastNamestring

The customer's last name.

notesstring

A note about the customer.

ordersCountobject

The number of orders that the customer has made at the store in their lifetime.

totalSpentobject

The total amount that the customer has spent on orders in their lifetime.

taxExemptboolean

Whether the customer is exempt from being charged taxes on their orders.

taxExemptionsobject

The list of tax exemptions applied to the customer.

+ Show child properties

smsMarketingConsentobject

The current SMS marketing state for the customer's phone number.

+ Show child properties

tagsarray

A list of tags that have been added to the customer.

emailMarketingConsentobject

The current email marketing state for the customer.

+ Show child properties

defaultAddressobject

The default address associated with the customer.

+ Show child properties

addressesarray

The addresses associated with the customer.

+ Show child properties

customers/create: Sample Payload

{
  "lastName": "li",
  "addresses": [
    {
      "zip": "23456",
      "firstName": "heihei",
      "lastName": "du",
      "address2": "cao he jing",
      "city": "shang hai",
      "phone": "2345653464",
      "address1": "xu hui",
      "countryCode": "CN",
      "provinceCode": "SH",
      "company": "demo",
      "isDefaultAddress": "false",
      "id": "879"
    }
  ],
  "notes": "this is new customer",
  "totalSpent": "13",
  "taxExempt": "true",
  "taxExemptions": {
    "applyToAllRegion": "true",
    "taxExemptionRegions": [
      {
        "country": "US",
        "applyToAllSubdivision": "false",
        "subdivisions": "[\"NYC\"]"
      }
    ]
  },
  "updateTime": "2024-18-12T08:18:49",
  "smsMarketingConsent": {
    "state": "SUBSCRIBED",
    "consentUpdateTime": "2024-11-12T08:18:49.125"
  },
  "tags": "[ \"xinsheng\",          \"human\" ]",
  "emailMarketingConsent": {
    "state": "SUBSCRIBED",
    "consentUpdateTime": "2024-11-12T08:18:49.125"
  },
  "firstName": "test23",
  "ordersCount": "2",
  "createTime": "2024-18-12T08:18:49",
  "phone": "13315034487",
  "id": "1020000013062",
  "state": "DECLINED",
  "email": "[email protected]",
  "verifiedEmail": "true",
  "defaultAddress": {
    "zip": "20000",
    "firstName": "heihei",
    "lastName": "chen",
    "address2": "cao he jing",
    "city": "shang hai",
    "phone": "13315035578",
    "address1": "xu hui",
    "countryCode": "CN",
    "provinceCode": "FJ",
    "company": "demo",
    "isDefaultAddress": "true",
    "id": "878"
  }
}

EVENT Customer updates

Customer updates

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/update 

Event Data

customerobject

Represents the personal information of a customer.

- Hide child properties

idnumber

Customer's unique identifier.

emailstring

The customer's email address.

createTimestring

Customer creation time (ISO 8601 format).

updateTimestring

Customer update time (ISO 8601 format).

phonestring

Customer's phone number.

verifiedEmailboolean

Whether the customer verifies the email address.

statestring

The state of the customer's account with the shop. Enumeration values: DECLINED - user declined to become a customer; DISABLED - invalid account; ENABLED - active customer; INVITED - customer under invitation.

firstNamestring

The customer's first name.

lastNamestring

The customer's last name.

notesstring

A note about the customer.

ordersCountobject

The number of orders that the customer has made at the store in their lifetime.

totalSpentobject

The total amount that the customer has spent on orders in their lifetime.

taxExemptboolean

Whether the customer is exempt from being charged taxes on their orders.

taxExemptionsobject

The list of tax exemptions applied to the customer.

+ Show child properties

smsMarketingConsentobject

The current SMS marketing state for the customer's phone number.

+ Show child properties

tagsarray

A list of tags that have been added to the customer.

emailMarketingConsentobject

The current email marketing state for the customer.

+ Show child properties

defaultAddressobject

The default address associated with the customer.

+ Show child properties

addressesarray

The addresses associated with the customer.

+ Show child properties

customers/update: Sample Payload

{
  "lastName": "li",
  "addresses": [
    {
      "zip": "23456",
      "firstName": "heihei",
      "lastName": "du",
      "address2": "cao he jing",
      "city": "shang hai",
      "phone": "2345653464",
      "address1": "xu hui",
      "countryCode": "CN",
      "provinceCode": "SH",
      "company": "demo",
      "isDefaultAddress": "false",
      "id": "879"
    }
  ],
  "notes": "this is new customer",
  "totalSpent": "13",
  "taxExempt": "true",
  "taxExemptions": {
    "applyToAllRegion": "true",
    "taxExemptionRegions": [
      {
        "country": "US",
        "applyToAllSubdivision": "false",
        "subdivisions": "[\"NYC\"]"
      }
    ]
  },
  "updateTime": "2024-18-12T08:18:49",
  "smsMarketingConsent": {
    "state": "SUBSCRIBED",
    "consentUpdateTime": "2024-11-12T08:18:49.125"
  },
  "tags": "[ \"xinsheng\",          \"human\" ]",
  "emailMarketingConsent": {
    "state": "SUBSCRIBED",
    "consentUpdateTime": "2024-11-12T08:18:49.125"
  },
  "firstName": "test23",
  "ordersCount": "2",
  "createTime": "2024-18-12T08:18:49",
  "phone": "13315034487",
  "id": "1020000013062",
  "state": "DECLINED",
  "email": "[email protected]",
  "verifiedEmail": "true",
  "defaultAddress": {
    "zip": "20000",
    "firstName": "heihei",
    "lastName": "chen",
    "address2": "cao he jing",
    "city": "shang hai",
    "phone": "13315035578",
    "address1": "xu hui",
    "countryCode": "CN",
    "provinceCode": "FJ",
    "company": "demo",
    "isDefaultAddress": "true",
    "id": "878"
  }
}

EVENT Customer deletes message

Customer deletes message

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/delete 

Event Data

customerobject

Represents the personal information of a customer.

- Hide child properties

idnumber

Customer's unique identifier.

emailstring

The customer's email address.

createTimestring

Customer creation time (ISO 8601 format).

updateTimestring

Customer update time (ISO 8601 format).

phonestring

Customer's phone number.

firstNamestring

The customer's first name.

lastNamestring

The customer's last name.

customers/delete: Sample Payload

{
  "customer": {
    "firstName": "test23",
    "lastName": "li",
    "createTime": "2024-18-12T08:18:49",
    "phone": "13315034487",
    "updateTime": "2024-18-12T08:18:49",
    "id": "1020000013062",
    "email": "[email protected]"
  }
}

EVENT Customer merges messages

Customer merges messages.

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/merge 

Event Data

jobIdnumber

The UUID of the merge job.

customerKeptIdnumber

The customer's unique identifier that is preserved in the merge.

customerDeletedIdnumber

The customer's unique identifier was removed in the merge.

statusstring

The status of the client merge. Enumeration values:
* COMPLETED - Customer merge request completed;
* FAILED - Customer merge failed;
* IN_PROGRESS - Customer merge request is currently in progress;
* REQUESTED - Customer merge requested.

errorFieldsarray

An error occurred during a customer merge request.

+ Show child properties

customers/merge: Sample Payload

{
  "jobId": "123456789",
  "customerDeletedId": "111222333",
  "customerKeptId": "987654321",
  "errorFields": [
    {
      "field": "deletedAt",
      "message": "The customer does not exist."
    }
  ],
  "status": "COMPLETED"
}

About Customer

Access scope

Multiple access scopes needed — refer to each endpoint for access scope requirements.

The customer module helps merchants maintain and analyze customer relationships. Genstore provides RESTful interfaces for managing online store customer information. Through these interfaces, merchants can efficiently handle customer information, including contact details, order history, and email marketing preferences.

Core Features

• Create Customer: Create new customer records.
• Delete Customer: Remove existing customer records.
• Query Customer: Retrieve specific customer details.
• List Customers: Get a list of store customers.

TIP

Before using the Customer APIs, please ensure your account has sufficient permissions to perform interface operations.

Use Cases

• Customer Profile Sync: CRM systems can sync customer data changes in real-time using the query interface.
• Marketing Segmentation: Marketing platforms can create targeted campaigns using customer attributes from the list interface.

Customer Object

Create and manage customers

Properties

EVENT Customer creates message

Customer creates message

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/create 

EVENT Customer updates

Customer updates

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/update 

EVENT Customer deletes message

Customer deletes message

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/delete 

EVENT Customer merges messages

Customer merges messages.

Access scope

Requires ANY of the following access scopes: write_customers read_customers

Topic

EVENT customers/merge