Appearance
Fulfillment Order API
Endpoint
POST /fulfillment
*Note: OrderId is Optional. Required only if this fulfillment is associated with an existing order. Leave empty if creating a standalone fulfillment.
Note: You can got the shipments's trackingNumber & purchase label information from the response of Get Order Details API get order details API after fulfillment shipped.
Note: If channelFulfillmentId is specified and an existing fulfillment has the same channelFulfillmentId, the request will fail with an HTTP 409 response and the following payload:
json
{
"code": "ALREADY_EXISTS",
"message": "Fulfillment with channelFulfillmentId '...' already exists for this organization"
}Headers
| Key | Value |
|---|---|
| Authorization | Bearer change_to_your_access_token |
| X-S2-Organization | 95d73baf-76ba-4bea-86ac-1534c5e5d4aa |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| orderId | string | No | Optional. Required only if this fulfillment is associated with an existing order. Leave empty if creating a standalone fulfillment. |
| rmaId | string | No | Optional. Required only if this fulfillment is associated with an existing rma. Leave empty if creating a standalone fulfillment. |
| address | object | Yes | Shipping address for the order. All fields are required. See Address Object for details. Pass an empty string if there is no value. |
| warehouseId | string | No | Identifier for the warehouse where the order will be fulfilled from. If not provided, a warehouse will be randomly assigned. |
| channelFulfillmentId | string | No | Optional. External channel's fulfillment identifier. Must be unique - cannot create duplicate fulfillments with the same channelFulfillmentId. |
| orderAccountId | string | No | Optional. Only set when no orderId is provided. If you have an order,no need set this value and auto use the order's accountId. |
| accountCode | string | No | Optional. Set matched value with related account's code. Can get and set value from Account page in web |
| orderType | int | No | Optional. Order type. Values: 0: B2C, 1: B2B, 2: FBA. If not set, will use 0: B2C default. |
| shippingMethod | string | Yes | The shipping method to be used for the order, pass empty string or standard if no value. |
| items | array | Yes | List of items in the order. Each item includes productId and quantity. See Fulfillment Item Object for details. |
| shipments | array | Yes | Details about the shipments including items and prepaidLabels.See Shipments Object for details. |
| attachments | Attachments Object array | Yes | Any attachments related to the order. Each attachment includes fileName and path. Pass an empty array [] if there is no value. See Attachments Object for details. |
| additionalReferenceIds | string array | No | Optional. Additional reference IDs related to the order. |
| signatureRequired | boolean | No | Optional. Indicates if signature is required for delivery. |
| method | int | No | Optional. The fulfillment method to be used. Values: 0: SPD , 1: PICKUP , 2: LTL. |
| customerNote | string | No | Optional. Additional notes from the customer. |
Address Object
The address object includes the following fields:
| Field | Type | Description |
|---|---|---|
| name | string | The full name of the recipient. |
| company | string | The company name, if applicable. |
| address1 | string | The primary street address. |
| address2 | string | Additional address information, such as apartment or suite number. |
| city | string | The city of the shipping address. |
| state | string | The state or province of the shipping address. |
| postalCode | string | The postal or ZIP code of the shipping address. |
| countryId | string | The country code in ISO 3166-1 alpha-2 format (e.g., "US"). |
| phone | string | The contact phone number for the recipient. |
| string | The contact email address for the recipient. |
Attachments Object
The attachments array contains objects with the following fields:
| Field | Type | Description |
|---|---|---|
| fileName | string | The name of the attached file. |
| path | string | The file path or URL where the attachment can be accessed. |
Fulfillment Item Object
Each item in the items array includes the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| productId | string | Yes | Unique identifier of the product. |
| quantity | integer | Yes | Quantity of the product being fulfilled. |
Shipments Object
The shipments array contains shipment objects with the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| items | array | Yes | List of items in the shipment. Each item contains productId and quantity. |
| prepaidLabels | array | Yes | List of pre-generated shipping labels. pass empty string or standard if no value. Each label contains filePath pointing to the label file. See Prepaid Label Object for details. |
| shippingCarrierId | string | No | Identifier for the shipping carrier. If not provided, the default carrier "OTHER" will be used. See Carrier List for available carriers. |
| trackingNumber | string | No | Optional. Tracking number for the shipment. If provided, this tracking number will be used for the shipment. |
Shipment Item Object
Each item in the shipment's items array includes:
| Field | Type | Required | Description |
|---|---|---|---|
| productId | string | Yes | Unique identifier of the product being shipped. |
| quantity | integer | Yes | Quantity of the product in this shipment. |
Prepaid Label Object
Each object in the prepaidLabels array includes:
| Field | Type | Required | Description |
|---|---|---|---|
| filePath | string | Yes | url to the pre-generated shipping label file. |
Request Body Example
json
{
"orderId": "ae52b0ab-8f0c-4b11-9c13-c5c221228ecd",
"address": {
"name": "test",
"company": "test company",
"address1": "test address",
"address2": "test address2",
"city": "test city",
"state": "test",
"postalCode": "123456",
"countryId": "CN",
"phone": "123456",
"email": ""
},
"warehouseId": "9cae310d-c440-4d78-bdc0-bf306ec3388",
"channelFulfillmentId": null,
"orderAccountId": "1ac48942-405a-4841-a7d8-708f50dbe888",
"accountCode": "test_account_code",
"orderType": 0,
"shippingMethod": "Expedited",
"items": [
{
"productId": "3775cc37-30e7-4579-a58e-c9adda6fa88",
"quantity": 2
},
{
"productId": "bab7c35b-2ecb-4b40-be82-8dc1e0a86888",
"quantity": 1
}
],
"shipments": [
{
"items": [
{
"productId": "3775cc37-30e7-4579-a58e-c9adda6fa88",
"quantity": 2
},
{
"productId": "bab7c35b-2ecb-4b40-be82-8dc1e0a8688",
"quantity": 1
}
],
"prepaidLabels": [
{
"filePath": "95d73baf-76ba-4bea-86ac-1534c5e5d4aa/2024-04-24/shipping_label/Snipaste_2024_04_15_13_37_25_wgfZCvetlGQmtEBqnQ__m.png"
}
],
"shippingCarrierId": "OTHER"
}
],
"attachments": [
{
"fileName": "听雨 (24 x 26.25)_PFPWig.jpg",
"path": "95d73baf-76ba-4bea-86ac-1534c5e5d4aa/2024-04-24/fulfillment/听雨__24_x_26.25__PFPWig_bdsL5YZcA8A5Wcfshhj3E.jpg"
}
],
"additionalReferenceIds": []
}Response Example
json
{
"id": "295dbfaa-de55-40aa-ad6b-71f05972288",
"status": "CREATED",
"address": {
"name": "test",
"company": "test company",
"address1": "test address",
"address2": "test address2",
"city": "test city",
"state": "test",
"postalCode": "123456",
"countryId": "CN",
"phone": "123456",
"email": ""
},
"channelFulfillmentId": null,
"meta": {},
"warehouse": {
"id": "9cae310d-c440-4d78-bdc0-bf306ec3388",
"organization": {
"id": "e8b021f4-9ab3-4fc2-af71-f3593075988",
"name": "test organization",
"createdAt": "2024-04-01T14:09:14.732646Z",
"updatedAt": "2024-04-09T21:15:15.615765Z"
},
"name": "test warehouse",
"address": {
"name": "GDI",
"company": "",
"address1": "test warehouse Rd Unit 3",
"address2": "",
"city": "Oakville",
"state": "ON",
"postalCode": "L6L 8X8",
"countryId": "CA",
"phone": "",
"email": ""
},
"dropshipper": true,
"fulfillmentCenter": true,
"rmaCenter": true,
"unitSystem": "METRIC",
"createdAt": "2024-04-01T14:18:10.903581Z",
"updatedAt": "2024-04-01T14:18:10.903581Z"
},
"warehousePickId": "5f590b33-5771-43af-9be0-44f52ae51888",
"shippingMethod": "Expedited",
"items": [
{
"product": {
"id": "3775cc37-30e7-4579-a58e-c9adda6fa888",
"organization": {
"id": "3f424caf-0eba-4813-b3e7-7ca0393af888",
"name": "test organization",
"createdAt": "2024-03-05T22:17:23.520948Z",
"updatedAt": "2024-04-09T21:15:15.615765Z"
},
"sku": "test",
"brand": {
"id": "e0cbbf33-cbea-4867-9fd9-5d72f22c2888",
"name": "Sony",
"nameNormalized": "sony",
"createdAt": "2024-06-04T03:16:22.617577Z"
},
"gtin": "7888888888888",
"name": "Test Product",
"remarks": "remark.",
"imageMain": "95d73baf-76ba-4bea-86ac-1534c5e5d4aa/2024-04-23/avatar/听雨__24_x_26.25__PFPWig_4_YXKT59pJLuoIk82VgaF.jpg",
"packageLengthMm": 33.27078,
"packageWidthMm": 64.29312,
"packageHeightMm": 96.57682,
"shippingWeightKg": 76.44365,
"caseUnit": "EACH",
"casePack": 2,
"caseLengthMm": 34.340958,
"caseWidthMm": 20.323586,
"caseHeightMm": 12.659683,
"caseWeightKg": 0.35708416,
"condition": "NEW",
"serialNumberRequired": true,
"expiryDateRequired": true,
"unknown": false,
"createdAt": "2024-06-04T03:16:22.617577Z",
"updatedAt": "2024-06-04T03:31:28.192345Z",
"otherIds": []
},
"channelFulfillmentItemId": null,
"quantity": 2,
"meta": {}
},
{
"product": {
"id": "bab7c35b-2ecb-4b40-be82-8dc1e0a86888",
"organization": {
"id": "3f424caf-0eba-4813-b3e7-7ca0393af888",
"name": "test organization",
"createdAt": "2024-03-05T22:17:23.520948Z",
"updatedAt": "2024-04-09T21:15:15.615765Z"
},
"sku": "SKU-GREY",
"brand": {
"id": "5643b7ee-7df1-48c6-b690-1e29ffa8ab33",
"name": "",
"nameNormalized": "",
"createdAt": "2024-03-05T22:17:28.679732Z"
},
"gtin": "",
"name": "SKU GREY",
"remarks": "",
"imageMain": "",
"packageLengthMm": 1500.0,
"packageWidthMm": 260.0,
"packageHeightMm": 810.0,
"shippingWeightKg": 35.0,
"caseUnit": "CARTON",
"casePack": 1,
"caseLengthMm": 0.0,
"caseWidthMm": 0.0,
"caseHeightMm": 0.0,
"caseWeightKg": 0.0,
"condition": "NEW",
"serialNumberRequired": false,
"expiryDateRequired": false,
"unknown": false,
"createdAt": "2024-03-05T22:20:44.132006Z",
"updatedAt": "2024-04-01T14:31:19.885955Z",
"otherIds": []
},
"channelFulfillmentItemId": null,
"quantity": 1,
"meta": {}
}
],
"createdAt": "2024-06-04T05:53:31.054574Z",
"updatedAt": "2024-06-04T05:53:31.054574Z",
"attachments": [
{
"id": "75d23312-d2c1-4830-95ae-6e739c6f23ec",
"fileName": "听雨 (24 x 26.25)_PFPWig.jpg",
"path": "95d73baf-76ba-4bea-86ac-1534c5e5d4aa/2024-04-24/fulfillment/听雨__24_x_26.25__PFPWig_bdsL5YZcA8A5Wcfshhj3E.jpg",
"createdAt": "2024-06-04T05:53:31.054574Z",
"updatedAt": "2024-06-04T05:53:31.054574Z"
}
],
"shipments": [
{
"id": "a0a1e200-05f1-4d99-8954-bb2e34741888",
"fulfillmentId": "295dbfaa-de55-40aa-ad6b-71f059722888",
"manifestId": null,
"channelShipmentId": null,
"status": "CREATED",
"meta": {},
"shippingCarrier": {
"id": "OTHER",
"name": "Other",
"createdAt": "2024-03-25T00:09:52.442733Z",
"updatedAt": "2024-03-25T00:09:52.729273Z"
},
"trackingNumber": "",
"trackingUrl": "",
"items": [
{
"channelShipmentItemId": null,
"product": {
"id": "3775cc37-30e7-4579-a58e-c9adda6fa888",
"organization": {
"id": "3f424caf-0eba-4813-b3e7-7ca0393af888",
"name": "test organization",
"createdAt": "2024-03-05T22:17:23.520948Z",
"updatedAt": "2024-04-09T21:15:15.615765Z"
},
"sku": "test",
"brand": {
"id": "e0cbbf33-cbea-4867-9fd9-5d72f22c2888",
"name": "Sony",
"nameNormalized": "sony",
"createdAt": "2024-06-04T03:16:22.617577Z"
},
"gtin": "7045557637838",
"name": "Test Product",
"remarks": "test.",
"imageMain": "95d73baf-76ba-4bea-86ac-1534c5e5d4aa/2024-04-23/avatar/听雨__24_x_26.25__PFPWig_4_YXKT59pJLuoIk82VgaF.jpg",
"packageLengthMm": 33.27078,
"packageWidthMm": 64.29312,
"packageHeightMm": 96.57682,
"shippingWeightKg": 76.44365,
"caseUnit": "EACH",
"casePack": 2,
"caseLengthMm": 34.340958,
"caseWidthMm": 20.323586,
"caseHeightMm": 12.659683,
"caseWeightKg": 0.35708416,
"condition": "NEW",
"serialNumberRequired": true,
"expiryDateRequired": true,
"unknown": false,
"createdAt": "2024-06-04T03:16:22.617577Z",
"updatedAt": "2024-06-04T03:31:28.192345Z",
"otherIds": []
},
"quantity": 2,
"meta": {}
},
{
"channelShipmentItemId": null,
"product": {
"id": "bab7c35b-2ecb-4b40-be82-8dc1e0a86888",
"organization": {
"id": "3f424caf-0eba-4813-b3e7-7ca0393af888",
"name": "test organization",
"createdAt": "2024-03-05T22:17:23.520948Z",
"updatedAt": "2024-04-09T21:15:15.615765Z"
},
"sku": "SKU-GREY",
"brand": {
"id": "5643b7ee-7df1-48c6-b690-1e29ffa8ab33",
"name": "",
"nameNormalized": "",
"createdAt": "2024-03-05T22:17:28.679732Z"
},
"gtin": "",
"name": "SKU GREY",
"remarks": "",
"imageMain": "",
"packageLengthMm": 1500.0,
"packageWidthMm": 260.0,
"packageHeightMm": 810.0,
"shippingWeightKg": 35.0,
"caseUnit": "CARTON",
"casePack": 1,
"caseLengthMm": 0.0,
"caseWidthMm": 0.0,
"caseHeightMm": 0.0,
"caseWeightKg": 0.0,
"condition": "NEW",
"serialNumberRequired": false,
"expiryDateRequired": false,
"unknown": false,
"createdAt": "2024-03-05T22:20:44.132006Z",
"updatedAt": "2024-04-01T14:31:19.885955Z",
"otherIds": []
},
"quantity": 1,
"meta": {}
}
],
"labels": [
{
"id": "788ea3ec-9cdf-4655-b3e8-fd5e93431888",
"type": "PREPAID",
"carrier": "",
"trackingNumber": "",
"trackingUrl": "",
"amount": 0.0,
"amountCurrency": "USD",
"filePath": "95d73baf-76ba-4bea-86ac-1534c5e5d4aa/2024-04-24/shipping_label/Snipaste_2024_04_15_13_37_25_wgfZCvetlGQmtEBqnQ__m.png",
"purchasedLabel": null,
"createdAt": "2024-06-04T05:53:31.054574Z",
"updatedAt": "2024-06-04T05:53:31.054574Z"
}
],
"packages": [],
"createdAt": "2024-06-04T05:53:31.054574Z",
"updatedAt": "2024-06-04T05:53:31.054574Z"
}
],
"orderOrganization": {
"id": "3f424caf-0eba-4813-b3e7-7ca0393af888",
"name": "test organization",
"createdAt": "2024-03-05T22:17:23.520948Z",
"updatedAt": "2024-04-09T21:15:15.615765Z"
},
"shipByDate": null,
"deliverByDate": null,
"customerNote": null,
"referenceIds": ["", "test_order_id2", "test_order_ref_id1"],
"orderId": "ae52b0ab-8f0c-4b11-9c13-c5c221228888",
"orderDate": "2024-04-24T06:00:33.889Z",
"orderAccountId": "1ac48942-405a-4841-a7d8-708f50dbe888",
"orderChannelOrderId": "test_order_id2"
}