Skip to main content

Download PO Sample (CSV/XLSX)

POST 
/api/suppliers/:supplier/po-sample

Generate and download a 3-row sample of the file the supplier will receive when this PO is submitted. Supports both CSV and XLSX (controlled by format). Backs the per-supplier PO file attachment column picker so users can preview the layout before saving.

Required scope: suppliers:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Request body (all optional):

  • format (string, csv | xlsx) — Output format. Defaults to csv. Use xlsx to preview the spreadsheet with text-typed cells (no scientific-notation corruption of long barcodes/SKUs).
  • columns (array of strings) — Unsaved column selection to preview. If omitted, the saved supplier preference is used; if that is also empty, the tenant default falls through, then the system default (every registered column).

Valid column keys (current registry): purchase_order, sku, barcode, supplier_sku, name, qty_ordered, unit_cost, extended_cost. Unknown keys are silently dropped.

CSV behavior: Values are written as plain CSV strings — quoted when they contain commas, quotes, or newlines per RFC 4180. No formula-prefix escaping is applied; long numeric-text columns (barcode, SKU) may be coerced to scientific notation by Excel on open. Use XLSX format to avoid that.

XLSX behavior: Numeric-text columns are written with t="inlineStr" cells (force text), quantities as integers, costs with the #,##0.00 price format.

The response is a binary file download — text/csv for CSV, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for XLSX. Not JSON.

Validation:

  • format must be one of csv, xlsx (any other value returns 422).

Authentication: Requires Bearer token. Scope: suppliers:rw.

Request​

Responses​

Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.