跳到主要内容

订单

Order API 用于在前台 JavaScript 中读取和操作订单。所有带订单 id 的 endpoint 都需要顾客登录态，且只能操作当前登录顾客自己的订单。POST /{locale}/api/order_verify 是例外：它用订单号加订单上的邮箱地址换取订单页地址，匿名访客也可以调用。

下面的示例带了 X-CSRF-Token 请求头，取值方式见身份要求。

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

获取顾客订单列表​

GET /{locale}/api/orders.json

获取当前已登录顾客的订单列表。

请求示例​

fetch(window.SHOPLAZZA.routes.root + '/api/orders.json?page=1&per_page=10')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数​

    pagenumber

    返回第几页订单。

    per_pagenumber

    每页返回的订单数。

响应​

  • order_list object
    countstring

    订单总数。

    orders object[]

    订单列表。

  • Array [
    • idstring

    订单的 ID。

    numberstring

    订单号。

    payment_methodstring

    订单使用的支付方式，例如 credit_card。

    financial_statusstring

    订单的支付状态，例如 waiting、paid。

    fulfillment_statusstring

    发货状态，例如 waiting、shipped、finished。

    statusstring

    订单状态，例如 opened、placed、finished。

    currency_codestring

    订单的货币代码，例如 USD。

    fail_codestring
    shipping_address object

    订单的收货地址。

    addressstring

    收件人的详细地址。

    address1string

    详细地址第一行。

    areastring

    地址所在区域。

    citystring

    地址所在城市。

    companystring

    地址的公司名称。

    countrystring

    地址所在国家的名称。

    country_codestring

    地址所在国家的 ISO 代码。

    emailstring

    与该地址关联的邮箱。

    extra_info object
    object
    first_namestring

    顾客或收件人的名。

    idstring

    地址的 ID。

    last_namestring

    顾客或收件人的姓。

    origin_idstring
    phonestring

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

    phone_area_codestring

    电话号码的区号。

    provincestring

    地址所在省或州。

    province_codestring

    省或州的代码。

    zipstring

    邮政编码。

    post_sale_statusstring

    订单的售后状态。

    create_atstring

    订单创建时间。

    customer_emailstring

    订单顾客的邮箱地址。

    customer_phonestring

    订单顾客的电话号码。

    customer_namestring

    订单顾客的全名。

    customer_idstring

    订单顾客的 ID。

    totalstring

    顾客支付的总金额，含税费、运费与折扣。

    fulfillment_countnumber

    订单已创建的物流记录数。

    create_timestring

    订单创建时间，与 create_at 相同。

    allowed_actions object

    顾客可对该订单执行的操作。

    delete_orderboolean

    订单是否可删除。

    cancel_orderboolean

    订单是否可取消。

    repay_orderboolean

    订单是否可重新支付。

    pay_orderboolean

    订单是否可支付。

    add_to_cartboolean

    订单商品是否可再次加入购物车。

    download_invoiceboolean

    订单是否可下载发票。

    finish_fulfillmentboolean

    顾客是否可确认收货。

    gift_card_totalstring

    订单使用的礼品卡总金额。

    paid_totalstring

    订单已支付的总金额。

    payment_duestring

    订单尚未支付的金额。

    payment_progressnumber

    订单的支付进度，3 表示已付清。

    real_paid_totalstring

    订单的实际支付金额。

    line_items object[]

    行项目列表。

  • Array [
    • compare_at_pricestring

    划线价。

    fulfillment_statusstring

    发货状态，例如 waiting、shipped、finished。

    idstring

    行项目的 ID。

    image object

    行项目所属款式的图片。

    altstring

    图片的替代文本。

    heightnumber

    图片高度（像素）。

    pathstring

    图片文件在图床上的路径。

    srcstring

    图片的地址。

    widthnumber

    图片宽度（像素）。

    notestring

    行项目的备注。

    options object[]

    行项目所属款式的属性取值。

  • Array [
    • namestring

    商品属性名称，例如 Color。

    valuestring

    该商品属性被选中的取值。

  • ]
    • pricestring

    行项目单件商品的价格。

    product_handlestring

    商品的 handle。

    product_idstring

    商品 ID。

    product_titlestring

    商品名称。

    product_urlstring

    商品页的相对地址。

    propertiesstring

    行项目上记录的自定义属性。

    quantitynumber

    商品数量。

    requires_shippingboolean

    是否需要物流配送。

    skustring

    款式的 SKU，用于库存管理。

    taxableboolean

    是否需要计税。

    totalstring

    行项目的总价。

    variant_idstring

    款式 ID。

    variant_titlestring

    款式标题，例如 Blue, Size M。

    vendorstring

    商品的供应商。

    weightstring

    款式的重量。

    weight_unitstring

    重量单位，例如 kg。

    barcodestring

    款式的条形码。

    customboolean

    该行项目是否为自定义商品。

    trunk_pricestring

    行项目的主干价格。

    main_currency_prices object

    订单金额换算成店铺主货币后的结果。

    compare_at_pricestring

    划线价。

    pricestring

    换算成店铺主货币后的单价。

    totalstring

    换算成店铺主货币后的总额。

    trunk_pricestring

    行项目的主干价格。

    actual_ratestring

    换算所用的汇率。

  • ]
    • order_urlstring

    订单页的相对地址。

    checkout_urlstring

    订单结账页的相对地址。

    fulfillmentsundefined[]

    订单的物流记录列表。

    main_currency_prices object

    订单金额换算成店铺主货币后的结果。

    totalstring

    换算成店铺主货币后的总额。

    actual_ratestring

    换算所用的汇率。

    actual_rate_showstring
    order_typenumber

    订单类型，0 为普通订单，1 为礼品卡订单。

  • ]

查询订单详情​

GET /{locale}/api/orders/{order_id}.json

获取当前已登录顾客的某一个订单，包含地址、行项目和金额。

请求示例​

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

请求参数​

    order_idstring

    订单的 id。

响应​

  • order object
    billing_address object

    订单的账单地址。

    addressstring

    收件人的详细地址。

    address1string

    详细地址第一行。

    areastring

    地址所在区域。

    citystring

    地址所在城市。

    countrystring

    地址所在国家的名称。

    country_codestring

    地址所在国家的 ISO 代码。

    emailstring

    与该地址关联的邮箱。

    first_namestring

    顾客或收件人的名。

    idstring

    地址的 ID。

    last_namestring

    顾客或收件人的姓。

    origin_idstring
    provincestring

    地址所在省或州。

    province_codestring

    省或州的代码。

    zipstring

    邮政编码。

    phonestring

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

    phone_area_codestring

    电话号码的区号。

    customer object

    顾客详情。

    customer_idstring

    订单顾客的 ID。

    emailstring

    顾客的邮箱地址。

    first_namestring

    顾客或收件人的名。

    last_namestring

    顾客或收件人的姓。

    namestring

    顾客的全名。

    order_countnumber

    顾客的订单数量。

    phonestring

    顾客的电话号码。

    user_idstring
    line_items object[]

    行项目列表。

  • Array [
    • compare_at_pricestring

    划线价。

    fulfillment_statusstring

    发货状态，例如 waiting、shipped、finished。

    idstring

    行项目的 ID。

    image object

    行项目所属款式的图片。

    altstring

    图片的替代文本。

    heightnumber

    图片高度（像素）。

    pathstring

    图片文件在图床上的路径。

    srcstring

    图片的地址。

    widthnumber

    图片宽度（像素）。

    notestring

    行项目的备注。

    options object[]

    行项目所属款式的属性取值。

  • Array [
    • namestring

    商品属性名称，例如 Color。

    valuestring

    该商品属性被选中的取值。

  • ]
    • pricestring

    行项目单件商品的价格。

    product_handlestring

    商品的 handle。

    product_idstring

    商品 ID。

    product_titlestring

    商品名称。

    product_urlstring

    商品页的相对地址。

    propertiesstring

    行项目上记录的自定义属性。

    quantitynumber

    商品数量。

    requires_shippingboolean

    是否需要物流配送。

    skustring

    款式的 SKU，用于库存管理。

    taxableboolean

    是否需要计税。

    totalstring

    行项目的总价。

    variant_idstring

    款式 ID。

    variant_titlestring

    款式标题，例如 Blue, Size M。

    vendorstring

    商品的供应商。

    weightstring

    款式的重量。

    weight_unitstring

    重量单位，例如 kg。

    barcodestring

    款式的条形码。

    customboolean

    该行项目是否为自定义商品。

    trunk_pricestring

    行项目的主干价格。

    shipping_statusstring

    行项目的发货状态。

    main_currency_prices object

    订单金额换算成店铺主货币后的结果。

    compare_at_pricestring

    划线价。

    pricestring

    换算成店铺主货币后的单价。

    totalstring

    换算成店铺主货币后的总额。

    trunk_pricestring

    行项目的主干价格。

    actual_ratestring

    换算所用的汇率。

    discount_totalstring

    折扣总额。

    tax_totalstring

    订单的税费总额。

    discount_detailsundefined[]
    final_pricestring

    应用行级折扣后，该行项目单件商品的价格。

    final_totalstring

    订单的最终总额。

    is_free_giftboolean

    该商品是否为赠品。

    duty_pricestring

    行项目的关税费用。

  • ]
    • order_info object

    订单的概要信息。

    code_discount_totalstring

    订单中优惠码带来的折扣总额。

    configstring

    订单的配置信息。

    create_timestring

    订单创建时间，与 create_at 相同。

    currency_codestring

    订单的货币代码，例如 USD。

    customer_notestring

    顾客在结账时填写的备注。

    discount_applicationsstring

    该对象已应用的折扣。

    discount_codestring

    订单使用的优惠码。

    discount_totalstring

    折扣总额。

    fail_codestring
    financial_statusstring

    订单的支付状态，例如 waiting、paid。

    fulfillment_statusstring

    发货状态，例如 waiting、shipped、finished。

    idstring

    订单的 ID。

    line_item_discount_totalstring

    订单行项目的折扣总额。

    notestring

    商家为订单添加的备注。

    order_nostring

    订单号。

    post_sale_statusstring

    订单的售后状态。

    refer_info object

    顾客访问来源信息。

    address_checkboolean
    client_idstring
    countrystring
    customer_sessionstring
    domainstring
    fbcstring
    fbpstring
    inventory_deductionstring
    ipstring

    访客的 IP 地址。

    segstring
    session_idstring
    sourcestring
    user_agentstring
    shipping_address_editableboolean

    收货地址是否仍可修改。

    shipping_totalstring

    订单的运费总额。

    statusstring

    订单状态，例如 opened、placed、finished。

    sub_totalstring

    应用订单级折扣前，所有行项目价格的总和。

    tax_totalstring

    订单的税费总额。

    totalstring

    顾客支付的总金额，含税费、运费与折扣。

    updated_atstring

    最后更新时间（ISO-8601 格式）。

    total_tip_receivedstring

    订单收到的小费总额。

    cancelableboolean

    订单是否还能取消。

    create_atstring

    订单创建时间。

    gift_card_totalstring

    订单使用的礼品卡总金额。

    paid_totalstring

    订单已支付的总金额。

    payment_duestring

    订单尚未支付的金额。

    payment_progressnumber

    订单的支付进度，3 表示已付清。

    real_paid_totalstring

    订单的实际支付金额。

    checkout_urlstring

    订单结账页的相对地址。

    order_urlstring

    订单页的相对地址。

    main_currency_prices object

    订单金额换算成店铺主货币后的结果。

    sub_totalstring

    应用订单级折扣前，所有行项目价格的总和。

    shipping_totalstring

    订单的运费总额。

    tax_totalstring

    订单的税费总额。

    discount_totalstring

    折扣总额。

    totalstring

    换算成店铺主货币后的总额。

    total_tip_receivedstring

    订单收到的小费总额。

    actual_ratestring

    换算所用的汇率。

    actual_rate_showstring
    final_totalstring

    订单的最终总额。

    order_typenumber

    订单类型，0 为普通订单，1 为礼品卡订单。

    shipping_tax_typenumber
    shipping_tax_totalstring

    订单的运费税总额。

    product_tax_includedboolean

    商品价格是否含税。

    additional_totalstring

    订单的附加费用总额。

    additional_prices object

    附加费用明细。

    object
    tax_linesundefined[]

    订单的税费明细。

    duty_totalstring

    订单的关税税费总额。

    payment_line object

    订单的支付详情。

    namestring

    支付方式的展示名称。

    channelstring

    处理该笔支付的支付渠道。

    methodstring

    本次支付使用的支付网关。

    credit_card_numberstring

    支付所用银行卡的尾号。

    transaction_idstring

    支付的交易流水号。

    paid_totalstring

    通过该支付方式支付的金额。

    extra_infostring
    real_paid_totalstring

    通过该支付方式实际支付的金额。

    shipping_address object

    订单的收货地址。

    addressstring

    收件人的详细地址。

    address1string

    详细地址第一行。

    areastring

    地址所在区域。

    citystring

    地址所在城市。

    companystring

    地址的公司名称。

    countrystring

    地址所在国家的名称。

    country_codestring

    地址所在国家的 ISO 代码。

    emailstring

    与该地址关联的邮箱。

    extra_info object
    object
    first_namestring

    顾客或收件人的名。

    idstring

    地址的 ID。

    last_namestring

    顾客或收件人的姓。

    origin_idstring
    phonestring

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

    phone_area_codestring

    电话号码的区号。

    provincestring

    地址所在省或州。

    province_codestring

    省或州的代码。

    zipstring

    邮政编码。

    shipping_linestring

    订单所选的物流方案。

    allowed_actions object

    顾客可对该订单执行的操作。

    delete_orderboolean

    订单是否可删除。

    cancel_orderboolean

    订单是否可取消。

    repay_orderboolean

    订单是否可重新支付。

    pay_orderboolean

    订单是否可支付。

    add_to_cartboolean

    订单商品是否可再次加入购物车。

    download_invoiceboolean

    订单是否可下载发票。

    finish_fulfillmentboolean

    顾客是否可确认收货。

    payment_lines object[]

    订单的支付记录列表。

  • Array [
    • namestring

    支付方式的展示名称。

    channelstring

    处理该笔支付的支付渠道。

    methodstring

    本次支付使用的支付网关。

    credit_card_numberstring

    支付所用银行卡的尾号。

    transaction_idstring

    支付的交易流水号。

    paid_totalstring

    通过该支付方式支付的金额。

    extra_infostring
    real_paid_totalstring

    通过该支付方式实际支付的金额。

  • ]
    • location_line object

    商家仓库地址。

    location_idstring

    仓库 ID。

    location_namestring

    仓库名称。

    first_namestring

    顾客或收件人的名。

    last_namestring

    顾客或收件人的姓。

    phonestring

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

    emailstring

    与该地址关联的邮箱。

    countrystring

    地址所在国家的名称。

    country_codestring

    地址所在国家的 ISO 代码。

    provincestring

    地址所在省或州。

    province_codestring

    省或州的代码。

    areastring

    地址所在区域。

    citystring

    地址所在城市。

    addressstring

    收件人的详细地址。

    address1string

    详细地址第一行。

    companystring

    地址的公司名称。

    latitudestring

    地址的纬度。

    longitudestring

    地址的经度。

    zipstring

    邮政编码。

    phone_area_codestring

    电话号码的区号。

    extra_infostring
    shipping_line_info object

    订单所选物流方案的详情。

    namestring

    物流方案的名称。

    descstring

    物流方案的描述。

    delivery_methodnumber

    配送方式类型，1 为快递配送，2 为本地配送。

    extra_infostring

取消订单​

PATCH /{locale}/api/orders/{order_id}/cancel.json

取消当前已登录顾客的某一个订单。

请求示例​

fetch(window.SHOPLAZZA.routes.root + '/api/orders/2446407211602194455359/cancel.json', {
  method: 'PATCH',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数​

    order_idstring

    订单的 id。

响应​

    object

确认订单收货​

PATCH /{locale}/api/orders/{order_id}/confirm_receipt.json

确认当前已登录顾客已收到该订单。

请求示例​

fetch(window.SHOPLAZZA.routes.root + '/api/orders/2446407211602194455359/confirm_receipt.json', {
  method: 'PATCH',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数​

    order_idstring

    订单的 id。

响应​

    object

获取订单发货记录​

GET /{locale}/api/orders/{order_id}/fulfillments.json

获取当前已登录顾客某一个订单的发货记录，包含运单号、承运商和行项目。

请求示例​

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

请求参数​

    order_idstring

    订单的 id。

响应​

    countstring

    返回的物流记录数量。

    fulfillments object[]

    订单的物流记录列表。

  • Array [
    • idstring

    物流记录的 ID。

    retrieve_methodstring
    tracking_numberstring

    运单号。

    tracking_companystring

    承运的物流商。

    tracking_company_codestring

    物流商编码。

    statusstring

    物流记录的状态，例如 shipped、finished。

    line_items object[]

    本次发货包含的行项目。

  • Array [
    • idstring

    行项目的 ID。

    product_titlestring

    商品名称。

    product_idstring

    商品 ID。

    product_handlestring

    商品的 handle。

    variant_idstring

    款式 ID。

    variant_titlestring

    款式标题，例如 Blue, Size M。

    quantitynumber

    商品数量。

    fulfillment_statusstring

    发货状态，例如 waiting、shipped、finished。

    notestring

    行项目的备注。

    image object

    行项目所属款式的图片。

    altstring

    图片的替代文本。

    heightnumber

    图片高度（像素）。

    pathstring

    图片文件在图床上的路径。

    srcstring

    图片的地址。

    widthnumber

    图片宽度（像素）。

    compare_at_pricestring

    划线价。

    pricestring

    行项目单件商品的价格。

    totalstring

    行项目的总价。

    skustring

    款式的 SKU，用于库存管理。

    weightstring

    款式的重量。

    weight_unitstring

    重量单位，例如 kg。

    taxableboolean

    是否需要计税。

    requires_shippingboolean

    是否需要物流配送。

    options object[]

    行项目所属款式的属性取值。

  • Array [
    • namestring

    商品属性名称，例如 Color。

    valuestring

    该商品属性被选中的取值。

  • ]
    • vendorstring

    商品的供应商。

    product_urlstring

    商品页的相对地址。

    propertiesstring

    行项目上记录的自定义属性。

    ship_quantitynumber

    本次发货的数量。

  • ]
    • tracking_company_code_v1string
    tracking_urlstring

    物流跟踪链接。

  • ]

确认单次发货收货​

PATCH /{locale}/api/orders/{order_id}/fulfillments/{fulfillment_id}/finish.json

确认当前已登录顾客已收到订单中的某一次发货。

请求示例​

fetch(
  window.SHOPLAZZA.routes.root +
    '/api/orders/2446407211602194455359/fulfillments/8dc782af-4ee6-4a0a-804a-e96227673b32/finish.json',
  {
    method: 'PATCH',
    headers: {
      'X-CSRF-Token': getCsrfToken()
    }
  }
)
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数​

    order_idstring

    订单的 id。

    fulfillment_idstring

    发货记录的 id。

响应​

    fulfillmentstring可空

请求删除订单​

DELETE /{locale}/api/orders/{order_id}.json

请求示例​

fetch(window.SHOPLAZZA.routes.root + '/api/orders/2446407211602194455359.json', {
  method: 'DELETE',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数​

    order_idstring

    订单的 id。

响应​

    object

免登录获取订单页地址​

POST /{locale}/api/order_verify

用订单号加订单上的邮箱地址换取订单页地址。匿名访客可以调用，前台的订单查询表单就用它。请求体为 application/x-www-form-urlencoded。

请求示例​

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

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

请求参数​

    order_numberstring

    订单号，例如 KSR43063。

    emailstring

    订单上的邮箱地址。

响应​

    actionstring

    请求结果，例如 Success 或 Unauthorized。

    valuestring

    顾客被跳转到的相对地址。

按运单号查询物流轨迹​

GET /{locale}/api/tracking/package

按运单号获取包裹的承运商物流状态。

请求示例​

fetch(window.SHOPLAZZA.routes.root + '/api/tracking/package?tracking_number=AJAXPROBE0001')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

请求参数​

    tracking_numberstring

    包裹的运单号。

响应​

    meta object

    查询结果的元信息。

    codenumber

    查询结果的状态码。

    typestring

    查询结果的类型，例如 Success。

    messagestring

    查询结果的说明。

    data object

    响应数据主体。

    items object[]

    被查询的包裹列表。

  • Array [
    • tracking_numberstring

    运单号。

    carrier_codestring

    承运该包裹的物流商编码。

    lastEventstring
    lastUpdateTimestring
    substatusstring
    origin_info object
    carrier_codestring

    承运该包裹的物流商编码。

    ItemReceivedstring
    trackinfostring可空
  • ]