Purchase Orders

Create a purchase order

Creates a draft purchase order. Use projectId to assign it to a project. Requires an Idempotency-Key.

post/purchase-orders

Request

  • Base URL: https://next-api.saturation.io/v1
  • URL: https://next-api.saturation.io/v1/purchase-orders
  • Auth: HTTP bearer

Query parameters

expandPurchaseOrderExpand[]

Comma list of related data to inline on a purchase order (depth ≤ 2). Unknown key returns 400 expand_invalid.

Headers

Idempotency-Keystring required

A unique 16-255 character key. Reusing the key with the same body returns the first result. Reusing it with a different body returns 409 idempotency_conflict.

Request body

projectIdstring

Project ID or slug. Omit to leave the purchase order unassigned.

numberstring

Purchase order number.

namestring

Purchase order name.

contactIdstring

Vendor contact ID.

budgetLineIdstring

Budget line ID.

dueDatestring date

Payment due date.

serviceStartAtstring date

First service date.

serviceEndAtstring date

Last service date.

notesstring
sortnumber

Example request

{
  "number": "PO-0042",
  "name": "Camera package rental",
  "contactId": "con_77a",
  "budgetLineId": "bud_5510",
  "dueDate": "2026-05-20",
  "serviceStartAt": "2026-05-21",
  "serviceEndAt": "2026-05-24",
  "notes": "Net-30",
  "items": [
    {
      "description": "Alexa Mini LF body",
      "qty": "5",
      "unit": "day",
      "rate": "25000"
    }
  ]
}

Response

The created purchase order (status draft).

idstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

workspaceIdstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

projectIdstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

numberstring nullable

Purchase order number, such as PO-0042.

namestring nullable

Purchase order name.

status'draft' | 'pending' | 'approved' | 'rejected' | 'actualizing' | 'paid' | 'void' required

Current purchase order status.

contactIdstring nullable

Vendor contact ID.

budgetLineIdstring nullable

Budget line ID.

dueDatestring date nullable

Payment due date.

serviceStartAtstring date nullable

First service date.

serviceEndAtstring date nullable

Last service date.

notesstring nullable

Notes about the purchase order.

sortnumber nullable

Display order within the project.

currencystring required

Purchase order currency.

exchangeRatenumber nullable required

Rate from the purchase order currency to the workspace currency.

exchangeRateSourcestring nullable required

Where the exchange rate came from.

createdByIdstring nullable

ID of the user who created the purchase order.

createdAtstring date-time required

Time the purchase order was created.

updatedAtstring date-time required

Time the purchase order was last updated.

Example response

{
  "id": "po_8f2a1c9e",
  "workspaceId": "ws_3b1",
  "projectId": "prj_demo",
  "number": "PO-0042",
  "name": "Camera package rental",
  "status": "pending",
  "contactId": "con_77a",
  "budgetLineId": "bud_5510",
  "dueDate": "2026-05-20",
  "serviceStartAt": "2026-05-21",
  "serviceEndAt": "2026-05-24",
  "notes": "Net-30",
  "sort": 1000,
  "createdById": "usr_aa1",
  "amount": {
    "amount": 152900,
    "currency": "USD"
  },
  "createdAt": "2026-05-18T14:02:11.000Z",
  "updatedAt": "2026-05-20T09:31:00.000Z"
}

Changes

No recorded changes to this operation across all 4 revisions of this API.