• fulfillment-requests
  • getGet fulfillment requests for an order
  • postUpdate the status of order items in a fulfillment request
• routing-config
  • getGet setting to update shipment status for order
  • postEnable setting to update shipment status for order

API docs by Redocly

Fulfillment Request API (v0)

Download OpenAPI specification:Download

Team Routing: team-routing@newstore.com

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.

fulfillment-requests

Fulfillment Requests

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

/v0/fulfillment_requests/{order_uuid}

Response samples

• 200
• 400
• 500
• default

Content type

application/json

{

• "description": "A GET fulfillment request example",
• "value": {

  • "fulfillment_requests": [

    • {

      • "fulfillment_request_id": "c3b7bea3-997c-40f2-858a-f402491aa1de",
      • "created_at": "2021-11-22T12:51:39.30Z",
      • "status": "completed",
      • "service_level": "GROUND",
      • "fulfillment_node_id": "US01",
      • "items": [

        • {

          • "item_id": "2770fd96-a43f-46ab-b66e-e088067d7825",
          • "product_id": "PID1",
          • "tracking_code": "12345678",
          • "carrier": "USPS",
          • "status": "shipped"

          },
        • {

          • "item_id": "4e0b82b8-ef7d-4f63-8974-17ac22fbf122",
          • "product_id": "PID2",
          • "tracking_code": null,
          • "carrier": null,
          • "status": "rejected"

          }

        ]

      },
    • {

      • "fulfillment_request_id": "f5bd0c3d-77c6-48df-ab10-0fd6124692e8",
      • "created_at": "2021-11-24T14:11:10.22Z",
      • "status": "completed",
      • "service_level": "GROUND",
      • "fulfillment_node_id": "DC01",
      • "items": [

        • {

          • "item_id": "4e0b82b8-ef7d-4f63-8974-17ac22fbf122",
          • "product_id": "PID2",
          • "tracking_code": 987654321,
          • "carrier": "fedex",
          • "status": "shipped"

          }

        ]

      }

    ]

  }

}

Update the status of order items in a fulfillment request

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

Note: Do not confuse this API with the Fulfillment Provider API. For orders routed to a DC or warehouse, the Fulfillment Provider API is the recommended integration path, because it also covers accepting and resending fulfillment requests.

This method is nonetheless supported for DC fulfillment requests, and is the way to act on individual items by item ID rather than by product ID. You can use both APIs on the same fulfillment request: keep accepting requests through Accept fulfillment request and use this method for the item state updates. One trade-off applies: Get shipping status reports shipments recorded through this method only once they have been processed, so it has to be polled. If you need the state to be readable immediately after your update, use Get fulfillment requests for an order.

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:

For fulfillment requests which are routed to store fulfillment nodes, 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 allows rerouting by setting reroute_to_rejected_fulfillment_nodes ( described in this API) to true, rejected fulfillment nodes will be downgraded in priority during the routing process. If all possible nodes for a given location_group in routing configuration are exhausted, it will take the first available fulfillment node as part of the mechanism, resulting in a potential route to the same location on further attempts.
• Setting reroute_to_rejected_fulfillment_nodes to false, fulfillment nodes will be ignored during future routing attempts. 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.

Important: carrier, carrier_service_level, tracking_code and tracking_url apply to the whole call and not to individual items. If a fulfillment request ships as more than one parcel, make one call per parcel with the items it contains.

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 the target state.
tracking_code	string non-empty Tracking code applied to items, which state is being changed to shipped. Applies to every item in the call.
carrier	string >= 0 characters Carrier used to ship items, which state is being changed to shipped. Applies to every item in the call.
tracking_url	string non-empty Tracking URL applied to items, which state is being changed to shipped. Applies to every item in the call. Ignored unless carrier or tracking_code is also provided.
carrier_service_level	string non-empty Speed and type of shipment offered by the carrier, for example FEDEX_GROUND. Applies to every item in the call. Ignored unless carrier or tracking_code is also provided.
associate_id	string non-empty Identifier of the associate who is changing the items's states.
	any or string

Responses

/v0/fulfillment_request/{ffr_uuid}/set_items_states

Request samples

• Payload

Content type

application/json

Example

Payload for marking an item as rejectedPayload for marking an item as shippedPayload for marking an item as rejected

{

• "line_items": [

  • {

    • "item_id": "af7dd63d-198d-40e9-abbb-e4d723881072",
    • "state": "rejected"

    }

  ],
• "associate_id": "77d6b285-4c2e-4e7f-b6b4-3e6c153e9934",
• "reason": "rescinded"

}

Response samples

• 400
• 404
• 500
• default

Content type

application/json

{

• "description": "Bad Request",
• "value": {

  • "error_code": "bad_request",
  • "message": "Incorrect target state for fulfillment request's items: 'some_weird_state'.",
  • "request_id": "ec2f3c9bb016ba971bf6074098363"

  }

}

routing-config

Routing Configuration

Get setting to update shipment status for order

Retrieves the current configuration to determine if you can update the status for fulfillment requests that were processed outside of the NewStore platform, because of possible issues with fulfillment or shipping status updates.

For more information, see the guide.

Authorizations:

newStoreAccessToken

Responses

/v0/config/routing/can_update_ffr_processed_externally

Response samples

• 200

Content type

application/json

{

• "description": "GET external fulfillment setting 200",
• "value": {

  • "value": false,
  • "updated_at": "2021-07-13T20:18:25Z"

  }

}

Enable setting to update shipment status for order

Enables the configuration to allow you to update the status for fulfillment requests that were processed outside of the NewStore platform, because of possible issues with fulfillment or shipping status updates.

For more information, see the guide.

Authorizations:

newStoreAccessToken

Request Body schema: application/json

value required

boolean or null Tenant-based release toggle for updating the status of a fulfillment request in NOM.

Responses

/v0/config/routing/can_update_ffr_processed_externally

Request samples

• Payload

Content type

application/json

{

• "description": "Enable external fulfillment setting request",
• "value": {

  • "value": false

  }

}