Receipts, receiving purchases

This is the new Receipts endpoint. Looking for the old /api/v1/purchaseorders/{id}/receipts endpoint? See this old page.

With "Receipts" you register received purchase orders.

Receipts can be linked to a specific purchase order or to a supplier to register received products from multiple purchase orders.

You can also receive products that are not on purchase orders. Picqer will then create a new purchase order with the products that are received that were not purchased.

Temporarily 2 receipt versions alongside

There are temporarily 2 versions of receipts in Picqer while we change the core receipt functionality. This means API calls need to transition as well and you’ll temporarily need to accommodate for requests and responses for both of these versions. A user can change the version of a receipt on a per-receipt basis, which means you’ll have to support both versions simultaneously. Once a receipt has been created and at least one product is received, the version of that specific receipt cannot be changed anymore.

In short the changes for v2 receipts are:

We expect to complete the roll-out of v2 receipts within a few months, after which we’ll discontinue v1. Since v1 receipts will then no longer be able to be created in Picqer, you can discontinue the v1 support from that moment as well. This page will be updated with more details at that time.

See this migration guide to learn more about the technical and conceptual changes.

Attributes

Name Type Required Description
idreceipt integer generated Unique Picqer reference
idwarehouse integer optional Linked to resource Warehouses. If you do not provide a idwarehouse, we will select the first warehouse.
version integer optional The version of this receipt (currently 1 or 2).
supplier array optional* Linked to resource Suppliers. Either a supplier or a purchase order is required.
purchaseorder array optional* Linked to resource Purchase orders. Either a supplier or a purchase order is required.
receiptid string generated Per-account receipt number
status string read-only Status of receipt: processing or completed
remarks string optional Remarks about this receipt. (Only v1)
completed_by array optional* User that completed the receipt, empty when the receipt is not yet completed. (Only v1)
completed_by.iduser integer read-only Unique Picqer reference of the user that completed the receipt.
completed_by.name string read-only The name of the user that completed the receipt
amount_received integer read-only Amount of products in this receipt
amount_received_excessive integer read-only Amount of products in this receipt more then purchased. (Only v1)
completed_at string read-only Datetime that this receipt is completed
created string read-only Datetime that this receipt is created
products array required Products in this receipt
products.idreceipt_product integer generated Unique id of this line item
products.idpurchaseorder_product integer read-only Linked to line of purchase order, the product that is being received
products.idproduct integer required Linked to resource Products
products.idpurchaseorder integer read-only Linked to resource Purchase order, as each product can come from a different purchase order
products.productcode string read-only Productcode of product
products.name string read-only Name of product
products.amount integer required Amount that is being received in this receipt
products.amount_ordered integer read-only Amount that was ordered in the purchase order
products.amount_previously_received integer read-only Amount that was received for this product on other receipts. (Only v1)
products.added_by_receipt boolean read-only False if this product was originally ordered, true if this product was added by this receipt
products.stock_location (v1)
products.location (v2)
array read-only Currently linked location to add the stock to on receiving
products.created_at string read-only The datetime a product is received (Only v2)
products.received_by_iduser integer read-only The iduser who registered this product (Only v2)
products.reverted_at string read-only The datetime this product is reverted (Only v2)
products.reverted_by_iduser integer read-only The iduser who reverted this product (Only v2)

Get all receipts

GET https://example.picqer.com/api/v1/receipts
HTTP/1.1 200 OK [ { "idreceipt": 469364, "idwarehouse": 18, "version": 1, "supplier": { "idsupplier": 55151, "name": "Schoenmaker Kramer" }, "purchaseorder": { "idpurchaseorder": 612084, "purchaseorderid": "20201023" }, "receiptid": "RC2020-1071", "status": "processing", "remarks": null, "completed_by": null, "amount_received": 5, "amount_received_excessive": 0, "completed_at": null, "created": "2020-11-11 14:18:42", "updated": "2020-11-11 14:18:42", "products": [ { "idreceipt_product": 14959405, "idpurchaseorder_product": 9473892, "idproduct": 13177709, "idpurchaseorder": 612084, "productcode": "AA568904", "productcode_supplier": "SEC-AA568904", "name": "Secrid Eco Drive Calculator Lumix", "barcode": "5480962989264", "amount": 0, "amount_ordered": 5, "amount_receiving": 0, "added_by_receipt": false, "abc_classification": null }, { "idreceipt_product": 14959407, "idpurchaseorder_product": 9473893, "idproduct": 13177679, "idpurchaseorder": 612084, "productcode": "AT298759", "productcode_supplier": "NES-AT298759", "name": "Nestle Watch Graphing Lumix S", "barcode": "3376627429184", "amount": 3, "amount_ordered": 5, "amount_receiving": 0, "added_by_receipt": false, "abc_classification": null } ] }, ... ]
This endpoint uses pagination.

Filters

You can filter the receipts with the following parameters. Add these filters as querystring parameters to the URL.

Attribute Description Example
receiptid Get the receipt that have this value as receiptid. RC2022-1003
status Only receipts with this status processing
idpurchaseorder Receipts for this purchase order.
idsupplier Receipts for this supplier.
updated_after Get the receipts that are changed since this date and time. 2022-01-01 16:00:00
completed_after Get the receipts that are completed since this date and time. 2022-01-01 16:00:00

Get single receipt

The receipt response differs based on the version of the receipt.

Version 1

GET https://example.picqer.com/api/v1/receipts/{idreceipt}
HTTP/1.1 200 OK { "idreceipt": 469364, "idwarehouse": 18, "version": 1, "supplier": { "idsupplier": 55151, "name": "Schoenmaker Kramer" }, "purchaseorder": { "idpurchaseorder": 612084, "purchaseorderid": "20201023" }, "receiptid": "RC2020-1071", "status": "processing", "remarks": null, "completed_by": null, "amount_received": 5, "amount_received_excessive": 0, "completed_at": null, "created": "2020-11-11 14:18:42", "updated": "2020-11-11 14:18:42", "products": [ { "idreceipt_product": 14959405, "idpurchaseorder_product": 9473892, "idproduct": 13177709, "idpurchaseorder": 612084, "productcode": "AA568904", "productcode_supplier": "SEC-AA568904", "name": "Secrid Eco Drive Calculator Lumix", "barcode": "5480962989264", "amount": 0, "amount_ordered": 5, "amount_receiving": 0, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 5, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 53, "stock_location": { "idlocation": 2059474, "idwarehouse": 18, "parent_idlocation": 2059472, "type": "location", "name": "A.2.1.2", "remarks": null, "unlink_on_empty": false, "location_type": { "idlocation_type": 1, "name": "Standaard", "default": true, "color": "#0000f0" }, "is_bulk_location": false } }, { "idreceipt_product": 14959407, "idpurchaseorder_product": 9473893, "idproduct": 13177679, "idpurchaseorder": 612084, "productcode": "AT298759", "productcode_supplier": "NES-AT298759", "name": "Nestle Watch Graphing Lumix S", "barcode": "3376627429184", "amount": 0, "amount_ordered": 5, "amount_receiving": 0, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 5, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 228, "stock_location": { "idlocation": 2060036, "idwarehouse": 18, "type": "location", "parent_idlocation": 2060035, "name": "B.6.3.1", "remarks": null, "unlink_on_empty": false, "location_type": { "idlocation_type": 1, "name": "Standaard", "default": true, "color": "#0000f0" }, "is_bulk_location": false } } ] }

Version 2

The following example is for a v2 receipt. Note that the products returned in this response are received and added to the stock already. Expected products are not included in this response anymore, you can use the "Get expected products" endpoint to see those.

GET https://example.picqer.com/api/v1/receipts/{idreceipt}
HTTP/1.1 200 OK { "idreceipt": 469364, "receiptid": "RC2020-1071", "idwarehouse": 18, "version": 2, "status": "processing", "supplier": { "idsupplier": 55151, "name": "Schoenmaker Kramer" }, "purchaseorder": { "idpurchaseorder": 612084, "purchaseorderid": "20201023" }, "status": "processing", "remarks": null, "completed_by": null, "amount_received": 1, "completed_at": null, "created": "2020-11-11 14:18:42", "updated": "2020-11-11 14:18:42", "products": [ { "idreceipt_product": 14959405, "idpurchaseorder_product": 9473892, "idproduct": 13177709, "idpurchaseorder": 612084, "productcode": "AA568904", "productcode_supplier": "SEC-AA568904", "name": "Secrid Eco Drive Calculator Lumix", "barcode": "5480962989264", "amount": 1, "amount_ordered": 5, "added_by_receipt": false, "abc_classification": null, "received_by_iduser: 1, "reverted_at": null, "reverted_by_iduser": null, "image": null, "location": { "idlocation": 2059474, "idwarehouse": 18, "parent_idlocation": 2059472, "type": "location", "name": "A.2.1.2", "remarks": null, "unlink_on_empty": false, "location_type": { "idlocation_type": 1, "name": "Standaard", "default": true, "color": "#0000f0" }, "is_bulk_location": false } } ] }

Get expected products

This endpoint only support v2 receipts

This endpoint returns the expected-products, including the strategies that you can use to receive this product. See "Add product" to find out more on using these strategies.

GET https://example.picqer.com/api/v1/receipts/{idreceipt}/expected-products
HTTP/1.1 200 OK [ { "product": { "idproduct": 114, "idvatgroup": 1, "idsupplier": 4, "productcode": "0195949018510", "name": "Apple iPhone 15 Pro", "price": 1000, "fixedstockprice": 0, "productcode_supplier": "", "deliverytime": 0, "description": "", "barcode": "", "unlimitedstock": false, "assembled": false, "type": "normal", "weight": 0, "length": null, "width": null, "height": null, "minimum_purchase_quantity": 0, "purchase_in_quantities_of": 0, "hs_code": "", "country_of_origin": "", "show_on_portal": true, "active": true, "comment_count": 0, "analysis_abc_classification": null, "analysis_pick_amount_per_day": null, "tags": {}, "productfields": [], "images": [], "stock": [], "pricelists": [] }, "totals": { "expected": 10, "received": 5, "remaining": 5 }, "strategies": [ { "strategy": "automatic", "parameters": {}, "ordered": 10, "received": 5, "remaining": 5 }, { "strategy": "purchaseorder_product", "parameters": { "idpurchaseorder_product": 572 }, "purchaseorderid": "PO2024-1163", "ordered": 10, "received": 5, "remaining": 5 }, { "strategy": "new", "parameters": {}, "idpurchaseorder": null, "purchaseorderid": null } ] } ]

You can also request the applicable strategies for a specific product by providing an 'idproduct'.

GET https://example.picqer.com/api/v1/receipts/{idreceipt}/expected-products/{idproduct}
HTTP/1.1 200 OK { "product": { "idproduct": 114, "idvatgroup": 1, "idsupplier": 4, "productcode": "0195949018510", "name": "Apple iPhone 15 Pro", "price": 1000, "fixedstockprice": 0, "productcode_supplier": "", "deliverytime": 0, "description": "", "barcode": "", "unlimitedstock": false, "assembled": false, "type": "normal", "weight": 0, "length": null, "width": null, "height": null, "minimum_purchase_quantity": 0, "purchase_in_quantities_of": 0, "hs_code": "", "country_of_origin": "", "show_on_portal": true, "active": true, "comment_count": 0, "analysis_abc_classification": null, "analysis_pick_amount_per_day": null, "tags": {}, "productfields": [], "images": [], "stock": [], "pricelists": [] }, "totals": { "expected": 10, "received": 5, "remaining": 5 }, "strategies": [ { "strategy": "automatic", "parameters": {}, "ordered": 10, "received": 5, "remaining": 5 }, { "strategy": "purchaseorder_product", "parameters": { "idpurchaseorder_product": 572 }, "purchaseorderid": "PO2024-1163", "ordered": 10, "received": 5, "remaining": 5 }, { "strategy": "new", "parameters": {}, "idpurchaseorder": null, "purchaseorderid": null } ] } ]

Create a new receipt

You can create a receipt for a purchase order by providing 'idpurchaseorder', or for a supplier by providing 'idsupplier'.

POST https://example.picqer.com/api/v1/receipts
{ "idpurchaseorder": 666379, "version": 1 }
HTTP/1.1 201 Created { "idreceipt": 496349, "idwarehouse": 18, "version": 1, "supplier": { "idsupplier": 63386, "name": "Heiku" }, "purchaseorder": { "idpurchaseorder": 666379, "purchaseorderid": "20201024" }, "receiptid": "RC2020-1073", "status": "processing", "remarks": null, "completed_by": null, "amount_received": 0, "amount_received_excessive": 0, "completed_at": null, "created": "2020-11-27 12:03:43", "updated": "2020-11-27 12:03:43", "products": [ { "idreceipt_product": 15792546, "idpurchaseorder_product": 10412819, "idproduct": 14781906, "idpurchaseorder": 666379, "productcode": "SW10111", "productcode_supplier": "", "name": "Kicker XXL Champ Elite Pro", "barcode": "", "amount": 0, "amount_ordered": 2, "amount_receiving": 0, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 0, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 5, "stock_location": null }, { "idreceipt_product": 15792545, "idpurchaseorder_product": 10412818, "idproduct": 14781890, "idpurchaseorder": 666379, "productcode": "SW10114", "productcode_supplier": "", "name": "Kicker Champ Elite", "barcode": "", "amount": 0, "amount_ordered": 2, "amount_receiving": 0, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 0, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 21, "stock_location": null } ] }

Mark all products as received

This endpoint only supports v1 receipts.

After you created a receipt for a purchase order, you can mark all products as received. This will set the amount received to the amount you ordered.

POST https://example.picqer.com/api/v1/receipts/{idreceipt}/mark-all-received
HTTP/1.1 200 OK { "idreceipt": 496349, "idwarehouse": 18, "version": 1, "supplier": { "idsupplier": 63386, "name": "Heiku" }, "purchaseorder": { "idpurchaseorder": 666379, "purchaseorderid": "20201024" }, "receiptid": "RC2020-1073", "status": "processing", "remarks": null, "completed_by": null, "amount_received": 4, "amount_received_excessive": 0, "completed_at": null, "created": "2020-11-27 12:03:43", "updated": "2020-11-27 12:03:43", "products": [ { "idreceipt_product": 15792546, "idpurchaseorder_product": 10412819, "idproduct": 14781906, "idpurchaseorder": 666379, "productcode": "SW10111", "productcode_supplier": "", "name": "Kicker XXL Champ Elite Pro", "barcode": "", "amount": 2, "amount_ordered": 2, "amount_receiving": 2, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 0, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 5, "stock_location": null }, { "idreceipt_product": 15792545, "idpurchaseorder_product": 10412818, "idproduct": 14781890, "idpurchaseorder": 666379, "productcode": "SW10114", "productcode_supplier": "", "name": "Kicker Champ Elite", "barcode": "", "amount": 2, "amount_ordered": 2, "amount_receiving": 2, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 0, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 21, "stock_location": null } ] }

Complete receipt

If you complete a receipt, we will set the status to "completed". For v1 receipts, products are added to the stock at this point.

As a response you do not see the status changed, this will be done in the background. If you retrieve the receipt again, you see status changed to 'completed' and the user and date of the completion filled.

PUT https://example.picqer.com/api/v1/receipts/{idreceipt}
{ "status": "completed" }
HTTP/1.1 200 OK { "idreceipt": 496349, "idwarehouse": 18, "version": 1, "supplier": { "idsupplier": 63386, "name": "Heiku" }, "purchaseorder": { "idpurchaseorder": 666379, "purchaseorderid": "20201024" }, "receiptid": "RC2020-1073", "status": "processing", "remarks": null, "completed_by": null, "amount_received": 4, "amount_received_excessive": 4, "completed_at": null, "created": "2020-11-27 12:03:43", "updated": "2020-11-27 12:03:43", "products": [ ... ] }

Delete receipt

It depends on the version of the receipt until when a receipt can be deleted. Products should not have been added to the stock yet. In v1 this means that any "processing" receipt can be deleted. For v2, only receipts where not a single product is received can be deleted.

DELETE https://example.picqer.com/api/v1/receipts/{idreceipt}
HTTP/1.1 204 No Content

Add product

The workings and response for this endpoint differ between the two receipt versions.

Version 1

If you want to mark product for product as received, use this endpoint to increment the amount received by 1. You can provide a barcode or a idproduct.

You get the matched receipt product as a response.

If you want to add a product that is not on the receipt yet, then provide the idproduct and the parameter force as 'true'.

POST https://example.picqer.com/api/v1/receipts/{idreceipt}/products
{ "barcode": "2745515900917" }
HTTP/1.1 200 OK { "idreceipt_product": 15793402, "idpurchaseorder_product": 10413052, "idproduct": 13177749, "idpurchaseorder": 666408, "productcode": "BP673709", "productcode_supplier": "OPE-BP673709", "name": "Opel LZ20 Color", "barcode": "2745515900917", "amount": 1, "amount_ordered": 5, "amount_receiving": 1, "added_by_receipt": false, "abc_classification": null, "amount_previously_received": 0, "amount_more_than_ordered": 0, "amount_backorders": 0, "image": null, "stock": 24, "stock_location": { "idlocation": 2059871, "idwarehouse": 18, "type": "location", "parent_idlocation": 2059870, "name": "B.3.3.1", "remarks": null, "unlink_on_empty": false, "location_type": { "idlocation_type": 1, "name": "Standaard", "default": true, "color": "#0000f0" }, "is_bulk_location": false } }

Version 2

You can receive a product by providing the associated purchase-order product. The amount and location will be used to directly add the product to the stock at the given location, this can also be a container.

POST https://example.picqer.com/api/v1/receipts/{idreceipt}/products
{ "idproduct": 78, "idpurchaseorder_product": 493, "amount": 1, "idlocation": 664 }
HTTP/1.1 200 OK [ { "idreceipt_product": 946, "idpurchaseorder": 113, "idpurchaseorder_product": 493, "idproduct": 78, "purchaseorderid": "PO2024-1112", "productcode": "AU605533", "productcode_supplier": "APP-AU605533", "name": "Apple Watch Color", "barcode": "4728410784335", "abc_classification": null, "image": null, "amount": 1, "amount_ordered": 10, "added_by_receipt": false, "received_by_iduser: 1, "reverted_at": null, "reverted_by_iduser": null, "location": { "idlocation": 664, "idwarehouse": 1, "type": "container", "name": "Container 2", "remarks": "" } } ]

The example above implicitly uses the "purchaseorder_product" strategy by default, you can otherwise choose to use 'automatic' or 'new'.

The 'automatic' strategy will divide the amount over purchase-orders which expect the product. The "new" strategy will add the product to a new purchase-order.

Note that the 'automatic' strategy can return multiple results, 1 per associated purchaseorder-product.

POST https://example.picqer.com/api/v1/receipts/{idreceipt}/products
{ "idproduct": 78, "strategy": "automatic", "amount": 10, "idlocation": 664 }
HTTP/1.1 200 OK [ { "idreceipt_product": 946, "idpurchaseorder": 113, "idpurchaseorder_product": 493, "idproduct": 78, "purchaseorderid": "PO2024-1112", "productcode": "AU605533", "productcode_supplier": "APP-AU605533", "name": "Apple Watch Color", "barcode": "4728410784335", "abc_classification": null, "image": null, "amount": 5, "amount_ordered": 10, "added_by_receipt": false, "received_by_iduser: 1, "reverted_at": null, "reverted_by_iduser": null, "location": { "idlocation": 664, "idwarehouse": 1, "type": "container", "name": "Container 2", "remarks": "" } }, { "idreceipt_product": 947, "idpurchaseorder": 114, "idpurchaseorder_product": 494, "idproduct": 78, "purchaseorderid": "PO2024-1113", "productcode": "AU605533", "productcode_supplier": "APP-AU605533", "name": "Apple Watch Color", "barcode": "4728410784335", "abc_classification": null, "image": null, "amount": 5, "amount_ordered": 5, "added_by_receipt": false, "received_by_iduser: 1, "reverted_at": null, "reverted_by_iduser": null, "location": { "idlocation": 664, "idwarehouse": 1, "type": "container", "name": "Container 2", "remarks": "" } }, ]

Revert product

This endpoint only supports v2 receipts.

You can revert a received product only when the stock is still available, this will decrease the stock by the received amount and will mark the receipt-product as reverted.

POST https://example.picqer.com/api/v1/receipts/{idreceipt}/products/{idreceipt_product}/revert
HTTP/1.1 200 OK { "idreceipt_product": 946, "idpurchaseorder": 113, "idpurchaseorder_product": 493, "idproduct": 78, "purchaseorderid": "PO2024-1112", "productcode": "AU605533", "productcode_supplier": "APP-AU605533", "name": "Apple Watch Color", "barcode": "4728410784335", "abc_classification": null, "image": null, "amount": 1, "amount_ordered": 10, "added_by_receipt": false, "received_by_iduser: 1, "reverted_at": "2024-03-11 10:09", "reverted_by_iduser": 1243, "location": { "idlocation": 664, "idwarehouse": 1, "type": "container", "name": "Container 2", "remarks": "" } }

Change amount or location of product on receipt

This endpoint only supports v1 receipts.

Use this endpoint if you want to provide a specific amount that is received, or change the linked stock location.

Provide delta to change the amount up or down, or provide amount to set the amount to the given value.

Provide stock_idlocation to change the linked location to receive the stock on. You can only provide a location that is already linked to the product or 'null' to select "no specific location".

PUT https://example.picqer.com/api/v1/receipts/{idreceipt}/products/{idreceipt_product}
{ "delta": 2 }
HTTP/1.1 200 OK { "idreceipt_product": 15793402, ... "amount": 3, "amount_ordered": 5, ... }

Comments

Comments are supported on receipts.

Read more Returns