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. Required.
`total_amount`	Total value of the received goods. Required.
`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`. Required — at least one item.

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 three 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
By SKU — Provide sku. Ottimate matches it against the sku field of the PO’s line items. This is used only when ottimate_po_item_id and po_external_item_id are not provided; see SKU matching below for how ties are resolved.

Field	Description
`ottimate_po_item_id`	The Ottimate-assigned PO item ID. Required unless `po_external_item_id` or `sku` is provided.
`po_external_item_id`	External ID of the PO item — used for lookup when `ottimate_po_item_id` is not available.
`sku`	SKU of the PO item — used for lookup when neither `ottimate_po_item_id` nor `po_external_item_id` is provided. Max 64 characters.
`quantity`	The quantity actually received for this item. Required. Must be greater than `0.0001`, with up to 4 decimal places.
`price`	Unit price. Optional — if omitted, defaults to the linked PO item’s price.
`uom`	Unit of measure (optional)

SKU matching

When a receipt item is matched by sku and that SKU appears on exactly one PO line item, it resolves to that item directly. When the SKU appears on more than one PO line item, Ottimate tries to disambiguate using the receipt item’s quantity, in order:

Exact match — If exactly one of the matching PO items has an ordered quantity equal to the receipt item’s quantity, the receipt item is linked to that PO item.
Consolidated match — Otherwise, if the receipt item’s quantity equals the sum of the ordered quantities across all PO items sharing that SKU, the single receipt item is expanded into one receipt item per matching PO item, each carrying that PO item’s ordered quantity. Use this when your source system sends one consolidated receipt line for multiple PO lines that share a SKU.
Ambiguous — If neither of the above applies, the request fails with a 400 validation error ({"sku": ["N PO items match sku \"...\". Use Purchase Order Item external_id to disambiguate."]}). Use po_external_item_id or ottimate_po_item_id instead to disambiguate.

API endpoints

Endpoint	Description
`GET /v1/receipts`	List receipts with filters for company, location, PO, status, and date range
`GET /v1/receipts/{id}`	Get a specific receipt with all line items
`POST /v1/receipts`	Create a single receipt
`PATCH /v1/receipts/{id}`	Update an existing receipt
`POST /v1/receipts/bulk`	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