---
title: "Create purchase order"
method: POST
path: "/v1/purchase-orders"
tags: ["Purchase Order Management"]
---

# Create purchase order

`POST /v1/purchase-orders`

## Request

- Base URL: `https://api.prod.goaugment.com`
- URL: `https://api.prod.goaugment.com/v1/purchase-orders`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/goaugment/apis/augment-api/docs/v1/purchase-orders/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a purchase order along with its line items and its vendor and buyer contact records, in a single call.

This endpoint creates only. A `purchaseOrderNumber` you have already used returns `409 Conflict` rather than updating the existing purchase order.

The vendor and contacts are matched before being created: reusing a `vendor.vendorCode` or a contact you have sent before links the new purchase order to the existing record instead of duplicating it.

`purchaseOrderDate` accepts either a calendar day (`2026-08-18`) or a full timestamp; only the UTC calendar day is stored.

## Request body

- PurchaseOrderRequest: Creates a purchase order together with its line items and its vendor and buyer contact records.
  - `purchaseOrder` object, required
    - `purchaseOrderNumber` string, required: Your purchase order number. Unique within your system.
    - `internalPurchaseOrderNumber` string, nullable
    - `status` 'OPEN' | 'CLOSED' | 'CANCELED', required: Lifecycle state of a purchase order or one of its line items.
    - `purchaseOrderDate` string, required: Day the purchase order was issued. A calendar day (`2026-08-18`) or a full timestamp is accepted; only the UTC calendar day is stored.
    - `customData` object, nullable
  - `lineItems` PurchaseOrderLineItemRequest[], required: The ordered lines. May be empty.
    - `lineNumber` string, required: Your line identifier. Unique within the purchase order.
    - `sku` string, nullable
    - `description` string, nullable
    - `orderedQuantity` integer, nullable
    - `openQuantity` integer, nullable
    - `unitOfMeasure` string, nullable
    - `unitPrice` string, nullable: Non-negative decimal string with up to 8 integer and 2 fractional digits.
    - `currency` string: ISO 4217 currency code. Defaults to USD when omitted.
    - `status` 'OPEN' | 'CLOSED' | 'CANCELED': Lifecycle state of a purchase order or one of its line items.
    - `expectedArrivalDate` string, nullable: Day this line is expected to arrive. A calendar day (`2026-09-02`) or a full timestamp is accepted; only the UTC calendar day is stored. Send `null` to clear it.
    - `customData` object, nullable: Arbitrary JSON key-value data you want carried on the line.
  - `vendor` object, required: The vendor shipping the purchase order. Matched on vendorCode within your system: an existing vendor is reused rather than duplicated.
    - `name` string, required
    - `vendorCode` string, required: Your vendor identifier. Unique within your system.
  - `vendorContact` object, nullable: A contact at the vendor. At least one of email or phone is required when supplied.
    - `name` string, nullable
    - `email` string, email, nullable
    - `phone` string, nullable: E.164 format, including the country code.
  - `buyerContact` object, required: The buying contact at your organization. At least one of email or phone is required.
    - `name` string, nullable
    - `externalId` string, nullable
    - `email` string, email, nullable
    - `phone` string, nullable: E.164 format, including the country code.
    - `phoneExtension` string, nullable: Digits only.

## Response `201`

Purchase order created successfully

- PurchaseOrderResponse: A purchase order with its line items.
  - `id` string, required: Augment's identifier for the purchase order.
  - `purchaseOrderNumber` string, required
  - `internalPurchaseOrderNumber` string, nullable
  - `status` 'OPEN' | 'CLOSED' | 'CANCELED', required: Lifecycle state of a purchase order or one of its line items.
  - `purchaseOrderDate` string, date, required: The stored UTC calendar day.
  - `customData` object, nullable
  - `lineItems` PurchaseOrderLineItemResponse[], required
    - `id` string, required: Augment's identifier for the line item.
    - `lineNumber` string, required
    - `sku` string, nullable
    - `description` string, nullable
    - `orderedQuantity` integer, nullable
    - `openQuantity` integer, nullable
    - `unitOfMeasure` string, nullable
    - `unitPrice` string, nullable
    - `currency` string, required
    - `status` 'OPEN' | 'CLOSED' | 'CANCELED': Lifecycle state of a purchase order or one of its line items.
    - `expectedArrivalDate` string, date, nullable: The stored UTC calendar day this line is expected to arrive.
    - `customData` object, nullable
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `409`: A purchase order with this purchaseOrderNumber already exists for your system
- `422`: Validation errors

---

[API](https://skmtc.dev/goaugment/apis/augment-api.md) - [All operations](https://skmtc.dev/goaugment/apis/augment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goaugment/apis/augment-api/revisions/b61097634d79?raw)