post https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders//fulfillments
Requires
write_orderaccess scope. More access scope
The Create Fulfillment API creates a fulfillment for specific order items and updates their shipping details.
This API is especially useful for:
- Managing the fulfillment process for order line items.
- Updating tracking details for shipments.
- Splitting or combining order items for different fulfillments.
Request Parameters
Public Request Parameters
Path Parameters
| Field | Type | Required | Description |
|---|---|---|---|
order_id | string | Yes | Order's unique identifier. |
Body Parameters
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
line_item_ids | array of strings | No | ["line_item_1", "line_item_2"] | IDs of the line items to fulfill. Use when splitting quantity across fulfillments. |
line_items | array of objects | No | - | Details of line items and their quantities. Used when fulfilling items in specific quantities. |
line_items[].id | string | Yes | ed8af005-1f4e-42d1-859d-99b0fd420781 | Line item ID. |
line_items[].ship_quantity | int32 | Yes | 1 | Quantity to fulfill. 0 means all items will be fulfilled together. |
tracking_number | string | Yes | DHL1231232113 | Tracking number for the shipment. Note: For virtual products, you may enter a placeholder tracking number (e.g., N/A) |
tracking_company | string | No | DHL | Name of the shipping company. |
tracking_company_code | string | No | dhl | Code of the shipping company. |
tracking_url | string | No | https://tracking.dhl.com | Tracking URL for the shipment. |
Response Explanation
Public Response Parameters
Successful Response
| Field | Type | Description | Example |
|---|---|---|---|
fulfillment | object | Fulfillment details. | - |
fulfillment. | string | Unique ID of the fulfillment. | 51c7dd5d-8f49-40c3-b2c1-5dfdeef9946d |
fulfillment. | string | Order ID associated with the fulfillment. | 633130-00000007 |
fulfillment. | string | Status of the fulfillment (shipped, pending, etc.). | shipped |
fulfillment. | string | Name of the shipping company. | 燕文物流 |
fulfillment. | string | Tracking number for the shipment. | 11111111111 |
fulfillment. | string | Code of the shipping company. | DJ-11343 |
fulfillment. | string | URL for tracking the shipment. | https://tracking.example.com |
fulfillment. | string | Timestamp of creation in ISO-8601 format. | 2024-04-22T08:37:12Z |
fulfillment. | string | Timestamp of the last update in ISO-8601 format. | 2024-04-22T08:37:12Z |
fulfillment. | array of objects | List of fulfilled line items. | - |
fulfillment. | string | Line item ID. | ed8af005-1f4e-42d1-859d-99b0fd420781 |
fulfillment. | string | Product ID. | a1a88be0-a1d4-47e4-a2f2-ba6e131cf447 |
fulfillment. | string | Variant ID of the product. | a7175820-36b3-4fc6-9baf-51e3035242ba |
fulfillment. | string | Title of the product variant. | L-blue-T |
fulfillment. | string | Title of the product. | shirt |
fulfillment. | string | Handle of the product. | shirt |
fulfillment. | integer | Quantity of the product fulfilled. | 1 |
fulfillment. | string | Note associated with the line item. | Special instructions |
fulfillment. | string | Fulfillment status for the line item. | shipped |
fulfillment. | string | SKU of the product. | T-M-L-blue-T-A001008 |
fulfillment. | string | Unit for the weight of the product. | kg |
fulfillment. | string | Weight of the product. | 1.10 |
fulfillment. | string | Vendor or supplier of the product. | shoplazza |
fulfillment. | string | URL of the product page. | /products/shirt |
fulfillment. | string | URL of the product image. | //cdn.shoplazza.com/image.jpg |
fulfillment. | string | Price of the product per unit. | 81.00 |
fulfillment. | string | Total price for the fulfilled quantity. | 81.00 |
fulfillment. | string | Original (compare at) price of the product. | 97.00 |
fulfillment. | array of objects | Custom properties of the line item. | [{ "name": "size", "value": "L" }] |
fulfillment. | integer | Quantity refunded from this line item. | 0 |
fulfillment. | string | Total refunded amount for this line item. | 0.00 |
fulfillment. | boolean | Indicates whether the product is taxable. | true |
fulfillment. | boolean | Indicates if shipping is required for the product. | true |
fulfillment. | integer | Quantity being shipped in this fulfillment. | 1 |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Example | Description |
|---|---|---|---|
errors | Array | [ "invalid line_item id"] | A list of errors encountered during the request processing. |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure (e.g., missing required fields or incorrect data types). | Bad Request |
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized | |
| 422 | Unprocessable Entity | line_item is invalid or not provided | invalid line_item id |
| invalid status of the order | Shipment not allowed under current status. | ||
| fulfillment quantity is insufficient | The fulfill failed due to insufficient remaining fulfillment quantity | ||
| ShipQuantity is not provided | ShipQuantity is required |