English

简体中文

English

简体中文

About Fulfillment ​

Access scope

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

Fulfillment is a core business module of Genstore, enabling end-to-end order delivery management from shipping to after-sales. Through standardized fulfillment processes and real-time status tracking, it provides merchants with efficient order fulfillment capabilities, reducing operational costs and improving customer satisfaction.

Core Features

  • Create Shipment: Create order shipment record and register logistics information.
  • Update Logistics: Modify carrier and tracking information of fulfillment order.
  • Query Logistics: Retrieve real-time logistics status and tracking history.
  • Create Return: Create refund record with or without item return.
  • Register Return: Record return logistics information.
  • Query Fulfillment: Retrieve detailed fulfillment record information.
  • Count Fulfillment: Get order fulfillment count and status statistics.

Use Cases

  • Multi-channel Fulfillment: Merchants can efficiently manage fulfillment processes across different channels through the API, coordinate shipments from multiple locations, and maintain consistent delivery standards across all sales channels.
  • Third-party Logistics Integration: Logistics providers can integrate with the API to automatically receive shipping orders, update delivery status in real-time, and manage exceptions through standardized processes, ensuring efficient and transparent delivery operations.
  • After-sales Service Platform: Customer service teams can leverage the API to process returns and refunds systematically, track return shipments, and maintain complete service records, enabling efficient resolution of customer issues.

Endpoints

POST /api/202412/fulfillments: Create fulfillment

POST /api/202412/fulfillment_services: Fulfillment Services

PUT /api/202412/fulfillments/{fulfillmentId}/update_tracking: Update fulfillment logistics

GET /api/202412/orders/{orderId}/fulfillments: Get order fulfillment list

Order Fulfillment Object ​

An order fulfillment refers to the process of preparing and delivering orders to customers.

Properties ​

fulfillmentobjectrequired
- Hide child properties
lineItemsarrayrequired
A list of the fulfillment's line items, which includes:
+ Show child properties
orderIdstringrequired
The unique numeric identifier for the order.
trackingUrlstringrequired
The URL to track the fulfillment.
createTimestringrequired
The date and time when the fulfillment was created. The API returns this value in ISO 8601 format.
originAddressarrayrequired
The address of the fulfillment location. This property is intended for tax purposes, as a full address is required for tax providers to accurately calculate taxes. To retrieve a fulfillment location's address, use the assigned_location` property on the FulfillmentOrder resource instead.
+ Show child properties
trackingCompanystringrequired
The name of the tracking company.
trackingNumbersstringrequired
A list of tracking numbers provided by the shipping company.
updateTimestringrequired
The date and time (ISO 8601 format) when the fulfillment was last modified..
idstringrequired
The ID for the fulfillment.
trackingNumberstringrequired
A tracking number provided by the shipping company.
trackingUrlsstringrequired
The URLs of tracking pages for the fulfillment.
statusstringrequired
The status of the fulfillment. Valid values:
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 Create fulfillment ​

Create a fulfillment for one or many fulfillment orders.

Access scope

Requires ANY of the following access scopes: write_fulfillments

Endpoint

POST /api/202412/fulfillments 

Request Params

fulfillmentobjectrequired
Returns a Fulfillment order resource by ID.
- Hide child properties
lineItemsarrayrequired
A list of the fulfillment's line items.
+ Show child properties
orderIdstringrequired
The unique numeric identifier for the order.
originAddressarray
The address of the fulfillment location.
+ Show child properties
fulfillmentServiceHandlestring
The fulfillment service handle.
trackingsarray
This is a collection of logistics information for fulfilling the contract.
+ Show child properties

Response Data

fulfillmentobjectrequired
Returns a Fulfillment order resource by ID.
- Hide child properties
lineItemsarrayrequired
A list of the fulfillment's line items.
+ Show child properties
orderIdstringrequired
The unique numeric identifier for the order.
trackingUrlstringrequired
The URL to track the fulfillment.
createTimestringrequired
The date and time when the fulfillment was created. The API returns this value in ISO 8601 format.
originAddressarrayrequired
The address of the fulfillment location.
+ Show child properties
trackingCompanystringrequired
The name of the tracking company.
trackingNumbersstringrequired
A list of tracking numbers provided by the shipping company.
updateTimestringrequired
The date and time (ISO 8601 format) when the fulfillment was last modified..
idstringrequired
The ID for the fulfillment.
trackingNumberstringrequired
A tracking number provided by the shipping company.
trackingUrlsstringrequired
The URLs of tracking pages for the fulfillment.
statusstringrequired
The status of the fulfillment. Enumeration value: open, fulfilled, part_fulfilled, cancelled, error, failure.
fulfillmentServiceHandlestringrequired
The fulfillment service handle.
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 Fulfillment Services ​

Create a fulfillment service provider.

Access scope

Requires ANY of the following access scopes: write_fulfillments

Endpoint

POST /api/202412/fulfillment_services 

Request Params

fulfillmentServiceobjectrequired
Create fulfillment services
- Hide child properties
callbackUrlstring
The shipping service is a callback URL for requesting registration.
namestringrequired
Customize service name.
trackingSupportboolean
Does it support logistics tracking.

Response Data

fulfillmentServiceobjectrequired
Create fulfillment services.
- Hide child properties
serviceIdnumberrequired
Service number.
namestringrequired
Customize service name.
serviceNamestringrequired
Service name.
trackingSupportbooleanrequired
Does it support logistics tracking.
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 Update fulfillment logistics ​

Update the tracking information for a fulfillment.

Access scope

Requires ANY of the following access scopes: write_fulfillments

Endpoint

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

Request Params

fulfillmentobjectrequired
Update fulfillment
- Hide child properties
lineItemsarrayrequired
A list of the fulfillment's line items.
+ Show child properties
orderIdstringrequired
The unique numeric identifier for the order.
createTimestringrequired
The date and time when the fulfillment was created. The API returns this value in ISO 8601 format.
originAddressarrayrequired
The address of the fulfillment location.
+ Show child properties
updateTimestringrequired
The date and time (ISO 8601 format) when the fulfillment was last modified..
idstringrequired
The ID for the fulfillment.
statusstringrequired
The status of the fulfillment. Enumeration value: open, fulfilled, cancelled, error, failure.
trackingsarrayrequired
This is a collection of logistics information for fulfilling the contract.
+ Show child properties

Response Data

fulfillmentobjectrequired
Update fulfillment
- Hide child properties
lineItemsarrayrequired
A list of the fulfillment's line items.
+ Show child properties
orderIdstringrequired
The unique numeric identifier for the order.
createTimestringrequired
The date and time when the fulfillment was created. The API returns this value in ISO 8601 format.
originAddressarrayrequired
The address of the fulfillment location.
+ Show child properties
updateTimestringrequired
The date and time (ISO 8601 format) when the fulfillment was last modified.
idstringrequired
The ID for the fulfillment.
statusstringrequired
The status of the fulfillment. Enumeration value: open, fulfilled, part_fulfilled, cancelled, error, failure.
trackingsarrayrequired
This is a collection of logistics information for fulfilling the contract.
+ Show child properties
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 Get order fulfillment list ​

Obtain the fulfillment list based on the order.

Access scope

Requires ANY of the following access scopes: read_fulfillments

Endpoint

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

Request Params

orderIdstringrequired
The ID of the fulfillment order that is associated with the fulfillments.

Response Data

fulfillmentarrayrequired
Performance resources.
- Hide child properties
lineItemsarrayrequired
A list of the fulfillment's line items.
+ Show child properties
orderIdstringrequired
The unique numeric identifier for the order.
trackingUrlstringrequired
The URL to track the fulfillment.
createTimestringrequired
The date and time when the fulfillment was created. The API returns this value in ISO 8601 format.
originAddressarrayrequired
The address of the fulfillment location.
+ Show child properties
trackingCompanystringrequired
The name of the tracking company.
trackingNumbersstringrequired
A list of tracking numbers provided by the shipping company.
updateTimestringrequired
The date and time (ISO 8601 format) when the fulfillment was last modified..
idstringrequired
The ID for the fulfillment.
trackingNumberstringrequired
A tracking number provided by the shipping company.
trackingUrlsstringrequired
The URLs of tracking pages for the fulfillment.
statusstringrequired
The status of the fulfillment. Enumeration value: open, fulfilled, part_fulfilled, cancelled, error, failure.
trackingsarrayrequired
This is a collection of logistics information for fulfilling the contract.
+ Show child properties
fulfillmentServiceHandlestringrequired
This is the fulfillment service handle.
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": "fulfilled",
      "fulfillmentServiceHandle": "dsers"
    }
  ]
}