Purchase Receipts | Ottimate Developer Documentation

A purchase receipt is a document that confirms goods or services were delivered against a purchase order. Receipts record what was actually received — including quantities and item details — and serve as the second verification step in three-way matching.

Source of truth: Purchase receipts originate in your source system (ERP). Ottimate syncs receipts from your ERP and stores them for document matching — your ERP remains the authoritative source for receipt data.

How receipts work in Ottimate

In a three-way matching workflow, receipts are synced to Ottimate after a purchase order has been created. Each receipt is linked to a specific PO, and a single PO can have one or more receipts (for example, when goods are delivered in multiple shipments).

Receipt line items reference the original PO line items through ottimate_po_item_id, connecting what was received back to what was ordered.

When an invoice arrives, Ottimate matches it against both the PO and its associated receipts to confirm that:

The billed items match what was ordered (PO)
The billed quantities match what was received (receipt)
The billed prices match the agreed amounts (PO)

Receipt status values

Status	Description
`open`	Receipt has been received and is active
`pending`	Receipt is awaiting processing
`flagged`	Receipt requires attention or review
`closed`	Receipt has been fully matched and closed
`archived`	Receipt is no longer active
`deleted`	Receipt has been removed

Key fields

Field	Description
`receipt_number`	Receipt number from your source system. Required.
`external_id`	Your system’s unique identifier. Used for idempotent operations — if a receipt with the same `external_id` already exists, it will be updated instead of duplicated.
`date`	Date the goods were received
`total_amount`	Total value of the received goods
`invoice_number_ref`	Optional invoice reference number
`note`	Optional note or memo for the receipt
`items`	Array of line items, each referencing a PO item with received `quantity`

Linking receipts to purchase orders

Each receipt must reference an existing PO. You can identify the PO in two ways:

By Ottimate ID — Provide ottimate_po_id directly
By lookup fields — Provide erp_vendor_id + ottimate_location_id + either po_number or po_external_id. Ottimate will resolve the PO for you.

Receipt line items

Each receipt line item links back to a PO line item. You can reference the PO item in two ways:

By Ottimate ID — Provide ottimate_po_item_id
By external ID — Provide po_external_item_id (the external ID of the PO item) for lookup

Field	Description
`ottimate_po_item_id`	The Ottimate-assigned PO item ID. Required unless `po_external_item_id` is provided.
`po_external_item_id`	External ID of the PO item — used for lookup when `ottimate_po_item_id` is not available.
`quantity`	The quantity actually received for this item. Required.
`price`	Unit price (optional)
`uom`	Unit of measure (optional)

API endpoints

Endpoint	Description
`GET /receipts`	List receipts with filters for company, location, PO, status, and date range
`GET /receipts/{id}`	Get a specific receipt with all line items
`POST /receipts`	Create a single receipt
`PATCH /receipts/{id}`	Update an existing receipt
`POST /receipts/bulk-upsert/`	Bulk create or update receipts

Bulk operations

The bulk upsert endpoint allows you to create or update multiple receipts in a single request. This operation is processed asynchronously.

Rate limits:

Maximum 100 receipts per request
Maximum 1,000 total line items across all receipts in a single request

The response returns a batch_id that you can use with the Batch progress and Batch results endpoints to track the status of your bulk operation.

Updating receipts

When updating a receipt via PATCH, note the following restrictions:

You cannot change status, receipt_number, external_id, or ottimate_po_id
To update existing line items, include the item id in the items array
To add new line items, omit the id field