PO workflow: API call sequence

As a purchase order moves from upload to submitted draft sales order, OrderBridge calls your ERP connection at each stage. The sequence below shows which endpoints to build first and when each request is sent.

Stage details

1. Ingest

The PO arrives as a PDF upload or email and is parsed into line items. No ERP calls happen at this stage. Everything below is triggered by operator actions on the extracted PO.

2. Match customer

The operator searches for the buying customer by name or code.

• Endpoint: POST /catalog/customers/search with query and limit.
• Return: a hits[] array with erpId and erpName. Alderstone scores match confidence; return rows in relevance order without a confidence field.

3. Match products

Each PO line is matched to an ERP product, by free-text search or SKU lookup.

• Endpoint: POST /catalog/products/search or POST /catalog/products/by-sku.
• Return: hits[] with erpSku, erpProductId, and a description.

4. Addresses

When the order needs ship-to or billing locations:

• Endpoint: POST /catalog/customers/addresses with the matched customerId and an optional kind filter.

5. Price check

For each matched line, OrderBridge asks what the ERP thinks the unit price should be, and flags lines where the PO price disagrees.

• Endpoint: POST /pricing/resolve with customerErpId and productErpId.
• Return: systemUnitPrice in the same currency and precision as the PO line. Return null when no price exists.

6. Allocation (only when SKU caps are configured)

If the company caps how many units of a SKU a customer may order in a period, OrderBridge sums historical usage before allowing the line through.

• Endpoint: POST /sales-orders/usage with customerErpId, sku, periodStart, and periodEnd.
• Return: units. A non-negative integer sum of ordered quantity in the window.

7. Submit

The operator confirms the PO and OrderBridge creates the draft sales order in your ERP.

• Endpoint: POST /sale-draft with poNumber, currency, and lines[].
• Return: saleId, optional human-readable saleNumber, status: "draft", and a receivedAt ISO datetime.
• Idempotency matters here: if the same poNumber is submitted again (retry, double-click, network blip), return the existing saleId instead of creating a duplicate order.

The connection test on save

When a REST integration is saved in Settings → Integrations, OrderBridge immediately calls:

1. POST /health
2. POST /sale-draft with a sample body (PO number DEMO-PO-001, a demo SKU)

Both must succeed before the connection status becomes connected, so make sure your test environment accepts the demo SKU or returns a clear validation error. See Troubleshooting if the test fails.