The FulfillmentRequest resource represents a fulfillment request made by the merchant
or an order management app
to a fulfillment service
for a fulfillment order.
A fulfillment service can accept or reject the fulfillment request.
A fulfillment service can stop fulfilling an accepted fulfillment request if they choose closing the fulfillment order as incomplete. The fulfillment order can be partially fulfilled when a fulfillment service chooses to stop the fulfillment.
The merchant or an order management app can notify the fulfillment service to cancel an accepted fulfillment request by sending a cancellation request. The fulfillment service can accept or reject the cancellation request. The fulfillment order can be partially fulfilled at this time.
The merchant or an order management app can also
cancel
a fulfillment order.
Calling the cancel endpoint results in the fulfilment order being cancelled within Shopify.
This change will not be communicated to the fulfilment service.
If the intention is for a fulfilment service to halt fulfilment activity,
a cancellation request
should be sent to the fulfilment service instead, as described above.
The FulfillmentOrder resource and the merchant_requests field can be used to retrieve
the merchant requests which have been made.
The overall status of these requests is also available using the request_status field of the fulfillment order.
To learn more about the fulfillment request process in the fulfillment workflow, refer to Manage fulfillments as a fulfillment service app guide.
## Resource Properties ### FulfillmentRequest * message: A message for the fulfillment request. * Type: x-string * Example: "The optional message that the merchant included in the request." * sent_at: The timestamp when the request was made. * Type: x-string * Example: "2024-04-01T13:38:11-04:00" * response_data: The response from the fulfillment service. * Type: x-string * Example: {"response"=>{}} * request_options: Whether to notify the customer about the fulfillment request. * Type: x-string * Example: {"notify_customer"=>true} * kind: The kind of request made. * Type: x-string * Example: "fulfillment_request" ## Sends a fulfillment request Sends a fulfillment request to the fulfillment service of a fulfillment order. ### Endpoint /admin/api/#{api_version}/fulfillment_orders/{fulfillment_order_id}/fulfillment_request.json (POST) ### Parameters * api_version (required): * fulfillment_order_id (required): * fulfillment_order_line_items: The fulfillment order line items to be requested for fulfillment. If left blank, all line items of the fulfillment order are requested for fulfillment. * message: An optional message for the fulfillment request. * notify_customer: Whether to notify the customer about the fulfillment request. ### Responses #### 200 Sends a fulfillment request Examples: ##### Sends a fulfillment request to the fulfillment service for all line items on the fulfillment order if fulfillment_order_line_items is left blank Request: ``` POST /admin/api/unstable/fulfillment_orders/1046000806/fulfillment_request.json {"fulfillment_request":{"message":"Fulfill this ASAP please."}} ``` Response: ``` HTTP/1.1 200 OK {"original_fulfillment_order":{"id":1046000806,"created_at":"2025-01-02T11:35:26-05:00","updated_at":"2025-01-02T11:35:27-05:00","shop_id":548380009,"order_id":450789469,"assigned_location_id":24826418,"request_status":"submitted","status":"open","fulfill_at":null,"fulfill_by":null,"supported_actions":["cancel_fulfillment_order"],"destination":{"id":1042572138,"address1":"Chestnut Street 92","address2":"","city":"Louisville","company":null,"country":"United States","email":"bob.norman@mail.example.com","first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","province":"Kentucky","zip":"40202"},"origin":{"address1":null,"address2":null,"city":null,"country_code":"DE","location_id":24826418,"name":"Apple Api Shipwire","phone":null,"province":null,"zip":null},"line_items":[{"id":1072503304,"shop_id":548380009,"fulfillment_order_id":1046000806,"quantity":1,"line_item_id":466157049,"inventory_item_id":39072856,"fulfillable_quantity":1,"variant_id":39072856},{"id":1072503305,"shop_id":548380009,"fulfillment_order_id":1046000806,"quantity":1,"line_item_id":518995019,"inventory_item_id":49148385,"fulfillable_quantity":1,"variant_id":49148385},{"id":1072503306,"shop_id":548380009,"fulfillment_order_id":1046000806,"quantity":1,"line_item_id":703073504,"inventory_item_id":457924702,"fulfillable_quantity":1,"variant_id":457924702}],"outgoing_requests":[{"message":"Fulfill this ASAP please.","request_options":{"notify_customer":false},"sent_at":"2025-01-02T11:35:27-05:00","kind":"fulfillment_request"}],"international_duties":null,"fulfillment_holds":[],"delivery_method":{"id":989232621,"method_type":"shipping","min_delivery_date_time":null,"max_delivery_date_time":null,"additional_information":{"phone":null,"instructions":null,"failed_carriers":null,"pickup_point_id":null},"service_code":null,"detailed_branded_promise":null,"source_reference":null,"presented_name":"Expedited Shipping"}},"submitted_fulfillment_order":{"id":1046000806,"created_at":"2025-01-02T11:35:26-05:00","updated_at":"2025-01-02T11:35:27-05:00","shop_id":548380009,"order_id":450789469,"assigned_location_id":24826418,"request_status":"submitted","status":"open","fulfill_at":null,"fulfill_by":null,"supported_actions":["cancel_fulfillment_order"],"destination":{"id":1042572138,"address1":"Chestnut Street 92","address2":"","city":"Louisville","company":null,"country":"United States","email":"bob.norman@mail.example.com","first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","province":"Kentucky","zip":"40202"},"origin":{"address1":null,"address2":null,"city":null,"country_code":"DE","location_id":24826418,"name":"Apple Api Shipwire","phone":null,"province":null,"zip":null},"line_items":[{"id":1072503304,"shop_id":548380009,"fulfillment_order_id":1046000806,"quantity":1,"line_item_id":466157049,"inventory_item_id":39072856,"fulfillable_quantity":1,"variant_id":39072856},{"id":1072503305,"shop_id":548380009,"fulfillment_order_id":1046000806,"quantity":1,"line_item_id":518995019,"inventory_item_id":49148385,"fulfillable_quantity":1,"variant_id":49148385},{"id":1072503306,"shop_id":548380009,"fulfillment_order_id":1046000806,"quantity":1,"line_item_id":703073504,"inventory_item_id":457924702,"fulfillable_quantity":1,"variant_id":457924702}],"outgoing_requests":[{"message":"Fulfill this ASAP please.","request_options":{"notify_customer":false},"sent_at":"2025-01-02T11:35:27-05:00","kind":"fulfillment_request"}],"international_duties":null,"fulfillment_holds":[],"delivery_method":{"id":989232621,"method_type":"shipping","min_delivery_date_time":null,"max_delivery_date_time":null,"additional_information":{"phone":null,"instructions":null,"failed_carriers":null,"pickup_point_id":null},"service_code":null,"detailed_branded_promise":null,"source_reference":null,"presented_name":"Expedited Shipping"}},"unsubmitted_fulfillment_order":null} ``` ##### Sends a fulfillment request to the fulfillment service of a fulfillment order for the specified line items Request: ``` POST /admin/api/unstable/fulfillment_orders/1046000807/fulfillment_request.json {"fulfillment_request":{"message":"Fulfill this ASAP please.","fulfillment_order_line_items":[{"id":1072503307,"quantity":1},{"id":1072503308,"quantity":1}],"notify_customer":true}} ``` Response: ``` HTTP/1.1 200 OK {"original_fulfillment_order":{"id":1046000807,"created_at":"2025-01-02T11:35:27-05:00","updated_at":"2025-01-02T11:35:27-05:00","shop_id":548380009,"order_id":450789469,"assigned_location_id":24826418,"request_status":"submitted","status":"open","fulfill_at":null,"fulfill_by":null,"supported_actions":["cancel_fulfillment_order"],"destination":{"id":1042572139,"address1":"Chestnut Street 92","address2":"","city":"Louisville","company":null,"country":"United States","email":"bob.norman@mail.example.com","first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","province":"Kentucky","zip":"40202"},"origin":{"address1":null,"address2":null,"city":null,"country_code":"DE","location_id":24826418,"name":"Apple Api Shipwire","phone":null,"province":null,"zip":null},"line_items":[{"id":1072503307,"shop_id":548380009,"fulfillment_order_id":1046000807,"quantity":1,"line_item_id":466157049,"inventory_item_id":39072856,"fulfillable_quantity":1,"variant_id":39072856},{"id":1072503308,"shop_id":548380009,"fulfillment_order_id":1046000807,"quantity":1,"line_item_id":518995019,"inventory_item_id":49148385,"fulfillable_quantity":1,"variant_id":49148385}],"outgoing_requests":[{"message":"Fulfill this ASAP please.","request_options":{"notify_customer":true},"sent_at":"2025-01-02T11:35:27-05:00","kind":"fulfillment_request"}],"international_duties":null,"fulfillment_holds":[],"delivery_method":{"id":989232622,"method_type":"shipping","min_delivery_date_time":null,"max_delivery_date_time":null,"additional_information":{"phone":null,"instructions":null,"failed_carriers":null,"pickup_point_id":null},"service_code":null,"detailed_branded_promise":null,"source_reference":null,"presented_name":"Expedited Shipping"}},"submitted_fulfillment_order":{"id":1046000807,"created_at":"2025-01-02T11:35:27-05:00","updated_at":"2025-01-02T11:35:27-05:00","shop_id":548380009,"order_id":450789469,"assigned_location_id":24826418,"request_status":"submitted","status":"open","fulfill_at":null,"fulfill_by":null,"supported_actions":["cancel_fulfillment_order"],"destination":{"id":1042572139,"address1":"Chestnut Street 92","address2":"","city":"Louisville","company":null,"country":"United States","email":"bob.norman@mail.example.com","first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","province":"Kentucky","zip":"40202"},"origin":{"address1":null,"address2":null,"city":null,"country_code":"DE","location_id":24826418,"name":"Apple Api Shipwire","phone":null,"province":null,"zip":null},"line_items":[{"id":1072503307,"shop_id":548380009,"fulfillment_order_id":1046000807,"quantity":1,"line_item_id":466157049,"inventory_item_id":39072856,"fulfillable_quantity":1,"variant_id":39072856},{"id":1072503308,"shop_id":548380009,"fulfillment_order_id":1046000807,"quantity":1,"line_item_id":518995019,"inventory_item_id":49148385,"fulfillable_quantity":1,"variant_id":49148385}],"outgoing_requests":[{"message":"Fulfill this ASAP please.","request_options":{"notify_customer":true},"sent_at":"2025-01-02T11:35:27-05:00","kind":"fulfillment_request"}],"international_duties":null,"fulfillment_holds":[],"delivery_method":{"id":989232622,"method_type":"shipping","min_delivery_date_time":null,"max_delivery_date_time":null,"additional_information":{"phone":null,"instructions":null,"failed_carriers":null,"pickup_point_id":null},"service_code":null,"detailed_branded_promise":null,"source_reference":null,"presented_name":"Expedited Shipping"}},"unsubmitted_fulfillment_order":{"id":1046000808,"created_at":"2025-01-02T11:35:27-05:00","updated_at":"2025-01-02T11:35:27-05:00","shop_id":548380009,"order_id":450789469,"assigned_location_id":24826418,"request_status":"unsubmitted","status":"open","fulfill_at":null,"fulfill_by":null,"supported_actions":["request_fulfillment","create_fulfillment","hold","merge"],"destination":{"id":1042572140,"address1":"Chestnut Street 92","address2":"","city":"Louisville","company":null,"country":"United States","email":"bob.norman@mail.example.com","first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","province":"Kentucky","zip":"40202"},"origin":{"address1":null,"address2":null,"city":null,"country_code":"DE","location_id":24826418,"name":"Apple Api Shipwire","phone":null,"province":null,"zip":null},"line_items":[{"id":1072503309,"shop_id":548380009,"fulfillment_order_id":1046000808,"quantity":1,"line_item_id":703073504,"inventory_item_id":457924702,"fulfillable_quantity":1,"variant_id":457924702}],"outgoing_requests":[],"international_duties":null,"fulfillment_holds":[],"delivery_method":{"id":989232623,"method_type":"shipping","min_delivery_date_time":null,"max_delivery_date_time":null,"additional_information":{"phone":null,"instructions":null,"failed_carriers":null,"pickup_point_id":null},"service_code":null,"detailed_branded_promise":null,"source_reference":null,"presented_name":"Expedited Shipping"}}} ``` ## Accepts a fulfillment request Accepts a fulfillment request sent to a fulfillment service for a fulfillment order. ### Endpoint /admin/api/#{api_version}/fulfillment_orders/{fulfillment_order_id}/fulfillment_request/accept.json (POST) ### Parameters * api_version (required): * fulfillment_order_id (required): * message: An optional reason for accepting the fulfillment request. ### Responses #### 200 Accepts a fulfillment request Examples: ##### Accepts a fulfillment request sent to a fulfillment service and updates the fulfillment order Request: ``` POST /admin/api/unstable/fulfillment_orders/1046000809/fulfillment_request/accept.json {"fulfillment_request":{"message":"We will start processing your fulfillment on the next business day."}} ``` Response: ``` HTTP/1.1 200 OK {"fulfillment_order":{"id":1046000809,"created_at":"2025-01-02T11:35:28-05:00","updated_at":"2025-01-02T11:35:28-05:00","shop_id":548380009,"order_id":450789469,"assigned_location_id":24826418,"request_status":"accepted","status":"in_progress","fulfill_at":null,"fulfill_by":null,"supported_actions":["create_fulfillment","request_cancellation"],"destination":{"id":1042572141,"address1":"Chestnut Street 92","address2":"","city":"Louisville","company":null,"country":"United States","email":"bob.norman@mail.example.com","first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","province":"Kentucky","zip":"40202"},"origin":{"address1":null,"address2":null,"city":null,"country_code":"DE","location_id":24826418,"name":"Apple Api Shipwire","phone":null,"province":null,"zip":null},"line_items":[{"id":1072503310,"shop_id":548380009,"fulfillment_order_id":1046000809,"quantity":1,"line_item_id":466157049,"inventory_item_id":39072856,"fulfillable_quantity":1,"variant_id":39072856},{"id":1072503311,"shop_id":548380009,"fulfillment_order_id":1046000809,"quantity":1,"line_item_id":518995019,"inventory_item_id":49148385,"fulfillable_quantity":1,"variant_id":49148385},{"id":1072503312,"shop_id":548380009,"fulfillment_order_id":1046000809,"quantity":1,"line_item_id":703073504,"inventory_item_id":457924702,"fulfillable_quantity":1,"variant_id":457924702}],"outgoing_requests":[],"international_duties":null,"fulfillment_holds":[],"delivery_method":{"id":989232624,"method_type":"shipping","min_delivery_date_time":null,"max_delivery_date_time":null,"additional_information":{"phone":null,"instructions":null,"failed_carriers":null,"pickup_point_id":null},"service_code":null,"detailed_branded_promise":null,"source_reference":null,"presented_name":"Expedited Shipping"}}} ``` ## Rejects a fulfillment request Rejects a fulfillment request sent to a fulfillment service for a fulfillment order. ### Endpoint /admin/api/#{api_version}/fulfillment_orders/{fulfillment_order_id}/fulfillment_request/reject.json (POST) ### Parameters * api_version (required): * fulfillment_order_id (required): * line_items: An optional array of line item rejection details. If none are provided, all line items will be assumed to be unfulfillable.