Skip to main content

Fulfillment Request API (v0)

Download OpenAPI specification:Download

The API provides access to the fulfillment request. This API allows you to get information about fulfillment requests and perform operations on them.

Note: Fulfillment requests are immutable. It means that rerouting will create a new fulfillment request even if all items in the fulfillment request stay the same.

Get fulfillment requests for an order

Returns all fulfillment requests created for an order, sorted by creation date in the ascending order (earliest first).

If order wasn't found, then the empty list of fulfillment requests will be returned.

If order wasn't routed yet, then the empty list of fulfillment requests will be returned.

Important: As for now this API will return fulfillment requests even for orders without routing (like in_store_purchase) but this behavior will change soon. And this API will only work for orders where routing is needed. So, build your integrations accordingly.

Important: Maximum number of fulfillment requests this API will return is 2000. If there are more than 2000 fulfillment requests for the order, then the response will have 400 status code (although it is actually not a bad request) and 2000 latest (according to the creaiton date) fulfillment requests.

Authorizations:
newStoreAccessToken
path Parameters
order_uuid
required
string <uuid>

Sales order UUID.

Responses

Response samples

Content type
application/json
{
  • "fulfillment_requests": [
    ]
}

Update the status of order items in a fulfillment request

Update the shipment status for items in the specified fulfillment request.

Important: Do not confuse this API with Fulfillment Provider API. For DC orders please use the Fulfillment Provider API.

Items in a fulfillment request can be marked as shipped or rejected. When you use this API you can't mix shipment and rejection actions on the same call.

Important: If you are doing a partial rejection of items in a fulfillment request, the reroute attempt will not happen until all items in the fulfillment request are in a terminal state.

For fulfillment requests which are routed to store fulfillment nodes, the item state update will only be accepted if the request has not been picked by a store associate. The change in status is only valid for items that are not in a final state (the fulfillment process for the item is considered as complete). The remaining items are not affected by this change.

Important: When you reject items that are currently fulfilled in DC we don't notify DC about items rejection. You are responsible for communicating with DC API to ensure these items will not be shipped.

Rejection reason:

To reject a fulfillment request you must provide the rejection reason "rescinded". This will initiate a re-routing attempt without any changes to inventory levels.

Edge Cases:

  • If your organization's settings allow it (i.e. reroute_to_rejected_fulfillment_nodes is set to true), rejected fulfillment nodes will be downgraded in priority during the routing process. Otherwise, rejected fulfillment nodes will be ignored during future routing attempts (i.e. if reroute_to_rejected_fulfillment_nodes is set to false).
  • If all fulfillment nodes are rejected and you don't want to reroute to these nodes, the rejected items will be put on hold.

Important: The platform emits a separate event for each line item that is marked as shipped, and not a single event for all items. This should be considered when reconciling these events in the ERP you are using to manage such events.

Authorizations:
newStoreAccessToken
path Parameters
ffr_uuid
required
string <uuid>

Fulfillment request UUID

Request Body schema: application/json
required
Array of objects

List of fulfillment request items with target state that a user wants to change.

tracking_code
string non-empty

Tracking code applied to items, which state is being changed to shipped.

carrier
string non-empty

Carrier used to ship items, which state is being changed to shipped.

associate_id
required
string non-empty

Identifier of the associate who is changing the items's states.

required
any or string

Responses

Request samples

Content type
application/json
Example
{
  • "line_items": [
    ],
  • "associate_id": "77d6b285-4c2e-4e7f-b6b4-3e6c153e9934",
  • "reason": "rescinded"
}

Response samples

Content type
application/json
{
  • "error_code": "bad_request",
  • "message": "Incorrect target state for fulfillment request's items: 'some_weird_state'.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"
}