API: StockCardSummaries v2


As a developer of OpenLMIS services, I'd like to be able to easily get stock card summary data that leverages the product model so that my service may understand what stock on hand I have, for a facility and by program using the relationships between Commodity Type, Trade Item and Orderable.

Currently we have GET /api/stockcardsummaries which returns an array of stock cards and their current Stock on Hand. And this resource also has a sub-resource GET /api/stockcardsummaries/nocards which is an array of stock cards which have never been created for Orderables which are approved for the facility/program (via FTAP).

We'd like a v2 of this resource which combines these, accessible at /api/v2/stockcardsummaries which returns a paged array of approved Orderable's Stock on Hand which has fields:

  • Orderable reference (approved Orderables of facility, regardless if there's a stock card or not)

  • stock on hand - either null (if no stock cards) or a positive integer (if more than 0) which is a sum of all stock on hands in the canFulfillForMe field

  • canFulfillForMe - is an un-ordered list where each entry is (this orderables that appear here are the orderable paramater as well as that orderable's list of Orderables in canFulfillForMe):

    • stock card reference

    • orderable reference

    • lot reference (if applicable)

    • stock on hand

    • processedDate - most recent processed date of the stock card's line items (note this is a change from the original stockcardsummaries api)

If there is no stock card for canFulfillForMe entry then is should not be on this list.
Those summaries with empty canFulfillForMe list should be sorted to the end (should be on the last pages).

The parameters are the typical paging parameters as well as:

  • program (required) - uuid

  • facility (required) - uuid

  • orderable ids (optional) - if given as one or more Orderable UUID's takes a sub-list of what program and facility would return (doesn't limit the stock cards returned in the canFullfillForMe field)

  • asOfDate (optional): limits the stock on hand reported in the return as the stock on hand at the end of the given day (ISO 8601 to the day). If asOfDate is further in the future than we have stock card data for, return the last SoH. If asOfDate is further in the past than we have stock card data for, return null.

Example: https://jsoneditoronline.org/?id=4ee0b90fb862cc935af9e3822864b80e


  • new api resource is created as outlined above

  • permissions works the same as existing /api/stockCardSummaries

  • /api/stockCardSummaries continues to work, and is marked in the documentation as deprecated

  • performance tests are duplicated so that we have tests for both the new and the old resources


Mateusz Kwiatkowski
March 1, 2018, 2:05 PM

Two questions:
1. About #3 - the problem with not displaying orderable that has no can fulfill for me entries is that this endpoint is paginated on the server side and removing one item and showing i.e. only 9 out of 10 can be confusing for user and I don't know how our UI pagination component would react
2. Should we reopen this ticket or do it in another one? I saw that a similar bug was created for this screen Yesterday.

Josh Zamor
March 1, 2018, 4:30 PM

Thanks .

Regarding your #1, I think what would make sense to me is to sort the returned paginated list by:

  1. Those that have stock cards

  2. By the existing sort order (I believe it's alphabetical?)

Does this work? It'll be important to keep the pagination work in the database for performance.

Regarding your #2, lets re-open this one to fix the issues in my above comment. For adding sorting lets add a new ticket. Does that work?

Mateusz Kwiatkowski
March 2, 2018, 4:50 PM

I've already fixed all you comments without using sorting so I'll just move it to review right now and skip the sorting. Changes are already on the test server.

Sebastian Brudziński
March 6, 2018, 10:52 AM

The following part has been added to the ticket description:

If there is no stock card for canFulfillForMe entry then is should not be on this list.
Those summaries with empty canFulfillForMe list should be sorted to the end (should be on the last pages).

Joanna Bebak
March 7, 2018, 9:59 AM

I re-tested the ticket, and everything works correctly.



Mateusz Kwiatkowski


Josh Zamor


Story Points


Time tracking


Time remaining





Fix versions