> This page is for version V1 (default). > For other versions, use one of these documentation indexes: > - V1 (default): https://docs.ottimate.com/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ottimate.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server. # Purchase Receipts 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. > **Info** > > **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](#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`](/api-reference/api-reference/receipts/get-receipts-root) | List receipts with filters for company, location, PO, status, and date range | | [`GET /v1/receipts/{id}`](/api-reference/api-reference/receipts/get-receipts-id) | Get a specific receipt with all line items | | [`POST /v1/receipts`](/api-reference/api-reference/receipts/post-receipts-root) | Create a single receipt | | [`PATCH /v1/receipts/{id}`](/api-reference/api-reference/receipts/patch-receipts-id) | Update an existing receipt | | [`POST /v1/receipts/bulk`](/api-reference/api-reference/receipts/post-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](/api-reference/api-reference/batch/get-batch-id-progress) and [Batch results](/api-reference/api-reference/batch/get-batch-id-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