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 | No | DHL1231232113 | Tracking number for the shipment. |
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 | Example | Description |
|---|---|---|---|
fulfillment | object | - | Fulfillment details. |
fulfillment.id | string | 51c7dd5d-8f49-40c3-b2c1-5dfdeef9946d | Unique ID of the fulfillment. |
fulfillment.order_id | string | 633130-00000007 | Order ID associated with the fulfillment. |
fulfillment.status | string | shipped | Status of the fulfillment (shipped, pending, etc.). |
fulfillment.tracking_company | string | 燕文物流 | Name of the shipping company. |
fulfillment.tracking_number | string | 11111111111 | Tracking number for the shipment. |
fulfillment.tracking_company_code | string | DJ-11343 | Code of the shipping company. |
fulfillment.tracking_url | string | https://tracking.example.com | URL for tracking the shipment. |
fulfillment.created_at | string | 2024-04-22T08:37:12Z | Timestamp of creation in ISO-8601 format. |
fulfillment.updated_at | string | 2024-04-22T08:37:12Z | Timestamp of the last update in ISO-8601 format. |
fulfillment.line_items | array of objects | - | List of fulfilled line items. |
fulfillment.line_items[].id | string | ed8af005-1f4e-42d1-859d-99b0fd420781 | Line item ID. |
fulfillment.line_items[].product_id | string | a1a88be0-a1d4-47e4-a2f2-ba6e131cf447 | Product ID. |
fulfillment.line_items[].variant_id | string | a7175820-36b3-4fc6-9baf-51e3035242ba | Variant ID of the product. |
fulfillment.line_items[].variant_title | string | L-blue-T | Title of the product variant. |
fulfillment.line_items[].product_title | string | shirt | Title of the product. |
fulfillment.line_items[].product_handle | string | shirt | Handle of the product. |
fulfillment.line_items[].quantity | integer | 1 | Quantity of the product fulfilled. |
fulfillment.line_items[].note | string | Special instructions | Note associated with the line item. |
fulfillment.line_items[].fulfillment_status | string | shipped | Fulfillment status for the line item. |
fulfillment.line_items[].sku | string | T-M-L-blue-T-A001008 | SKU of the product. |
fulfillment.line_items[].weight_unit | string | kg | Unit for the weight of the product. |
fulfillment.line_items[].weight | string | 1.10 | Weight of the product. |
fulfillment.line_items[].vendor | string | shoplazza | Vendor or supplier of the product. |
fulfillment.line_items[].product_url | string | /products/shirt | URL of the product page. |
fulfillment.line_items[].image | string | //cdn.shoplazza.com/image.jpg | URL of the product image. |
fulfillment.line_items[].price | string | 81.00 | Price of the product per unit. |
fulfillment.line_items[].total | string | 81.00 | Total price for the fulfilled quantity. |
fulfillment.line_items[].compare_at_price | string | 97.00 | Original (compare at) price of the product. |
fulfillment.line_items[].properties | array of objects | [{ "name": "size", "value": "L" }] | Custom properties of the line item. |
fulfillment.line_items[].refund_quantity | integer | 0 | Quantity refunded from this line item. |
fulfillment.line_items[].refund_total | string | 0.00 | Total refunded amount for this line item. |
fulfillment.line_items[].taxable | boolean | true | Indicates whether the product is taxable. |
fulfillment.line_items[].requires_shipping | boolean | true | Indicates if shipping is required for the product. |
fulfillment.line_items[].shipping_quantity | integer | 1 | Quantity being shipped in this fulfillment. |
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 |