关于履约

访问范围

需要多个访问范围—请参阅每个端点以了解访问范围要求。

需要访问受保护的客户数据。

履约是 Genstore 的核心业务模块，实现从发货到售后的端到端订单交付管理。通过标准化的履约流程和实时状态追踪，为商家提供高效的订单履约能力，降低运营成本并提升客户满意度。

核心功能

创建发货单：创建订单发货记录并登记物流信息。
更新物流：修改履约单的物流公司和运单信息。
查询物流：获取实时物流运输状态和轨迹信息。
创建售后单：创建退货退款或仅退款的售后记录。
登记退货：记录售后退货物流信息。
查询履约：获取履约记录的详细信息。
统计履约：获取订单的履约次数和状态统计。

应用场景

全渠道订单管理：商家可通过接口高效管理多渠道的履约流程，协调多地发货，并保持各销售渠道的统一配送标准。
第三方物流对接：物流服务商可集成接口实现自动接单、实时更新物流状态，并通过标准流程处理异常情况，确保高效透明的配送作业。
售后服务平台：客服团队可使用接口系统化处理退货退款、跟踪退货物流，并维护完整的服务记录，实现高效的客户问题解决。

接口

POST /api/202412/fulfillments: 创建履约

POST /api/202412/fulfillment_services: 创建履约服务商

PUT /api/202412/fulfillments/{fulfillmentId}/cancel: 取消履约

PUT /api/202412/fulfillments/{fulfillmentId}/update_tracking: 更新履约物流

GET /api/202412/orders/{orderId}/fulfillments: 获取订单履约列表

GET /api/202412/orders/{orderId}/fulfillments/count: 获取订单履约次数

GET /api/202412/fulfillments?ids={fulfillmentIds}: 获取履约信息

订单履约对象

订单履行是指准备订单并向客户交付订单的过程。

属性

fulfillmentobject

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

trackingUrlstring

用于跟踪发货的 URL。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

trackingCompanystring

跟踪公司的名称。

trackingNumbersstring

运输公司提供的跟踪号列表。

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

trackingNumberstring

运输公司提供的跟踪号。

trackingUrlsstring

发货的跟踪页面的 URL。

statusstring

发货状态。

订单履约对象

bash

{
  "fulfillment": {
    "lineItems": [
      {
        "variantTitle": "green",
        "quantity": "1",
        "productId": "632910392",
        "title": "iPhone 15Pr - 128gb",
        "fulfillmentStatus": "null",
        "requiresShipping": "true",
        "price": "6400",
        "giftCard": "false",
        "name": "iPhone 15Pr - 128gb - green",
        "id": "466157049",
        "variantId": "39072856",
        "grams": "200",
        "sku": "IPOD2008GREEN"
      }
    ],
    "orderId": "450789469",
    "trackingUrl": "https://www.my-shipping-company.com?tracking_number=MS1562678",
    "createTime": "2024-11-25T15:47:18-04:00",
    "originAddress": [
      {
        "zip": "G1R 4P5",
        "address2": "Suite 123",
        "city": "Montreal",
        "address1": "1 Rue des Carrieres",
        "countryCode": "CA",
        "provinceCode": "QC"
      }
    ],
    "trackingCompany": "",
    "trackingNumbers": "["MS1562678"]",
    "updateTime": "2024-11-25T15:47:18-04:00",
    "id": "466157049",
    "trackingNumber": "MS1562678",
    "trackingUrls": "["https://www.my-shipping-company.com?tracking_number=MS1562678" ]",
    "status": "open"
  }
}

`POST` 创建履约

为订单创建履约。

访问范围

需要以下任意访问权限: write_fulfillments

接口

POST /api/202412/fulfillments

请求参数

fulfillmentobject

履约资源。

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

originAddressarray

发货地点的地址。

+ 展开属性

fulfillmentServiceHandlestring

履约服务商Handle。

trackingsarray

物流信息。

+ 展开属性

响应数据

fulfillmentobject

履约资源。

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

trackingUrlstring

用于跟踪发货的 URL。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

trackingCompanystring

跟踪公司的名称。

trackingNumbersstring

运输公司提供的跟踪号列表。

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

trackingNumberstring

运输公司提供的跟踪号。

trackingUrlsstring

发货的跟踪页面的 URL。

statusstring

发货状态:创建发货、已发货、已取消、请求出错、请求失败。

fulfillmentServiceHandlestring

履约服务商Handle。

POST /api/202412/fulfillments

bash

curl -X POST \ 
https://{shop}.genmystore.com/api/202412/fulfillments" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillment":{
		"lineItems":[
			{
				"quantity":"1",
				"id":"prod_991122"
			}
		],
		"orderId":"12",
		"trackings":[
			{
				"trackingUrl":"https://www.ups.com/cn/zh/home",
				"trackingCompany":"UPS",
				"trackingNumber":"1Z9R45W80327001526"
			}
		],
		"originAddress":[
			{
				"zip":"200050",
				"address2":"B座15楼",
				"city":"上海市",
				"address1":"长宁区虹桥路1234号",
				"countryCode":"CN",
				"provinceCode":"SH"
			}
		],
		"fulfillmentServiceHandle":"dsers"
	}
}'

响应

json

HTTP/1.1 200 OK
{
  "fulfillment": {
    "orderId": "12",
    "trackingUrl": "https://www.ups.com/cn/zh/track?trackingNumber=1Z9R45W80327001526",
    "originAddress": [
      {
        "zip": "200050",
        "address2": "B座15楼",
        "city": "上海市",
        "address1": "长宁区虹桥路1234号",
        "countryCode": "CN",
        "provinceCode": "SH"
      }
    ],
    "trackingNumbers": "1Z9R45W80327001526,1ZW689A80327004321",
    "updateTime": "2025-06-24T09:15:22+08:00",
    "trackingUrls": "https://www.ups.com/track?num=1Z9R45W80327001526,https://www.ups.com/track?num=1ZW689A80327004321",
    "lineItems": [
      {
        "variantTitle": "黑色 / 大码",
        "quantity": "2",
        "productId": "prod_778899",
        "title": "男士纯棉T恤",
        "fulfillmentStatus": "fulfilled",
        "requiresShipping": "true",
        "price": "129.00",
        "giftCard": "false",
        "name": "Premium T-Shirt",
        "id": "li_00112233",
        "variantId": "var_445566",
        "grams": "350",
        "sku": "TSH-BLK-L"
      }
    ],
    "createTime": "2025-06-24T09:15:22+08:00",
    "trackingCompany": "UPS China",
    "id": "ful_123456789",
    "trackingNumber": "1Z9R45W80327001526",
    "status": "open",
    "fulfillmentServiceHandle": "dsers"
  }
}

`POST` 创建履约服务商

创建履约服务商

访问范围

需要以下任意访问权限: write_fulfillments

接口

POST /api/202412/fulfillment_services

请求参数

fulfillmentServiceobject

创建履约服务

- 收起属性

callbackUrlstring

发货服务为请求注册的回调 URL。

namestring

自定义服务名称。

trackingSupportboolean

是否支持物流追踪。

响应数据

fulfillmentServiceobject

履约服务。

- 收起属性

serviceIdnumber

服务编号。

namestring

自定义服务名称。

serviceNamestring

服务名称。

trackingSupportboolean

是否支持物流追踪。

POST /api/202412/fulfillment_services

bash

curl -X POST \ 
https://{shop}.genmystore.com/api/202412/fulfillment_services" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillmentService":{
		"trackingSupport":"true",
		"name":"Dsers",
		"callbackUrl":"http://api.genstore.ai/callback"
	}
}'

响应

json

HTTP/1.1 200 OK
{
  "fulfillmentService": {
    "trackingSupport": "true",
    "name": "Dsers",
    "serviceId": "129001",
    "serviceName": "Dsers"
  }
}

`PUT` 取消履约

取消履约。

访问范围

需要以下任意访问权限: write_fulfillments

接口

PUT /api/202412/fulfillments/{fulfillmentId}/cancel

请求参数

fulfillmentIdstring

要取消的履约 ID。

响应数据

fulfillmentobject

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

trackingUrlstring

用于跟踪发货的 URL。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

trackingCompanystring

跟踪公司的名称。

trackingNumbersstring

运输公司提供的跟踪号列表。

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

trackingNumberstring

运输公司提供的跟踪号。

trackingUrlsstring

发货的跟踪页面的 URL。

statusstring

发货状态。

PUT /api/202412/fulfillments/{fulfillmentId}/cancel

bash

curl -X PUT \ 
https://{shop}.genmystore.com/api/202412/fulfillments/{fulfillmentId}/cancel" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillmentId":"237894043"
}'

响应

json

HTTP/1.1 200 OK
{
  "fulfillment": {
    "lineItems": [
      {
        "variantTitle": "",
        "quantity": "",
        "productId": "",
        "title": "",
        "fulfillmentStatus": "",
        "requiresShipping": "",
        "price": "",
        "giftCard": "",
        "name": "",
        "id": "",
        "variantId": "",
        "grams": "",
        "sku": ""
      }
    ],
    "orderId": "",
    "trackingUrl": "",
    "createTime": "",
    "originAddress": [
      {
        "zip": "",
        "address2": "",
        "city": "",
        "address1": "",
        "countryCode": "",
        "provinceCode": ""
      }
    ],
    "trackingCompany": "",
    "trackingNumbers": "",
    "updateTime": "",
    "id": "",
    "trackingNumber": "",
    "trackingUrls": "",
    "status": ""
  }
}

`PUT` 更新履约物流

更新履约物流信息。

访问范围

需要以下任意访问权限: write_fulfillments

接口

PUT /api/202412/fulfillments/{fulfillmentId}/update_tracking

请求参数

fulfillmentobject

履约能力

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

statusstring

发货状态。

trackingsarray

物流信息。

+ 展开属性

响应数据

fulfillmentobject

履约能力

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

statusstring

发货状态。

trackingsarray

物流信息。

+ 展开属性

PUT /api/202412/fulfillments/{fulfillmentId}/update_tracking

bash

curl -X PUT \ 
https://{shop}.genmystore.com/api/202412/fulfillments/{fulfillmentId}/update_tracking" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillment":{
		"lineItems":[
			{
				"variantTitle":"Blue / Large",
				"quantity":"2",
				"productId":"7982439268491",
				"title":"男士纯棉T恤",
				"fulfillmentStatus":"fulfilled",
				"requiresShipping":"true",
				"price":"29.99",
				"giftCard":"false",
				"name":"Classic Cotton Tee",
				"id":"1051830923275",
				"variantId":"40234680336587",
				"grams":"250",
				"sku":"MCT-BLU-L"
			}
		],
		"orderId":"520982765579",
		"createTime":"2025-07-07T10:30:00Z",
		"trackings":[
			{
				"trackingUrl":"https://www.ups.com/cn/zh/home",
				"trackingCompany":"UPS",
				"trackingNumber":"1Z9R45W80327001526"
			}
		],
		"originAddress":[
			{
				"zip":"200001",
				"address2":"单元B",
				"city":"上海",
				"address1":"南京东路123号",
				"countryCode":"CN",
				"provinceCode":"SH"
			}
		],
		"updateTime":"2025-07-07T14:15:00Z",
		"id":"7009837645",
		"status":"fulfilled"
	}
}'

响应

json

HTTP/1.1 200 OK
{
  "fulfillment": {
    "lineItems": [
      {
        "variantTitle": "Blue / Large",
        "quantity": "2",
        "productId": "7982439268491",
        "title": "男士纯棉T恤",
        "fulfillmentStatus": "fulfilled",
        "requiresShipping": "true",
        "price": "29.99",
        "giftCard": "false",
        "name": "Classic Cotton Tee",
        "id": "1051830923275",
        "variantId": "40234680336587",
        "grams": "250",
        "sku": "MCT-BLU-L"
      }
    ],
    "orderId": "520982765579",
    "createTime": "2025-07-07T10:30:00Z",
    "trackings": [
      {
        "trackingUrl": "https://www.ups.com/cn/zh/home",
        "trackingCompany": "UPS",
        "trackingNumber": "1Z9R45W80327001526"
      }
    ],
    "originAddress": [
      {
        "zip": "200001",
        "address2": "单元B",
        "city": "上海",
        "address1": "南京东路123号",
        "countryCode": "CN",
        "provinceCode": "SH"
      }
    ],
    "updateTime": "2025-07-07T14:15:00Z",
    "id": "7009837645",
    "status": "fulfilled"
  }
}

`GET` 获取订单履约列表

根据订单获取履约列表。

访问范围

需要以下任意访问权限: read_fulfillments

接口

GET /api/202412/orders/{orderId}/fulfillments

请求参数

orderIdstring

这是一个订单行。

响应数据

fulfillmentarray

履约资源。

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

trackingUrlstring

用于跟踪发货的 URL。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

trackingCompanystring

跟踪公司的名称。

trackingNumbersstring

运输公司提供的跟踪号列表。

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

trackingNumberstring

运输公司提供的跟踪号。

trackingUrlsstring

发货的跟踪页面的 URL。

statusstring

发货状态:创建发货、已发货、已取消、请求出错、请求失败。

trackingsarray

物流信息。

+ 展开属性

fulfillmentServiceHandlestring

履约服务商Handle。

GET /api/202412/orders/{orderId}/fulfillments

bash

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/orders/{orderId}/fulfillments" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

json

HTTP/1.1 200 OK
{
  "fulfillment": [
    {
      "orderId": "12",
      "trackingUrl": "https://www.ups.com/cn/zh/track?trackingNumber=1Z9R45W80327001526",
      "originAddress": [
        {
          "zip": "200050",
          "address2": "B座15楼",
          "city": "上海市",
          "address1": "长宁区虹桥路1234号",
          "countryCode": "CN",
          "provinceCode": "SH"
        }
      ],
      "trackingNumbers": "UPS China",
      "updateTime": "2025-06-24T09:15:22+08:00",
      "trackingUrls": "https://www.ups.com/track?num=1Z9R45W80327001526,https://www.ups.com/track?num=1ZW689A80327004321",
      "lineItems": [
        {
          "variantTitle": "黑色 / 大码",
          "quantity": "2",
          "productId": "prod_778899",
          "title": "男士纯棉T恤",
          "fulfillmentStatus": "fulfilled",
          "requiresShipping": "true",
          "price": "129.00",
          "giftCard": "false",
          "name": "Premium T-Shirt",
          "id": "li_00112233",
          "variantId": "var_445566",
          "grams": "350",
          "sku": "TSH-BLK-L"
        }
      ],
      "createTime": "2025-06-25T14:30:00+08:00",
      "trackings": [
        {
          "trackingUrl": "https://www.ups.com/track?num=1ZW689A80327004321",
          "trackingCompany": "UPS Express",
          "trackingNumber": "1ZW689A80327004321"
        }
      ],
      "trackingCompany": "[]",
      "id": "ful_123456789",
      "trackingNumber": "1Z9R45W80327001526",
      "status": "delivered",
      "fulfillmentServiceHandle": "dsers"
    }
  ]
}

`GET` 获取订单履约次数

获取订单的履约次数。

访问范围

需要以下任意访问权限: read_fulfillments

接口

GET /api/202412/orders/{orderId}/fulfillments/count

请求参数

orderIdstring

订单的唯一数字标识符。

响应数据

countstring

订单的履约次数。

GET /api/202412/orders/{orderId}/fulfillments/count

bash

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/orders/{orderId}/fulfillments/count" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

json

HTTP/1.1 200 OK
{
  "count": "1"
}

`GET` 获取履约信息

根据履约 ID 查询履约信息。

访问范围

需要以下任意访问权限: read_fulfillments

接口

GET /api/202412/fulfillments?ids={fulfillmentIds}

请求参数

fulfillmentIdnumber

履约 ID。

orderIdnumber

订单的唯一数字标识符。

响应数据

fulfillmentobject

- 收起属性

lineItemsarray

发货的行项目列表。

+ 展开属性

orderIdstring

订单的唯一数字标识符。

trackingUrlstring

用于跟踪发货的 URL。

createTimestring

创建发货的日期和时间。API 以 ISO 8601 格式返回此值。

originAddressarray

发货地点的地址。

+ 展开属性

trackingCompanystring

跟踪公司的名称。

trackingNumbersstring

运输公司提供的跟踪号列表。

updateTimestring

最后修改履行的日期和时间（ISO 8601格式）..

idstring

履约ID。

trackingNumberstring

运输公司提供的跟踪号。

trackingUrlsstring

发货的跟踪页面的 URL。

statusstring

发货状态。

GET /api/202412/fulfillments?ids={fulfillmentIds}

bash

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/fulfillments?ids={fulfillmentIds}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

响应

json

HTTP/1.1 200 OK
{
  "fulfillment": {
    "lineItems": [
      {
        "variantTitle": "",
        "quantity": "",
        "productId": "",
        "title": "",
        "fulfillmentStatus": "",
        "requiresShipping": "",
        "price": "",
        "giftCard": "",
        "name": "",
        "id": "",
        "variantId": "",
        "grams": "",
        "sku": ""
      }
    ],
    "orderId": "",
    "trackingUrl": "",
    "createTime": "",
    "originAddress": [
      {
        "zip": "",
        "address2": "",
        "city": "",
        "address1": "",
        "countryCode": "",
        "provinceCode": ""
      }
    ],
    "trackingCompany": "",
    "trackingNumbers": "",
    "updateTime": "",
    "id": "",
    "trackingNumber": "",
    "trackingUrls": "",
    "status": ""
  }
}

关于履约

访问范围

需要多个访问范围—请参阅每个端点以了解访问范围要求。

需要访问受保护的客户数据。

核心功能

创建发货单：创建订单发货记录并登记物流信息。
更新物流：修改履约单的物流公司和运单信息。
查询物流：获取实时物流运输状态和轨迹信息。
创建售后单：创建退货退款或仅退款的售后记录。
登记退货：记录售后退货物流信息。
查询履约：获取履约记录的详细信息。
统计履约：获取订单的履约次数和状态统计。

应用场景

全渠道订单管理：商家可通过接口高效管理多渠道的履约流程，协调多地发货，并保持各销售渠道的统一配送标准。
第三方物流对接：物流服务商可集成接口实现自动接单、实时更新物流状态，并通过标准流程处理异常情况，确保高效透明的配送作业。
售后服务平台：客服团队可使用接口系统化处理退货退款、跟踪退货物流，并维护完整的服务记录，实现高效的客户问题解决。

订单履约对象

接口

GET /api/202412/fulfillments?ids={fulfillmentIds}

产品

变体

系列

库存

类目

礼品卡

厂商

订单

履约

客户

主题

页面

店铺

市场

翻译

元字段

元字段定义

账户

交易

折扣

消息订阅

订阅收费

使用量收费

关于 履约 ​

订单履约 对象 ​

属性 ​

POST 创建履约 ​

请求参数

响应数据

POST 创建履约服务商 ​

请求参数

响应数据

PUT 取消履约 ​

请求参数

响应数据

PUT 更新履约物流 ​

请求参数

响应数据

GET 获取订单履约列表 ​

请求参数

响应数据

GET 获取订单履约次数 ​

请求参数

响应数据

GET 获取履约信息 ​

请求参数

响应数据

关于 履约 ​

订单履约 对象 ​

属性 ​

POST 创建履约 ​

POST 创建履约服务商 ​

PUT 取消履约 ​

PUT 更新履约物流 ​

GET 获取订单履约列表 ​

GET 获取订单履约次数 ​

GET 获取履约信息 ​

关于履约

订单履约对象

属性

`POST` 创建履约

`POST` 创建履约服务商

`PUT` 取消履约

`PUT` 更新履约物流

`GET` 获取订单履约列表

`GET` 获取订单履约次数

`GET` 获取履约信息

关于履约

订单履约对象

属性

`POST` 创建履约

`POST` 创建履约服务商

`PUT` 取消履约

`PUT` 更新履约物流

`GET` 获取订单履约列表

`GET` 获取订单履约次数

`GET` 获取履约信息