> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase Orders Field Mapping

> Map source purchase order fields to Better Data purchase order fields.

## Overview

Purchase order import creates PO headers and line items in one request.
Each PO row requires header keys plus at least one line in `lines[]`.

## Quick Start

1. Build `purchaseOrders[]` with PO headers and nested `lines`.
2. POST to `/api/import/purchase-orders`.
3. Poll `/api/import/status/[jobId]` for row-level failures.

## Header Fields

| Better Data Field       | Type   | Required | Example     | Description                             |
| ----------------------- | ------ | -------- | ----------- | --------------------------------------- |
| `externalPoNumber`      | string | YES      | `PO-100245` | Unique PO number (idempotent key).      |
| `supplierId`            | string | YES      | `SUP-ACME`  | Supplier code.                          |
| `destinationLocationId` | string | YES      | `DC-WEST`   | Destination location code.              |
| `status`                | string | No       | `PENDING`   | Optional status, defaults to `PENDING`. |
| `lines`                 | array  | YES      | `[{...}]`   | PO line records.                        |

## Line Fields (`lines[]`)

| Better Data Field | Type   | Required | Example   | Description                           |
| ----------------- | ------ | -------- | --------- | ------------------------------------- |
| `skuId`           | string | YES      | `SKU-001` | SKU identifier.                       |
| `quantity`        | number | YES      | `500`     | Ordered quantity.                     |
| `unitCost`        | number | YES      | `4.25`    | Unit cost for total-cost calculation. |

## Validation Rules

* `purchaseOrders[]` must be present and non-empty.
* Header requires `externalPoNumber`, `supplierId`, `destinationLocationId`, and non-empty `lines[]`.
* Line numbering is derived by array position (`1..n`).

## Common Errors

| Error                          | Meaning                                            | How to fix                                       |
| ------------------------------ | -------------------------------------------------- | ------------------------------------------------ |
| `purchaseOrders[] is required` | Missing PO array.                                  | Send `{ "purchaseOrders": [ ... ] }`.            |
| `required fields missing`      | Header missing key fields or lines array is empty. | Fill required header keys and at least one line. |