Purchase Orders

Sync purchase orders from your ERP into Ottimate for invoice matching

Purchase Orders

Sync purchase orders from your ERP into Ottimate for invoice matching

A purchase order (PO) is a document issued by a buyer to a vendor that specifies the items, quantities, and agreed-upon prices for goods or services. POs serve as the authoritative record of what was ordered and at what cost.

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

How purchase orders work in Ottimate

When a PO is created in your source system, you sync it to Ottimate using the Purchase Orders API. Once in Ottimate, POs are used to match against invoices to validate that billed amounts align with what was ordered.

Each PO can be configured for one of two matching workflows:

Three-way matching (default) — The PO is matched against both a receipt and an invoice. This ensures that what was ordered, received, and billed all agree before payment is released.
Two-way matching — The PO is matched directly against an invoice, skipping the receipt step. Set is_2_way: true when creating the PO. This is common for services or other scenarios where delivery verification is not required.

PO status values

Ottimate tracks the lifecycle of each PO with the following statuses:

Status	Description
`pending`	PO has been received but not yet processed
`open`	PO is active and available for matching
`received`	All items on the PO have been received
`closed`	PO has been fully matched and closed
`flagged`	PO requires attention or review
`archived`	PO is no longer active
`deleted`	PO has been removed

Key fields

Field	Description
`po_number`	PO number from your source system. Required — Ottimate does not auto-generate PO numbers.
`external_id`	Your system’s unique identifier. Used for idempotent operations — if a PO with the same `external_id` already exists, it will be updated instead of duplicated.
`erp_vendor_id`	Vendor identifier from your ERP system
`erp_vendor_name`	Vendor display name from your ERP
`ottimate_location_id`	The Ottimate location this PO belongs to
`is_2_way`	Set to `true` for two-way matching (no receipt required)
`custom_fields`	Custom fields configured for this company’s purchase orders
`items`	Array of line items, each with `name`, `quantity`, `price`, and optional `sku`, `uom`, and `dimensions`

Item-level dimensions

It is common for PO line items to carry dimension mappings (e.g., GL account, department, project) from the source ERP. When an invoice is matched to a PO, Ottimate can inherit these dimensions onto the invoice line items — so coding happens automatically based on what was already set on the purchase order.

Dimensions are passed as key-value pairs on each item, keyed by dimension type (e.g., DEPARTMENT, CLASS). Each value must be a plain string — the ERP dimension code or ID (e.g., "erp_dim_dept123"):

1 {
2   "items": [
3     {
4       "name": "Tomatoes",
5       "quantity": 100,
6       "price": 2.5,
7       "dimensions": {
8         "DEPARTMENT": "erp_dim_dept123",
9         "CLASS": "erp_dim_class456"
10       }
11     }
12   ]
13 }

The dimensions format in POST/PATCH requests differs from GET responses. GET responses return dimensions as rich objects (with id, erp_dimension_id, name, and code fields). Copying dimensions from a GET response and passing them directly to a POST or PATCH request will return a PO4000 validation error: “Dimension value for ‘X’ must be a string.” Always use the plain string value (the ERP code or ID) when writing dimensions.

Dimensions must exist in Ottimate before they can be referenced on a PO. Dimensions are typically synced from your ERP via an Ottimate-hosted integration, or created directly using the Dimensions API. If a PO request references a dimension that does not exist in Ottimate, the request will return a 400 error.

When creating or updating a PO, providing dimensions on a line item replaces all existing dimensions on that item — include every dimension you want to keep. Omit the field or pass null to leave dimensions unchanged.

API endpoints

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

Bulk operations

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

Rate limits:

Maximum 100 purchase orders per request
Maximum 1,000 total line items across all POs 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 purchase orders

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

You cannot change status, po_number, external_id, erp_vendor_id, or ottimate_location_id
To update existing line items, include the item id in the items array
To add new line items, omit the id field — Ottimate will create them automatically