顾客

Customer API 用于在前台 JavaScript 中注册顾客、让顾客登录和登出，以及读取和修改已登录顾客的资料、地址和营销邮件订阅状态。

所有 Ajax API 请求应使用多语言 URL，以便为访客提供一致的体验。

身份要求

顾客登录态。 注册、登录、发送密码重置邮件、重置密码、发送登录验证码、订阅营销邮件、读取登录配置这几个 endpoint 匿名访客可以调用，本页其余 endpoint 都需要顾客已登录。登录态保存在 cookie 里，sign_up 或 sign_in 成功后浏览器会自动带上。没有登录态时请求返回 401：

{
  "errors": [
    "Sign in to continue store operations."
  ]
}

CSRF token。 除 GET 以外的请求都要带 X-CSRF-Token 请求头，值取 cookie CSRF-TOKEN。该 cookie 可以在 JavaScript 中读取，下面的示例都用这个函数取值：

function getCsrfToken() {
  const entry = document.cookie.split('; ').find((item) => item.startsWith('CSRF-TOKEN='));
  return entry ? decodeURIComponent(entry.slice('CSRF-TOKEN='.length)) : '';
}

缺少该请求头时，请求返回 406，响应体为 {"errors":["CSRF token verify fails"]}。

人机校验。 注册、登录、发送密码重置邮件、重置密码这四个 endpoint 受店铺的人机校验保护。服务端需要校验时返回 400，响应体为 {"errors":["{\"errors\":[\"empty token\"]}"]}。此时把人机校验令牌放进 token 字段、version 传 v3，重新提交请求。在 Shoplazza 主题中，spz-privacy-token 组件会自动填好这两个字段；自己发请求时，从店铺配置的人机校验服务（Google reCAPTCHA v3）获取令牌。

请求格式。 本页需要提交数据的 endpoint 都使用 application/x-www-form-urlencoded 请求体，下面的示例用 URLSearchParams 构造。

注册顾客账号

POST /{locale}/api/customers/sign_up

注册顾客账号。请求成功后会同时建立顾客登录态，顾客即为已登录状态。

请求示例

const body = new URLSearchParams({
  email: '[email protected]',
  password: 'your-password',
  first_name: 'Jane',
  last_name: 'Doe',
  newsletter: 'true'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/sign_up', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

账号的邮箱地址。

passwordstring

账号的密码。

first_namestring

顾客的名。

last_namestring

顾客的姓。

newsletterboolean

顾客是否订阅营销邮件。

tokenstring

人机校验令牌。店铺的人机校验要求校验时必填。

versionstring

人机校验版本，取值 v3。与 token 一起填。

响应

数据结构
示例

customer object
idstring
顾客的 ID。
emailstring
顾客的邮箱地址。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
phonestring可空
顾客的电话号码。
tagsundefined[]
对象上的标签。
namestring
顾客的全名。
notestring可空
对象上的备注。
contactstring
顾客的联系方式，邮箱或电话号码。
contact_typestring
联系方式类型，邮箱或电话。
created_bystring
location_idstring
registered_atstring
顾客完成注册的时间。
noted_atstring可空
created_atstring
创建时间（ISO-8601 格式）。
sourcestring
顾客数据的来源。
free_taxboolean
顾客是否享有税收豁免。
subscribedboolean
顾客是否订阅了营销信息。
registeredboolean
顾客是否已注册账号。
customer_extra_info object
顾客的附加统计信息。
finished_order_countnumber
顾客已完成的订单数。
finished_order_totalstring
顾客已完成订单的总金额。
countrystring可空
country_codestring可空
provincestring可空
地址所在省或州。
province_codestring可空
省或州的代码。
currency_codestring
订单的货币代码，例如 USD。
purchase_product_countnumber
顾客已购买的商品件数。
store_customer_idstring
customer_rolestring可空
extstring可空
first_order_atstring可空
顾客首次下单时间。
last_order_atstring可空
顾客最后一次下单时间。

{
  "customer": {
    "id": "04f268c8-fea5-4386-abd7-c4fade761257",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "tags": [],
    "name": "Jane Doe",
    "note": null,
    "contact": "[email protected]",
    "contact_type": "email",
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T02:48:07Z",
    "noted_at": null,
    "created_at": "2026-09-03T02:48:08Z",
    "source": "sign_up",
    "free_tax": false,
    "subscribed": true,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 0,
      "finished_order_total": "0.0",
      "country": null,
      "country_code": null,
      "province": null,
      "province_code": null,
      "currency_code": "USD",
      "purchase_product_count": 0,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": null,
      "last_order_at": null
    }
  }
}

顾客登录

POST /{locale}/api/customers/sign_in

用邮箱和密码登录顾客账号，并建立顾客登录态。

请求示例

const body = new URLSearchParams({
  email: '[email protected]',
  password: 'your-password'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/sign_in', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

账号的邮箱地址。

passwordstring

账号的密码。

tokenstring

人机校验令牌。店铺的人机校验要求校验时必填。

versionstring

人机校验版本，取值 v3。与 token 一起填。

响应

数据结构
示例

customer object
idstring
顾客的 ID。
emailstring
顾客的邮箱地址。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
phonestring
顾客的电话号码。
tagsundefined[]
对象上的标签。
namestring
顾客的全名。
notestring可空
对象上的备注。
contactstring
顾客的联系方式，邮箱或电话号码。
contact_typestring
联系方式类型，邮箱或电话。
created_bystring
location_idstring
registered_atstring
顾客完成注册的时间。
noted_atstring可空
created_atstring
创建时间（ISO-8601 格式）。
sourcestring
顾客数据的来源。
free_taxstring可空
顾客是否享有税收豁免。
subscribedboolean
顾客是否订阅了营销信息。
registeredboolean
顾客是否已注册账号。
customer_extra_info object
顾客的附加统计信息。
finished_order_countnumber
顾客已完成的订单数。
finished_order_totalstring
顾客已完成订单的总金额。
countrystring
country_codestring
provincestring
地址所在省或州。
province_codestring
省或州的代码。
currency_codestring
订单的货币代码，例如 USD。
purchase_product_countnumber
顾客已购买的商品件数。
store_customer_idstring
customer_rolestring可空
extstring可空
first_order_atstring
顾客首次下单时间。
last_order_atstring
顾客最后一次下单时间。

{
  "customer": {
    "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1 555-0100",
    "tags": [],
    "name": "Jane Doe",
    "note": null,
    "contact": "[email protected]",
    "contact_type": "email",
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T01:03:32Z",
    "noted_at": null,
    "created_at": "2026-09-02T14:13:31Z",
    "source": "order_create_c",
    "free_tax": null,
    "subscribed": false,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 2,
      "finished_order_total": "33.0",
      "country": "United States",
      "country_code": "US",
      "province": "California",
      "province_code": "US-CA",
      "currency_code": "USD",
      "purchase_product_count": 4,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": "2026-09-03T02:19:44Z",
      "last_order_at": "2026-09-03T02:32:31Z"
    }
  }
}

顾客登出

POST /{locale}/api/customers/sign_out

结束当前顾客登录态。需要顾客登录态，没有参数。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/sign_out', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

响应

数据结构
示例

object

{}

发送密码重置邮件

POST /{locale}/api/customers/password_reset_email

向顾客发送密码重置邮件。邮件里带的验证码用于 PATCH /{locale}/api/customers/password_reset。

请求示例

const body = new URLSearchParams({ email: '[email protected]' });

fetch(window.SHOPLAZZA.routes.root + '/api/customers/password_reset_email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

账号的邮箱地址。

响应

数据结构
示例

object

{}

重置顾客密码

PATCH /{locale}/api/customers/password_reset

用密码重置邮件里的验证码为顾客设置新密码。

请求示例

const body = new URLSearchParams({
  email: '[email protected]',
  code: '123456',
  password: 'your-new-password',
  confirm_password: 'your-new-password'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/password_reset', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

账号的邮箱地址。

codestring

密码重置邮件里的验证码。

passwordstring

新密码。

confirm_passwordstring

再次输入的新密码，必须与 password 一致。

tokenstring

人机校验令牌。店铺的人机校验要求校验时必填。

versionstring

人机校验版本，取值 v3。与 token 一起填。

响应

数据结构
示例

object

{}

发送登录验证码

POST /{locale}/api/customers/login_email

向顾客邮箱发送登录验证码，用于让顾客用验证码代替密码登录的场景。

请求示例

const body = new URLSearchParams({ email: '[email protected]' });

fetch(window.SHOPLAZZA.routes.root + '/api/customers/login_email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

接收验证码的邮箱地址。

响应

数据结构
示例

object

{}

获取店铺社交登录方式

GET /{locale}/api/customers/login_settings

获取店铺登录页提供的社交登录方式。无参数。店铺未开启任何社交登录时，login_setting 为 null。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/login_settings')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

响应

数据结构
示例

login_setting object
googleboolean
是否开启 Google 登录。
appleboolean
是否开启 Apple 登录。
facebookboolean
是否开启 Facebook 登录。

{
  "login_setting": {
    "google": true,
    "apple": true,
    "facebook": true
  }
}

获取当前顾客资料

GET /{locale}/api/customers/show

获取当前已登录顾客的资料。需要顾客登录态，没有参数。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/show')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

响应

数据结构
示例

customer object
idstring
顾客的 ID。
emailstring
顾客的邮箱地址。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
phonestring
顾客的电话号码。
tagsundefined[]
对象上的标签。
namestring
顾客的全名。
notestring可空
对象上的备注。
contactstring
顾客的联系方式，邮箱或电话号码。
contact_typestring
联系方式类型，邮箱或电话。
created_bystring
location_idstring
registered_atstring
顾客完成注册的时间。
noted_atstring可空
created_atstring
创建时间（ISO-8601 格式）。
sourcestring
顾客数据的来源。
free_taxstring可空
顾客是否享有税收豁免。
subscribedboolean
顾客是否订阅了营销信息。
registeredboolean
顾客是否已注册账号。
customer_extra_info object
顾客的附加统计信息。
finished_order_countnumber
顾客已完成的订单数。
finished_order_totalstring
顾客已完成订单的总金额。
countrystring可空
country_codestring可空
provincestring可空
地址所在省或州。
province_codestring可空
省或州的代码。
currency_codestring
订单的货币代码，例如 USD。
purchase_product_countnumber
顾客已购买的商品件数。
store_customer_idstring
customer_rolestring可空
extstring可空
first_order_atstring可空
顾客首次下单时间。
last_order_atstring可空
顾客最后一次下单时间。

{
  "customer": {
    "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1 555-0100",
    "tags": [],
    "name": "Jane Doe",
    "note": null,
    "contact": "[email protected]",
    "contact_type": "email",
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T01:03:32Z",
    "noted_at": null,
    "created_at": "2026-09-02T14:13:31Z",
    "source": "newsletter",
    "free_tax": null,
    "subscribed": true,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 0,
      "finished_order_total": "0.0",
      "country": null,
      "country_code": null,
      "province": null,
      "province_code": null,
      "currency_code": "USD",
      "purchase_product_count": 0,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": null,
      "last_order_at": null
    }
  }
}

修改当前顾客资料

PATCH /{locale}/api/customers/update

修改当前已登录顾客的姓名和邮箱地址。需要顾客登录态。email 要与姓名字段一起提交。

请求示例

const body = new URLSearchParams({
  email: '[email protected]',
  first_name: 'Jane',
  last_name: 'Doe'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/update', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

账号的邮箱地址。

first_namestring

顾客的名。

last_namestring

顾客的姓。

响应

数据结构
示例

customer object
emailstring
顾客的邮箱地址。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
phonestring
顾客的电话号码。
idstring
顾客的 ID。
contact_typestring
联系方式类型，邮箱或电话。
contactstring
顾客的联系方式，邮箱或电话号码。
namestring
顾客的全名。
tagsundefined[]
对象上的标签。
notestring可空
对象上的备注。
created_bystring
location_idstring
registered_atstring
顾客完成注册的时间。
noted_atstring可空
created_atstring
创建时间（ISO-8601 格式）。
sourcestring
顾客数据的来源。
free_taxstring可空
顾客是否享有税收豁免。
subscribedboolean
顾客是否订阅了营销信息。
registeredboolean
顾客是否已注册账号。
customer_extra_info object
顾客的附加统计信息。
finished_order_countnumber
顾客已完成的订单数。
finished_order_totalstring
顾客已完成订单的总金额。
countrystring可空
country_codestring可空
provincestring可空
地址所在省或州。
province_codestring可空
省或州的代码。
currency_codestring
订单的货币代码，例如 USD。
purchase_product_countnumber
顾客已购买的商品件数。
store_customer_idstring
customer_rolestring可空
extstring可空
first_order_atstring可空
顾客首次下单时间。
last_order_atstring可空
顾客最后一次下单时间。

{
  "customer": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1 555-0100",
    "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5",
    "contact_type": "email",
    "contact": "[email protected]",
    "name": "Jane Doe",
    "tags": [],
    "note": null,
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T01:03:32Z",
    "noted_at": null,
    "created_at": "2026-09-02T14:13:31Z",
    "source": "newsletter",
    "free_tax": null,
    "subscribed": true,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 0,
      "finished_order_total": "0.0",
      "country": null,
      "country_code": null,
      "province": null,
      "province_code": null,
      "currency_code": "USD",
      "purchase_product_count": 0,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": null,
      "last_order_at": null
    }
  }
}

订阅营销邮件

POST /{locale}/api/customers/newsletters

让一个邮箱地址订阅店铺的营销邮件。匿名访客可以调用。

请求示例

const body = new URLSearchParams({ email: '[email protected]' });

fetch(window.SHOPLAZZA.routes.root + '/api/customers/newsletters', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

emailstring

要订阅的邮箱地址。

响应

数据结构
示例

idstring

完成订阅的顾客 ID。

{
  "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5"
}

获取顾客地址列表

GET /{locale}/api/customers/addresses

获取当前已登录顾客的地址列表。需要顾客登录态。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses?per_page=40')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

per_pagenumber

返回的地址条数。

响应

数据结构
示例

countnumber

返回的地址数量。

addresses object[]

顾客的地址列表。

Array [

idstring

地址的 ID。

first_namestring

顾客或收件人的名。

last_namestring

顾客或收件人的姓。

phonestring可空

与该地址关联的电话号码。

emailstring

与该地址关联的邮箱。

countrystring

地址所在国家的名称。

country_codestring

地址所在国家的 ISO 代码。

provincestring

地址所在省或州。

province_codestring

省或州的代码。

areastring可空

地址所在区域。

citystring

地址所在城市。

companystring可空

地址的公司名称。

zipstring

邮政编码。

genderstring可空

收件人的性别。

phone_area_codestring可空

电话号码的区号。

addressstring

收件人的详细地址。

address1string

详细地址第一行。

is_defaultboolean

是否为顾客的默认地址。

created_atstring

创建时间（ISO-8601 格式）。

]

{
  "count": 1,
  "addresses": [
    {
      "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": null,
      "email": "[email protected]",
      "country": "United States",
      "country_code": "US",
      "province": "California",
      "province_code": "US-CA",
      "area": null,
      "city": "Los Angeles",
      "company": null,
      "zip": "90001",
      "gender": null,
      "phone_area_code": null,
      "address": "123 Main St",
      "address1": "123 Main St",
      "is_default": true,
      "created_at": "2026-09-03T01:07:23Z"
    }
  ]
}

创建地址

POST /{locale}/api/customers/addresses

为当前已登录顾客新增一个地址。需要顾客登录态。country 与 country_code 要一起提交。

请求示例

const body = new URLSearchParams({
  first_name: 'Jane',
  last_name: 'Doe',
  address: '123 Main St',
  address1: 'Apt 4',
  city: 'Los Angeles',
  province: 'California',
  province_code: 'CA',
  country: 'United States',
  country_code: 'US',
  zip: '90001',
  email: '[email protected]',
  is_default: '1'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

first_namestring

收件人的名。

last_namestring

收件人的姓。

addressstring

街道地址第一行。

address1string

街道地址第二行，例如门牌号。

citystring

城市。

provincestring

省/州名称。

province_codestring

省/州代码，例如 CA。

countrystring

国家/地区名称，例如 United States。

country_codestring

国家/地区两位代码，例如 US。

zipstring

邮政编码。

emailstring

收件人的邮箱地址。

is_defaultnumber

是否设为默认地址，取值 1 或 0。

响应

数据结构
示例

address object
idstring
地址的 ID。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
phonestring可空
与该地址关联的电话号码。
emailstring
与该地址关联的邮箱。
countrystring
地址所在国家的名称。
country_codestring
地址所在国家的 ISO 代码。
provincestring
地址所在省或州。
province_codestring
省或州的代码。
areastring可空
地址所在区域。
citystring
地址所在城市。
companystring可空
地址的公司名称。
zipstring
邮政编码。
genderstring可空
收件人的性别。
phone_area_codestring可空
电话号码的区号。
addressstring
收件人的详细地址。
address1string
详细地址第一行。
is_defaultboolean
是否为顾客的默认地址。
created_atstring
创建时间（ISO-8601 格式）。

{
  "address": {
    "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "email": "[email protected]",
    "country": "United States",
    "country_code": "US",
    "province": "California",
    "province_code": "US-CA",
    "area": null,
    "city": "Los Angeles",
    "company": null,
    "zip": "90001",
    "gender": null,
    "phone_area_code": null,
    "address": "123 Main St",
    "address1": "123 Main St",
    "is_default": true,
    "created_at": "2026-09-03T01:07:23Z"
  }
}

查询地址详情

GET /{locale}/api/customers/addresses/{address_id}

获取当前已登录顾客的某一个地址。需要顾客登录态。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

address_idstring

地址的 id。

响应

数据结构
示例

address object
idstring
地址的 ID。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
phonestring可空
与该地址关联的电话号码。
emailstring
与该地址关联的邮箱。
countrystring
地址所在国家的名称。
country_codestring
地址所在国家的 ISO 代码。
provincestring
地址所在省或州。
province_codestring
省或州的代码。
areastring可空
地址所在区域。
citystring
地址所在城市。
companystring可空
地址的公司名称。
zipstring
邮政编码。
genderstring可空
收件人的性别。
phone_area_codestring可空
电话号码的区号。
addressstring
收件人的详细地址。
address1string
详细地址第一行。
is_defaultboolean
是否为顾客的默认地址。
created_atstring
创建时间（ISO-8601 格式）。

{
  "address": {
    "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "email": "[email protected]",
    "country": "United States",
    "country_code": "US",
    "province": "California",
    "province_code": "US-CA",
    "area": null,
    "city": "Los Angeles",
    "company": null,
    "zip": "90001",
    "gender": null,
    "phone_area_code": null,
    "address": "123 Main St",
    "address1": "123 Main St",
    "is_default": true,
    "created_at": "2026-09-03T01:07:23Z"
  }
}

修改地址

PATCH /{locale}/api/customers/addresses/{address_id}

修改当前已登录顾客的某一个地址。需要顾客登录态。country 与 country_code 要一起提交。

请求示例

const body = new URLSearchParams({
  first_name: 'Jane',
  last_name: 'Doe',
  address: '456 Oak Ave',
  city: 'Los Angeles',
  province: 'California',
  province_code: 'CA',
  country: 'United States',
  country_code: 'US',
  zip: '90002'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

address_idstring

地址的 id。

first_namestring

收件人的名。

last_namestring

收件人的姓。

addressstring

街道地址第一行。

citystring

城市。

provincestring

省/州名称。

province_codestring

省/州代码，例如 CA。

countrystring

国家/地区名称，例如 United States。

country_codestring

国家/地区两位代码，例如 US。

zipstring

邮政编码。

响应

数据结构
示例

address object
idstring
地址的 ID。
first_namestring
顾客或收件人的名。
last_namestring
顾客或收件人的姓。
countrystring
地址所在国家的名称。
country_codestring
地址所在国家的 ISO 代码。
provincestring
地址所在省或州。
province_codestring
省或州的代码。
citystring
地址所在城市。
zipstring
邮政编码。
emailstring
与该地址关联的邮箱。
genderstring可空
收件人的性别。
phonestring可空
与该地址关联的电话号码。
areastring可空
地址所在区域。
companystring可空
地址的公司名称。
phone_area_codestring可空
电话号码的区号。
addressstring
收件人的详细地址。
address1string
详细地址第一行。
is_defaultboolean
是否为顾客的默认地址。
created_atstring
创建时间（ISO-8601 格式）。

{
  "address": {
    "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
    "first_name": "Jane",
    "last_name": "Doe",
    "country": "United States",
    "country_code": "US",
    "province": "California",
    "province_code": "US-CA",
    "city": "Los Angeles",
    "zip": "90001",
    "email": "[email protected]",
    "gender": null,
    "phone": null,
    "area": null,
    "company": null,
    "phone_area_code": null,
    "address": "123 Main St",
    "address1": "123 Main St",
    "is_default": true,
    "created_at": "2026-09-03T01:07:23Z"
  }
}

删除地址

DELETE /{locale}/api/customers/addresses/{address_id}

删除当前已登录顾客的某一个地址。需要顾客登录态。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6', {
  method: 'DELETE',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

address_idstring

地址的 id。

响应

数据结构
示例

object

{}

设置默认地址

POST /{locale}/api/customers/addresses/{address_id}/default

把某一个地址设为当前已登录顾客的默认地址。需要顾客登录态。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6/default', {
  method: 'POST',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数

address_idstring

地址的 id。

响应

数据结构
示例

object

{}

获取店铺地址表单配置

GET /{locale}/api/customers/address_settings

获取店铺地址表单的配置：姓名字段如何排布、哪些可选字段展示或隐藏、哪些联系方式字段必填。需要顾客登录态，没有参数。

请求示例

fetch(window.SHOPLAZZA.routes.root + '/api/customers/address_settings')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

响应

数据结构
示例

emailstring

地址表单中邮箱字段的展示设置。

namestring

地址表单中姓名字段的排布方式。

phonestring

地址表单中电话字段的展示设置。

companystring

地址表单中公司字段的展示设置，例如 hidden。

address1string

地址表单中详细地址字段的展示设置。

name_requirementstring

姓名字段中哪一项必填，例如 last_name。

contact_detailsstring

地址表单收集联系方式的方式。

{
  "email": "[email protected]",
  "name": "separate",
  "phone": "+1 555-0100",
  "company": "hidden",
  "address1": "123 Main St",
  "name_requirement": "last_name",
  "contact_details": "multiple"
}

身份要求​

注册顾客账号​

请求示例​

请求参数​

响应​

顾客登录​

请求示例​

请求参数​

响应​

顾客登出​

请求示例​

响应​

发送密码重置邮件​

请求示例​

请求参数​

响应​

重置顾客密码​

请求示例​

请求参数​

响应​

发送登录验证码​

请求示例​

请求参数​

响应​

获取店铺社交登录方式​

请求示例​

响应​

获取当前顾客资料​

请求示例​

响应​

修改当前顾客资料​

请求示例​

请求参数​

响应​

订阅营销邮件​

请求示例​

请求参数​

响应​

获取顾客地址列表​

请求示例​

请求参数​

响应​

创建地址​

请求示例​

请求参数​

响应​

查询地址详情​

请求示例​

请求参数​

响应​

修改地址​

请求示例​

请求参数​

响应​

删除地址​

请求示例​

请求参数​

响应​

设置默认地址​

请求示例​

请求参数​

响应​

获取店铺地址表单配置​

请求示例​

响应​

身份要求

注册顾客账号

请求示例

请求参数

响应

顾客登录

请求示例

请求参数

响应

顾客登出

请求示例

响应

发送密码重置邮件

请求示例

请求参数

响应

重置顾客密码

请求示例

请求参数

响应

发送登录验证码

请求示例

请求参数

响应

获取店铺社交登录方式

请求示例

响应

获取当前顾客资料

请求示例

响应

修改当前顾客资料

请求示例

请求参数

响应

订阅营销邮件

请求示例

请求参数

响应

获取顾客地址列表

请求示例

请求参数

响应

创建地址

请求示例

请求参数

响应

查询地址详情

请求示例

请求参数

响应

修改地址

请求示例

请求参数

响应

删除地址

请求示例

请求参数

响应

设置默认地址

请求示例

请求参数

响应

获取店铺地址表单配置

请求示例

响应