Which API endpoint should I use to reduce stock immediately after a sale?

We are currently conducting a PoC to evaluate OpenBoxes for use as an inventory management system for hospital.

In our setup, we would like to integrate with a POS (Point of Sale) system so that when a sale occurs, the stock is automatically reduced via API. Since this is for a hospital, there is no shipping process involved — the inventory should be decreased immediately when the item is sold and API is called.

In this case, I believe the Stock Movements endpoint is not the correct one.

Could you please advise which API endpoint would be appropriate for this use case?

Thanks in advance for your help!

It depends on how much of the “fulfillment” process you’d like to track.

If a sale is just a debit of inventory with no other referencing documents then you can just use a transaction. This is the easiest solution for now, but you lose out on tracing back to the sales order as well as all of the activities related to fulfillment of that sales order. But this would be a good starting point for an integration since it has the least amount of friction and user interaction. We should talk about edge cases though.

If you want to be able to track all fulfillment activities for a sales order (requisition, allocation, picking, shipment, return) then the Stock Movement is potentially more suitable. However, it’s also more complicated and the API is a backend-for-frontend (BFF) so the logic is intrinsically tied to the UI. But you should be able to make it work for your use case.

I am looking to take a more API-first approach to our APIs and will be working on that for another project in the near future. I would love to collaborate with you on your requirements so I can help build out something that works for all potential API clients i.e. our default UI, your idea of a thin layer to support integration and more complicated use cases that involve integration with ERP / order management and a mobile application to handle all fulfillment activities.

For now, I’ll put together a sample API request / response for the transaction approach I mentioned above. If you think you’ll want to track more fulfillment activities (allocation, picking) let’s chat about your requirements.

Justin

p.s. Feel free to reach out and schedule a call if you want to discuss this in more detail.

@openruix Here’s a video describing how you could create a very simple debit transaction to reduce stock.

The request should look something like this

curl --location 'https://<SERVER_URL>/openboxes/api/generic/transaction' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Cookie: JSESSIONID=<JSESSIONID>' \
--data '{
    "inventory": "8a8a9e9665c4f59d0165c54ec6b10028",
    "transactionType": "3",
    "transactionDate": "03/30/2025 23:16:05",
    "transactionEntries": [
        {
            "product": "10001",
            "inventoryItem": "09f5e11685c659b60185cb90814c2832",
            "binLocation": "8a8a9e96687c94ce0168bab17b5c2348",
            "quantity": "-1"
        }
    ]
}'

Please let me know if you have any further questions.

In our setup, we would like to integrate with a POS (Point of Sale) system so that when a sale occurs, the stock is automatically reduced via API.

What POS system are you integrating with?

Since this is for a hospital, there is no shipping process involved — the inventory should be decreased immediately when the item is sold and API is called.

Even though there’s no shipping process, there might be additional metadata and state that you want to track in OpenBoxes. If that’s the case, it might make sense to have a referencing document (Sales Order) attached to the transaction in order to track

  • additional metadata about the sale (terminal, customer, sales campaign, etc)
  • complex state regarding the sale (i.e. transaction for online purchase can’t be posted until will-call pickup)
  • complex workflows like returns or discounts

Again, I’m available if you’d like to talk more about your use case.