# 订单 Order API 用于在前台 JavaScript 中读取和操作订单。所有带订单 id 的 endpoint 都需要顾客登录态，且只能操作当前登录顾客自己的订单。`POST /{locale}/api/order_verify` 是例外：它用订单号加订单上的邮箱地址换取订单页地址，匿名访客也可以调用。 除 `GET` 以外的请求都要带 `X-CSRF-Token` 请求头，取值方式见[身份要求](/zh-CN/docs/theme/references/ajax-api/customer#%E8%BA%AB%E4%BB%BD%E8%A6%81%E6%B1%82)。 所有 Ajax API 请求应使用[多语言 URL](/zh-CN/docs/theme/references/ajax-api/#locale-aware-urls)，以便为访客提供一致的体验。 ## 获取顾客订单列表 ```text GET /{locale}/api/orders.json ``` 获取当前已登录顾客的订单列表。 ### 请求示例 **请求示例** ```javascript fetch(window.SHOPLAZZA.routes.root + '/api/orders.json?page=1&per_page=10') .then((response) => response.json()) .then((data) => { // do something... }); ``` ### 请求参数 - `page` number 返回第几页订单。 - `per_page` number 每页返回的订单数。 ### 响应 **数据结构 | 示例** - `order_list` object - `count` string 订单总数。 - `orders` object[] 订单列表。 * Array \[ - `id` string 订单的 ID。 - `number` string 订单号。 - `payment_method` string 订单使用的支付方式，例如 `credit_card`。 - `financial_status` string 订单的支付状态，例如 `waiting`、`paid`。 - `fulfillment_status` string 发货状态，例如 `waiting`、`shipped`、`finished`。 - `status` string 订单状态，例如 `opened`、`placed`、`finished`。 - `currency_code` string 订单的货币代码，例如 `USD`。 - `fail_code` string - `shipping_address` object 订单的收货地址。 - `address` string 收件人的详细地址。 - `address1` string 详细地址第一行。 - `area` string 地址所在区域。 - `city` string 地址所在城市。 - `company` string 地址的公司名称。 - `country` string 地址所在国家的名称。 - `country_code` string 地址所在国家的 ISO 代码。 - `email` string 与该地址关联的邮箱。 - `extra_info` object - `` object - `first_name` string 顾客或收件人的名。 - `id` string 地址的 ID。 - `last_name` string 顾客或收件人的姓。 - `origin_id` string - `phone` string 与该地址关联的电话号码。 - `phone_area_code` string 电话号码的区号。 - `province` string 地址所在省或州。 - `province_code` string 省或州的代码。 - `zip` string 邮政编码。 - `post_sale_status` string 订单的售后状态。 - `create_at` string 订单创建时间。 - `customer_email` string 订单顾客的邮箱地址。 - `customer_phone` string 订单顾客的电话号码。 - `customer_name` string 订单顾客的全名。 - `customer_id` string 订单顾客的 ID。 - `total` string 顾客支付的总金额，含税费、运费与折扣。 - `fulfillment_count` number 订单已创建的物流记录数。 - `create_time` string 订单创建时间，与 `create_at` 相同。 - `allowed_actions` object 顾客可对该订单执行的操作。 - `delete_order` boolean 订单是否可删除。 - `cancel_order` boolean 订单是否可取消。 - `repay_order` boolean 订单是否可重新支付。 - `pay_order` boolean 订单是否可支付。 - `add_to_cart` boolean 订单商品是否可再次加入购物车。 - `download_invoice` boolean 订单是否可下载发票。 - `finish_fulfillment` boolean 顾客是否可确认收货。 - `gift_card_total` string 订单使用的礼品卡总金额。 - `paid_total` string 订单已支付的总金额。 - `payment_due` string 订单尚未支付的金额。 - `payment_progress` number 订单的支付进度，`3` 表示已付清。 - `real_paid_total` string 订单的实际支付金额。 - `line_items` object[] 行项目列表。 * Array \[ - `compare_at_price` string 划线价。 - `fulfillment_status` string 发货状态，例如 `waiting`、`shipped`、`finished`。 - `id` string 行项目的 ID。 - `image` object 行项目所属款式的图片。 - `alt` string 图片的替代文本。 - `height` number 图片高度（像素）。 - `path` string 图片文件在图床上的路径。 - `src` string 图片的地址。 - `width` number 图片宽度（像素）。 - `note` string 行项目的备注。 - `options` object[] 行项目所属款式的属性取值。 * Array \[ - `name` string 商品属性名称，例如 `Color`。 - `value` string 该商品属性被选中的取值。 * \] - `price` string 行项目单件商品的价格。 - `product_handle` string 商品的 handle。 - `product_id` string 商品 ID。 - `product_title` string 商品名称。 - `product_url` string 商品页的相对地址。 - `properties` string 行项目上记录的自定义属性。 - `quantity` number 商品数量。 - `requires_shipping` boolean 是否需要物流配送。 - `sku` string 款式的 SKU，用于库存管理。 - `taxable` boolean 是否需要计税。 - `total` string 行项目的总价。 - `variant_id` string 款式 ID。 - `variant_title` string 款式标题，例如 `Blue, Size M`。 - `vendor` string 商品的供应商。 - `weight` string 款式的重量。 - `weight_unit` string 重量单位，例如 `kg`。 - `barcode` string 款式的条形码。 - `custom` boolean 该行项目是否为自定义商品。 - `trunk_price` string 行项目的主干价格。 - `main_currency_prices` object 订单金额换算成店铺主货币后的结果。 - `compare_at_price` string 划线价。 - `price` string 换算成店铺主货币后的单价。 - `total` string 换算成店铺主货币后的总额。 - `trunk_price` string 行项目的主干价格。 - `actual_rate` string 换算所用的汇率。 * \] - `order_url` string 订单页的相对地址。 - `checkout_url` string 订单结账页的相对地址。 - `fulfillments` undefined[] 订单的物流记录列表。 - `main_currency_prices` object 订单金额换算成店铺主货币后的结果。 - `total` string 换算成店铺主货币后的总额。 - `actual_rate` string 换算所用的汇率。 - `actual_rate_show` string - `order_type` number 订单类型，`0` 为普通订单，`1` 为礼品卡订单。 * \] ```json { "order_list": { "count": "2", "orders": [ { "id": "2446407211602194455359", "number": "KSR43063", "payment_method": "bogus_gateway", "financial_status": "paid", "fulfillment_status": "waiting", "status": "placed", "currency_code": "USD", "fail_code": "", "shipping_address": { "address": "123 Main St", "address1": "123 Main St", "area": "", "city": "Los Angeles", "company": "", "country": "United States", "country_code": "US", "email": "jane@example.com", "extra_info": {}, "first_name": "Jane", "id": "f1871eb3-5baa-47ba-bfce-783601c6e925", "last_name": "Doe", "origin_id": "6ca9fa54-8bfc-461f-9364-0fd104858990", "phone": "+1 555-0100", "phone_area_code": "", "province": "California", "province_code": "US-CA", "zip": "90001" }, "post_sale_status": "none", "create_at": "2026-09-03T02:23:14Z", "customer_email": "jane@example.com", "customer_phone": "+1 555-0100", "customer_name": "Jane Probe", "customer_id": "e1773fff-2b71-42c5-bf63-fc93e6e5b3c5", "total": "2.00", "fulfillment_count": 0, "create_time": "2026-09-03T02:23:14Z", "allowed_actions": { "delete_order": false, "cancel_order": false, "repay_order": false, "pay_order": false, "add_to_cart": false, "download_invoice": false, "finish_fulfillment": false }, "gift_card_total": "0.00", "paid_total": "2.00", "payment_due": "0.00", "payment_progress": 3, "real_paid_total": "2.00", "line_items": [ { "compare_at_price": "1.00", "fulfillment_status": "waiting", "id": "b56596b5-3e36-418b-9098-c7099da3beb2", "image": { "alt": "", "height": 1500, "path": "free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "src": "//img.staticdj.com/free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "width": 3000 }, "note": "", "options": [ { "name": "Size", "value": "01" } ], "price": "1.00", "product_handle": "sample-product", "product_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc", "product_title": "sample-product", "product_url": "/products/sample-product", "properties": "{}", "quantity": 1, "requires_shipping": true, "sku": "", "taxable": false, "total": "1.00", "variant_id": "fff360dd-6457-466a-98b3-16878bacef5b", "variant_title": "01", "vendor": "", "weight": "0.00", "weight_unit": "kg", "barcode": "", "custom": false, "trunk_price": "1.00", "main_currency_prices": { "compare_at_price": "1", "price": "1", "total": "1", "trunk_price": "1", "actual_rate": "1" } } ], "order_url": "/order/2446407211602194455359", "checkout_url": "/checkout/2446407211602194455359?key=082bf85a7f94752154bfd18f96d828", "fulfillments": [], "main_currency_prices": { "total": "2", "actual_rate": "1", "actual_rate_show": "" }, "order_type": 0 }, { "id": "2446407211542406852662", "number": "ZYL16546", "payment_method": "bogus_gateway", "financial_status": "paid", "fulfillment_status": "waiting", "status": "placed", "currency_code": "USD", "fail_code": "", "shipping_address": { "address": "123 Main St", "address1": "123 Main St", "area": "", "city": "Los Angeles", "company": "", "country": "United States", "country_code": "US", "email": "jane@example.com", "extra_info": {}, "first_name": "Jane", "id": "d3e95a5d-5e50-406b-8077-61a5fd292add", "last_name": "Doe", "origin_id": "b1ebe1da-4113-4630-80cb-7dc30cf2a5b3", "phone": "+1 555-0100", "phone_area_code": "", "province": "California", "province_code": "US-CA", "zip": "90001" }, "post_sale_status": "none", "create_at": "2026-09-02T09:46:46Z", "customer_email": "jane@example.com", "customer_phone": "+1 555-0100", "customer_name": "Jane Probe", "customer_id": "e1773fff-2b71-42c5-bf63-fc93e6e5b3c5", "total": "31.00", "fulfillment_count": 0, "create_time": "2026-09-02T09:46:46Z", "allowed_actions": { "delete_order": false, "cancel_order": false, "repay_order": false, "pay_order": false, "add_to_cart": false, "download_invoice": false, "finish_fulfillment": false }, "gift_card_total": "0.00", "paid_total": "31.00", "payment_due": "0.00", "payment_progress": 3, "real_paid_total": "31.00", "line_items": [ { "compare_at_price": "1.00", "fulfillment_status": "waiting", "id": "9c775cb0-b818-4d95-86bc-dda220fd7519", "image": { "alt": "", "height": 1500, "path": "free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "src": "//img.staticdj.com/free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "width": 3000 }, "note": "", "options": [ { "name": "Size", "value": "01" } ], "price": "1.00", "product_handle": "sample-product", "product_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc", "product_title": "sample-product", "product_url": "/products/sample-product", "properties": "{}", "quantity": 1, "requires_shipping": true, "sku": "", "taxable": false, "total": "1.00", "variant_id": "fff360dd-6457-466a-98b3-16878bacef5b", "variant_title": "01", "vendor": "", "weight": "0.00", "weight_unit": "kg", "barcode": "", "custom": false, "trunk_price": "1.00", "main_currency_prices": { "compare_at_price": "1", "price": "1", "total": "1", "trunk_price": "1", "actual_rate": "1" } }, { "compare_at_price": "20.00", "fulfillment_status": "waiting", "id": "b534c4d6-1532-432f-8a24-b90ded1d88fd", "image": { "alt": "", "height": 1254, "path": "50fa9b8c054f4d11b0d765de5f35dd4e.png", "src": "//img.staticdj.com/50fa9b8c054f4d11b0d765de5f35dd4e.png", "width": 1254 }, "note": "", "options": [ { "name": "Color", "value": "Black" }, { "name": "Size", "value": "S" } ], "price": "10.00", "product_handle": "Sample product", "product_id": "b3b656ae-504f-4f01-a054-879a610925e3", "product_title": "Sample product", "product_url": "/products/Sample product", "properties": "{}", "quantity": 2, "requires_shipping": true, "sku": "1111-BLACK-S-A001001", "taxable": false, "total": "20.00", "variant_id": "0699bc80-19ae-41bb-87c4-dbcbe5ed90a0", "variant_title": "Black-S", "vendor": "", "weight": "0.00", "weight_unit": "kg", "barcode": "", "custom": false, "trunk_price": "10.00", "main_currency_prices": { "compare_at_price": "20", "price": "10", "total": "20", "trunk_price": "10", "actual_rate": "1" } } ], "order_url": "/order/2446407211542406852662", "checkout_url": "/checkout/2446407211542406852662?key=5dc2a127c14c578bc05bd30ba0e096", "fulfillments": [], "main_currency_prices": { "total": "31", "actual_rate": "1", "actual_rate_show": "" }, "order_type": 0 } ] } } ``` ## 查询订单详情 ```text GET /{locale}/api/orders/{order_id}.json ``` 获取当前已登录顾客的某一个订单，包含地址、行项目和金额。 ### 请求示例 **请求示例** ```javascript fetch(window.SHOPLAZZA.routes.root + '/api/orders/2446407211602194455359.json') .then((response) => response.json()) .then((data) => { // do something... }); ``` ### 请求参数 - `order_id` string 订单的 id。 ### 响应 **数据结构 | 示例** - `order` object - `billing_address` object 订单的账单地址。 - `address` string 收件人的详细地址。 - `address1` string 详细地址第一行。 - `area` string 地址所在区域。 - `city` string 地址所在城市。 - `country` string 地址所在国家的名称。 - `country_code` string 地址所在国家的 ISO 代码。 - `email` string 与该地址关联的邮箱。 - `first_name` string 顾客或收件人的名。 - `id` string 地址的 ID。 - `last_name` string 顾客或收件人的姓。 - `origin_id` string - `province` string 地址所在省或州。 - `province_code` string 省或州的代码。 - `zip` string 邮政编码。 - `phone` string 与该地址关联的电话号码。 - `phone_area_code` string 电话号码的区号。 - `customer` object 顾客详情。 - `customer_id` string 订单顾客的 ID。 - `email` string 顾客的邮箱地址。 - `first_name` string 顾客或收件人的名。 - `last_name` string 顾客或收件人的姓。 - `name` string 顾客的全名。 - `order_count` number 顾客的订单数量。 - `phone` string 顾客的电话号码。 - `user_id` string - `line_items` object[] 行项目列表。 * Array \[ - `compare_at_price` string 划线价。 - `fulfillment_status` string 发货状态，例如 `waiting`、`shipped`、`finished`。 - `id` string 行项目的 ID。 - `image` object 行项目所属款式的图片。 - `alt` string 图片的替代文本。 - `height` number 图片高度（像素）。 - `path` string 图片文件在图床上的路径。 - `src` string 图片的地址。 - `width` number 图片宽度（像素）。 - `note` string 行项目的备注。 - `options` object[] 行项目所属款式的属性取值。 * Array \[ - `name` string 商品属性名称，例如 `Color`。 - `value` string 该商品属性被选中的取值。 * \] - `price` string 行项目单件商品的价格。 - `product_handle` string 商品的 handle。 - `product_id` string 商品 ID。 - `product_title` string 商品名称。 - `product_url` string 商品页的相对地址。 - `properties` string 行项目上记录的自定义属性。 - `quantity` number 商品数量。 - `requires_shipping` boolean 是否需要物流配送。 - `sku` string 款式的 SKU，用于库存管理。 - `taxable` boolean 是否需要计税。 - `total` string 行项目的总价。 - `variant_id` string 款式 ID。 - `variant_title` string 款式标题，例如 `Blue, Size M`。 - `vendor` string 商品的供应商。 - `weight` string 款式的重量。 - `weight_unit` string 重量单位，例如 `kg`。 - `barcode` string 款式的条形码。 - `custom` boolean 该行项目是否为自定义商品。 - `trunk_price` string 行项目的主干价格。 - `shipping_status` string 行项目的发货状态。 - `main_currency_prices` object 订单金额换算成店铺主货币后的结果。 - `compare_at_price` string 划线价。 - `price` string 换算成店铺主货币后的单价。 - `total` string 换算成店铺主货币后的总额。 - `trunk_price` string 行项目的主干价格。 - `actual_rate` string 换算所用的汇率。 - `discount_total` string 折扣总额。 - `tax_total` string 订单的税费总额。 - `discount_details` undefined[] - `final_price` string 应用行级折扣后，该行项目单件商品的价格。 - `final_total` string 订单的最终总额。 - `is_free_gift` boolean 该商品是否为赠品。 - `duty_price` string 行项目的关税费用。 * \] - `order_info` object 订单的概要信息。 - `code_discount_total` string 订单中优惠码带来的折扣总额。 - `config` string 订单的配置信息。 - `create_time` string 订单创建时间，与 `create_at` 相同。 - `currency_code` string 订单的货币代码，例如 `USD`。 - `customer_note` string 顾客在结账时填写的备注。 - `discount_applications` string 该对象已应用的折扣。 - `discount_code` string 订单使用的优惠码。 - `discount_total` string 折扣总额。 - `fail_code` string - `financial_status` string 订单的支付状态，例如 `waiting`、`paid`。 - `fulfillment_status` string 发货状态，例如 `waiting`、`shipped`、`finished`。 - `id` string 订单的 ID。 - `line_item_discount_total` string 订单行项目的折扣总额。 - `note` string 商家为订单添加的备注。 - `order_no` string 订单号。 - `post_sale_status` string 订单的售后状态。 - `refer_info` object 顾客访问来源信息。 - `address_check` boolean - `client_id` string - `country` string - `customer_session` string - `domain` string - `fbc` string - `fbp` string - `inventory_deduction` string - `ip` string 访客的 IP 地址。 - `seg` string - `session_id` string - `source` string - `user_agent` string - `shipping_address_editable` boolean 收货地址是否仍可修改。 - `shipping_total` string 订单的运费总额。 - `status` string 订单状态，例如 `opened`、`placed`、`finished`。 - `sub_total` string 应用订单级折扣前，所有行项目价格的总和。 - `tax_total` string 订单的税费总额。 - `total` string 顾客支付的总金额，含税费、运费与折扣。 - `updated_at` string 最后更新时间（ISO-8601 格式）。 - `total_tip_received` string 订单收到的小费总额。 - `cancelable` boolean 订单是否还能取消。 - `create_at` string 订单创建时间。 - `gift_card_total` string 订单使用的礼品卡总金额。 - `paid_total` string 订单已支付的总金额。 - `payment_due` string 订单尚未支付的金额。 - `payment_progress` number 订单的支付进度，`3` 表示已付清。 - `real_paid_total` string 订单的实际支付金额。 - `checkout_url` string 订单结账页的相对地址。 - `order_url` string 订单页的相对地址。 - `main_currency_prices` object 订单金额换算成店铺主货币后的结果。 - `sub_total` string 应用订单级折扣前，所有行项目价格的总和。 - `shipping_total` string 订单的运费总额。 - `tax_total` string 订单的税费总额。 - `discount_total` string 折扣总额。 - `total` string 换算成店铺主货币后的总额。 - `total_tip_received` string 订单收到的小费总额。 - `actual_rate` string 换算所用的汇率。 - `actual_rate_show` string - `final_total` string 订单的最终总额。 - `order_type` number 订单类型，`0` 为普通订单，`1` 为礼品卡订单。 - `shipping_tax_type` number - `shipping_tax_total` string 订单的运费税总额。 - `product_tax_included` boolean 商品价格是否含税。 - `additional_total` string 订单的附加费用总额。 - `additional_prices` object 附加费用明细。 - `` object - `tax_lines` undefined[] 订单的税费明细。 - `duty_total` string 订单的关税税费总额。 - `payment_line` object 订单的支付详情。 - `name` string 支付方式的展示名称。 - `channel` string 处理该笔支付的支付渠道。 - `method` string 本次支付使用的支付网关。 - `credit_card_number` string 支付所用银行卡的尾号。 - `transaction_id` string 支付的交易流水号。 - `paid_total` string 通过该支付方式支付的金额。 - `extra_info` string - `real_paid_total` string 通过该支付方式实际支付的金额。 - `shipping_address` object 订单的收货地址。 - `address` string 收件人的详细地址。 - `address1` string 详细地址第一行。 - `area` string 地址所在区域。 - `city` string 地址所在城市。 - `company` string 地址的公司名称。 - `country` string 地址所在国家的名称。 - `country_code` string 地址所在国家的 ISO 代码。 - `email` string 与该地址关联的邮箱。 - `extra_info` object - `` object - `first_name` string 顾客或收件人的名。 - `id` string 地址的 ID。 - `last_name` string 顾客或收件人的姓。 - `origin_id` string - `phone` string 与该地址关联的电话号码。 - `phone_area_code` string 电话号码的区号。 - `province` string 地址所在省或州。 - `province_code` string 省或州的代码。 - `zip` string 邮政编码。 - `shipping_line` string 订单所选的物流方案。 - `allowed_actions` object 顾客可对该订单执行的操作。 - `delete_order` boolean 订单是否可删除。 - `cancel_order` boolean 订单是否可取消。 - `repay_order` boolean 订单是否可重新支付。 - `pay_order` boolean 订单是否可支付。 - `add_to_cart` boolean 订单商品是否可再次加入购物车。 - `download_invoice` boolean 订单是否可下载发票。 - `finish_fulfillment` boolean 顾客是否可确认收货。 - `payment_lines` object[] 订单的支付记录列表。 * Array \[ - `name` string 支付方式的展示名称。 - `channel` string 处理该笔支付的支付渠道。 - `method` string 本次支付使用的支付网关。 - `credit_card_number` string 支付所用银行卡的尾号。 - `transaction_id` string 支付的交易流水号。 - `paid_total` string 通过该支付方式支付的金额。 - `extra_info` string - `real_paid_total` string 通过该支付方式实际支付的金额。 * \] - `location_line` object 商家仓库地址。 - `location_id` string 仓库 ID。 - `location_name` string 仓库名称。 - `first_name` string 顾客或收件人的名。 - `last_name` string 顾客或收件人的姓。 - `phone` string 与该地址关联的电话号码。 - `email` string 与该地址关联的邮箱。 - `country` string 地址所在国家的名称。 - `country_code` string 地址所在国家的 ISO 代码。 - `province` string 地址所在省或州。 - `province_code` string 省或州的代码。 - `area` string 地址所在区域。 - `city` string 地址所在城市。 - `address` string 收件人的详细地址。 - `address1` string 详细地址第一行。 - `company` string 地址的公司名称。 - `latitude` string 地址的纬度。 - `longitude` string 地址的经度。 - `zip` string 邮政编码。 - `phone_area_code` string 电话号码的区号。 - `extra_info` string - `shipping_line_info` object 订单所选物流方案的详情。 - `name` string 物流方案的名称。 - `desc` string 物流方案的描述。 - `delivery_method` number 配送方式类型，`1` 为快递配送，`2` 为本地配送。 - `extra_info` string ```json { "order": { "billing_address": { "address": "123 Main St", "address1": "123 Main St", "area": "", "city": "Los Angeles", "country": "United States", "country_code": "US", "email": "jane@example.com", "first_name": "Jane", "id": "408593e0-c316-415b-b125-714af68b1bed", "last_name": "Doe", "origin_id": "", "province": "California", "province_code": "US-CA", "zip": "90001", "phone": "+1 555-0100", "phone_area_code": "" }, "customer": { "customer_id": "e1773fff-2b71-42c5-bf63-fc93e6e5b3c5", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "name": "Jane Doe", "order_count": 2, "phone": "+1 555-0100", "user_id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5" }, "line_items": [ { "compare_at_price": "1.00", "fulfillment_status": "finished", "id": "b56596b5-3e36-418b-9098-c7099da3beb2", "image": { "alt": "", "height": 1500, "path": "free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "src": "//img.staticdj.com/free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "width": 3000 }, "note": "", "options": [ { "name": "Size", "value": "01" } ], "price": "1.00", "product_handle": "sample-product", "product_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc", "product_title": "sample-product", "product_url": "/products/sample-product", "properties": "{}", "quantity": 1, "requires_shipping": true, "sku": "", "taxable": false, "total": "1.00", "variant_id": "fff360dd-6457-466a-98b3-16878bacef5b", "variant_title": "01", "vendor": "", "weight": "0.00", "weight_unit": "kg", "barcode": "", "custom": false, "trunk_price": "1.00", "shipping_status": "finished", "main_currency_prices": { "compare_at_price": "1", "price": "1", "total": "1", "trunk_price": "1", "actual_rate": "1" }, "discount_total": "0.00", "tax_total": "0.00", "discount_details": [], "final_price": "1.00", "final_total": "1.00", "is_free_gift": false, "duty_price": "0.00" } ], "order_info": { "code_discount_total": "0.00", "config": "{\"page_type\":\"three_step\",\"requires_shipping\":true,\"checkout_business_type\":0,\"product_tax_included\":false,\"checkout_template_type\":0,\"market_setting\":{\"primary_market_lang\":\"en-US\",\"market_lang\":\"en-US\",\"market_id\":\"653506617437848647\",\"market_currency\":\"USD\",\"market_currency_symbol\":{\"code\":\"USD\",\"val\":\"$\",\"left\":\"$\",\"right\":\"\"},\"market_base_currency\":\"USD\",\"market_base_currency_symbol\":{\"code\":\"USD\",\"val\":\"$\",\"left\":\"$\",\"right\":\"\"},\"primary_market_id\":\"653506617437848647\",\"primary_market_currency\":\"USD\",\"primary_market_currency_symbol\":{\"code\":\"USD\",\"val\":\"$\",\"left\":\"$\",\"right\":\"\"},\"market_price_setting\":{\"local_currency_enabled\":false,\"custom_rate_enabled\":false,\"custom_rate\":0,\"rate\":1,\"back_rate\":1,\"actual_rate\":1,\"base_to_local\":0,\"local_to_base\":0,\"adjust\":0,\"price_round_enabled\":true},\"market_country\":\"US\"}}", "create_time": "2026-09-03T02:23:14Z", "currency_code": "USD", "customer_note": "", "discount_applications": "[]", "discount_code": "", "discount_total": "0.00", "fail_code": "", "financial_status": "paid", "fulfillment_status": "finished", "id": "2446407211602194455359", "line_item_discount_total": "0.00", "note": "", "order_no": "KSR43063", "post_sale_status": "", "refer_info": { "address_check": true, "client_id": "1788247080462259", "country": "US", "customer_session": "879f8b8f-c3a0-483c-baf6-f5a55a7ff5b4", "domain": "your-store.myshoplaza.com", "fbc": "", "fbp": "", "inventory_deduction": "order_created", "ip": "203.0.113.10", "seg": "A", "session_id": "1788401986587184", "source": "cart", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36" }, "shipping_address_editable": false, "shipping_total": "1.00", "status": "finished", "sub_total": "1.00", "tax_total": "0.00", "total": "2.00", "updated_at": "2026-09-03T02:37:41Z", "total_tip_received": "0.00", "cancelable": false, "create_at": "2026-09-03T02:23:14Z", "gift_card_total": "0.00", "paid_total": "2.00", "payment_due": "0.00", "payment_progress": 3, "real_paid_total": "2.00", "checkout_url": "/checkout/2446407211602194455359?key=082bf85a7f94752154bfd18f96d828", "order_url": "/order/2446407211602194455359", "main_currency_prices": { "sub_total": "1", "shipping_total": "1", "tax_total": "0", "discount_total": "0", "total": "2", "total_tip_received": "0", "actual_rate": "1", "actual_rate_show": "" }, "final_total": "1.00", "order_type": 0, "shipping_tax_type": 0, "shipping_tax_total": "0.00", "product_tax_included": false, "additional_total": "0.00", "additional_prices": {}, "tax_lines": [], "duty_total": "0.00" }, "payment_line": { "name": "bogus", "channel": "bogus", "method": "bogus_gateway", "credit_card_number": "0000", "transaction_id": "test_2446407211602194455359", "paid_total": "2.00", "extra_info": "{\"order_trans_id\":\"48c7db2c5b904252aae2019ce738a818\",\"pay_unique_id\":\"2446407211602194455359\"}", "real_paid_total": "2.00" }, "shipping_address": { "address": "123 Main St", "address1": "123 Main St", "area": "", "city": "Los Angeles", "company": "", "country": "United States", "country_code": "US", "email": "jane@example.com", "extra_info": {}, "first_name": "Jane", "id": "f1871eb3-5baa-47ba-bfce-783601c6e925", "last_name": "Doe", "origin_id": "6ca9fa54-8bfc-461f-9364-0fd104858990", "phone": "+1 555-0100", "phone_area_code": "", "province": "California", "province_code": "US-CA", "zip": "90001" }, "shipping_line": "{\"id\":\"d43bfac3-5f80-433d-b9ce-49a3d645cd5c\",\"name\":\"Standard shipping\",\"desc\":\"\",\"support_cod\":0,\"shipping_price\":\"1.00\",\"delivery_method\":1,\"location_id\":\"0\"}", "allowed_actions": { "delete_order": true, "cancel_order": false, "repay_order": false, "pay_order": false, "add_to_cart": false, "download_invoice": false, "finish_fulfillment": false }, "payment_lines": [ { "name": "bogus", "channel": "bogus", "method": "bogus_gateway", "credit_card_number": "0000", "transaction_id": "test_2446407211602194455359", "paid_total": "2.00", "extra_info": "{\"order_trans_id\":\"48c7db2c5b904252aae2019ce738a818\",\"pay_unique_id\":\"2446407211602194455359\"}", "real_paid_total": "2.00" } ], "location_line": { "location_id": "653509177250953159", "location_name": "Default", "first_name": "Jane", "last_name": "Doe", "phone": "+1 555-0100", "email": "jane@example.com", "country": "", "country_code": "", "province": "", "province_code": "", "area": "", "city": "", "address": "123 Main St", "address1": "123 Main St", "company": "", "latitude": "0.000000", "longitude": "0.000000", "zip": "", "phone_area_code": "", "extra_info": "" }, "shipping_line_info": { "name": "Standard shipping", "desc": "", "delivery_method": 1, "extra_info": "{\"id\":\"d43bfac3-5f80-433d-b9ce-49a3d645cd5c\",\"name\":\"Standard shipping\",\"desc\":\"\",\"support_cod\":0,\"shipping_price\":\"1.00\",\"delivery_method\":1,\"location_id\":\"0\"}" } } } ``` ## 取消订单 ```text PATCH /{locale}/api/orders/{order_id}/cancel.json ``` 取消当前已登录顾客的某一个订单。 ### 请求示例 **请求示例** ```javascript 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_id` string 订单的 id。 ### 响应 **数据结构 | 示例** - `` object ```json {} ``` ## 确认订单收货 ```text PATCH /{locale}/api/orders/{order_id}/confirm_receipt.json ``` 确认当前已登录顾客已收到该订单。 ### 请求示例 **请求示例** ```javascript 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_id` string 订单的 id。 ### 响应 **数据结构 | 示例** - `` object ```json {} ``` ## 获取订单发货记录 ```text GET /{locale}/api/orders/{order_id}/fulfillments.json ``` 获取当前已登录顾客某一个订单的发货记录，包含运单号、承运商和行项目。 ### 请求示例 **请求示例** ```javascript fetch(window.SHOPLAZZA.routes.root + '/api/orders/2446407211602194455359/fulfillments.json') .then((response) => response.json()) .then((data) => { // do something... }); ``` ### 请求参数 - `order_id` string 订单的 id。 ### 响应 **数据结构 | 示例** - `count` string 返回的物流记录数量。 - `fulfillments` object[] 订单的物流记录列表。 * Array \[ - `id` string 物流记录的 ID。 - `retrieve_method` string - `tracking_number` string 运单号。 - `tracking_company` string 承运的物流商。 - `tracking_company_code` string 物流商编码。 - `status` string 物流记录的状态，例如 `shipped`、`finished`。 - `line_items` object[] 本次发货包含的行项目。 * Array \[ - `id` string 行项目的 ID。 - `product_title` string 商品名称。 - `product_id` string 商品 ID。 - `product_handle` string 商品的 handle。 - `variant_id` string 款式 ID。 - `variant_title` string 款式标题，例如 `Blue, Size M`。 - `quantity` number 商品数量。 - `fulfillment_status` string 发货状态，例如 `waiting`、`shipped`、`finished`。 - `note` string 行项目的备注。 - `image` object 行项目所属款式的图片。 - `alt` string 图片的替代文本。 - `height` number 图片高度（像素）。 - `path` string 图片文件在图床上的路径。 - `src` string 图片的地址。 - `width` number 图片宽度（像素）。 - `compare_at_price` string 划线价。 - `price` string 行项目单件商品的价格。 - `total` string 行项目的总价。 - `sku` string 款式的 SKU，用于库存管理。 - `weight` string 款式的重量。 - `weight_unit` string 重量单位，例如 `kg`。 - `taxable` boolean 是否需要计税。 - `requires_shipping` boolean 是否需要物流配送。 - `options` object[] 行项目所属款式的属性取值。 * Array \[ - `name` string 商品属性名称，例如 `Color`。 - `value` string 该商品属性被选中的取值。 * \] - `vendor` string 商品的供应商。 - `product_url` string 商品页的相对地址。 - `properties` string 行项目上记录的自定义属性。 - `ship_quantity` number 本次发货的数量。 * \] - `tracking_company_code_v1` string - `tracking_url` string 物流跟踪链接。 * \] ```json { "count": "1", "fulfillments": [ { "id": "8dc782af-4ee6-4a0a-804a-e96227673b32", "retrieve_method": "manual", "tracking_number": "AJAXPROBE0001", "tracking_company": "DHL", "tracking_company_code": "", "status": "shipped", "line_items": [ { "id": "b56596b5-3e36-418b-9098-c7099da3beb2", "product_title": "sample-product", "product_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc", "product_handle": "sample-product", "variant_id": "fff360dd-6457-466a-98b3-16878bacef5b", "variant_title": "01", "quantity": 1, "fulfillment_status": "shipped", "note": "", "image": { "alt": "", "height": 1500, "path": "free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "src": "//img.staticdj.com/free/e6e8dc980211cbef103e16371d6e0e61.jpeg", "width": 3000 }, "compare_at_price": "1.00", "price": "1.00", "total": "1.00", "sku": "", "weight": "0.00", "weight_unit": "kg", "taxable": false, "requires_shipping": true, "options": [ { "name": "Size", "value": "01" } ], "vendor": "", "product_url": "/products/sample-product", "properties": "{}", "ship_quantity": 1 } ], "tracking_company_code_v1": "", "tracking_url": "" } ] } ``` ## 确认单次发货收货 ```text PATCH /{locale}/api/orders/{order_id}/fulfillments/{fulfillment_id}/finish.json ``` 确认当前已登录顾客已收到订单中的某一次发货。 ### 请求示例 **请求示例** ```javascript 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_id` string 订单的 id。 - `fulfillment_id` string 发货记录的 id。 ### 响应 **数据结构 | 示例** - `fulfillment` string ```json { "fulfillment": null } ``` ## 请求删除订单 ```text DELETE /{locale}/api/orders/{order_id}.json ``` ### 请求示例 **请求示例** ```javascript 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_id` string 订单的 id。 ### 响应 **数据结构 | 示例** - `` object ```json {} ``` ## 免登录获取订单页地址 ```text POST /{locale}/api/order_verify ``` 用订单号加订单上的邮箱地址换取订单页地址。匿名访客可以调用，前台的订单查询表单就用它。请求体为 `application/x-www-form-urlencoded`。 ### 请求示例 **请求示例** ```javascript const body = new URLSearchParams({ order_number: 'KSR43063', email: 'jane@example.com' }); 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_number` string 订单号，例如 `KSR43063`。 - `email` string 订单上的邮箱地址。 ### 响应 **数据结构 | 示例** - `action` string 请求结果，例如 `Success` 或 `Unauthorized`。 - `value` string 顾客被跳转到的相对地址。 ```json { "action": "Success", "value": "/order/2446407211602194455359" } ``` ## 按运单号查询物流轨迹 ```text GET /{locale}/api/tracking/package ``` 按运单号获取包裹的承运商物流状态。 ### 请求示例 **请求示例** ```javascript fetch(window.SHOPLAZZA.routes.root + '/api/tracking/package?tracking_number=AJAXPROBE0001') .then((response) => response.json()) .then((data) => { // do something... }); ``` ### 请求参数 - `tracking_number` string 包裹的运单号。 ### 响应 **数据结构 | 示例** - `meta` object 查询结果的元信息。 - `code` number 查询结果的状态码。 - `type` string 查询结果的类型，例如 `Success`。 - `message` string 查询结果的说明。 - `data` object 响应数据主体。 - `items` object[] 被查询的包裹列表。 * Array \[ - `tracking_number` string 运单号。 - `carrier_code` string 承运该包裹的物流商编码。 - `lastEvent` string - `lastUpdateTime` string - `substatus` string - `origin_info` object - `carrier_code` string 承运该包裹的物流商编码。 - `ItemReceived` string - `trackinfo` string * \] ```json { "meta": { "code": 200, "type": "Success", "message": "Success" }, "data": { "items": [ { "tracking_number": "AJAXPROBE0001", "carrier_code": "100296", "lastEvent": "", "lastUpdateTime": "", "substatus": "Pending", "origin_info": { "carrier_code": "100296", "ItemReceived": "2026-09-03 10:37:40", "trackinfo": null } } ] } } ```