API for updating Stock Request status to RECEIVED

Hi Justin,
Happy New Year!
I hope you are well.
I am stuck on getting the API for updating the request status to RECEIVED after the Stock Request is received at the destination.
Please assist with the API endpoint and sample payload. I also need the endpoint for selecting products within 3 months of the expiry date.
Thank you.

Thank you, Gideon.

This is a really great question and fairly complicated because there are multiple entities involved, each with their own state machines. The requisition on the origin side of the transaction goes through multiple states before it is issued (e.g. created → requested → verifying → picking → picked → checking → issued). We decided to make the requisition status a static property (i.e. something that needs to be set) because deriving the status was expensive and complicated. We might revisit that decision in the future.

But at some point during the requisition state machine (I believe either in the picking or picked state), we create a shipment to track the outbound movement of the stock from the origin location to the destination. Like, the requisition, the shipment has its own state machine (e.g. created → shipped → in-transit → partially received → received). However, unlike the requisition, the shipment status is derived, based on events that occur on the shipment.

Aside: Although the shipment status is derived from events, there is a currentStatus property on shipment, but this is calculated whenever we persist the shipment to the database. This currentStatus property allows us to query shipments by status without requiring expensive joins and/or stored procedures.

On top of that, the shipment is associated with receipts used to determine whether a shipment is in-transit, partially received, or fully received. In cases where you control the destination with OpenBoxes you can simply post receipts against the shipment until the shipment is fully received.

However, if the destination is an unmanaged location (i.e. a customer for which you don’t control) then you can set the status of the shipment by adding an event that signifies the shipment has been received by the destination.

I need to know which scenario you are in (managed or unmanaged destination) before I can comment on the proper APIs to use. And, to be honest, it’s possible that we haven’t exposed an API for your use case yet so bear with us and provide as much details as you can about what you’re trying to accomplish.

I also need the endpoint for selecting products within 3 months of the expiry date.

Regarding the expiration query, let me dig into this a bit more. We expose endpoints that return statistics of the number of products expiring or expired with certain timeframes, but we might not have an API to query the list of expired or expiring products yet.

With that said an API endpoint like that would be straightforward to implement.

Hi Justin,
Thank you so much for the detailed explanation of the process, which has given me more insight. I am in a managed location and integrating the API with another application to trigger a request based on its stock level.