Skip to main content
POST
Create a purchase order
A client’s authorization to bill up to a set amount. Projects, invoices, and credit notes can be tied to a purchase order to track how much of it is used.

Authorizations

Authorization
string
header
required

An API key created in Settings > API Keys. Each key is either Read-Only or Full Access, chosen when the key is created. A Read-Only key can only make GET requests; POST, PATCH, and DELETE requests made with it return a 403 with the message This API key is read-only.

Body

application/json
number
string
required

The purchase order number issued by the client (max 255 chars).

name
string
required

The name of the purchase order (max 255 chars).

amount
number
required

The total amount authorized by the purchase order. Must be between 0.01 and 99999999999.

clientId
string
required

The client ID (uuid) the purchase order belongs to. Cannot be changed after creation.

currency
string

The ISO 4217 currency code of the purchase order. Must be the workspace currency or, when Multi-Currency is enabled, one of the workspace's currencies. Defaults to the client's currency when Multi-Currency is enabled, otherwise the workspace currency.

includeTax
boolean

Whether tax on invoices and credit notes counts toward the amount used. Defaults to true.

isActive
boolean

Whether the purchase order is active. Defaults to true.

start
string<date> | null

The start date of the purchase order. Must be in the form YYYY-MM-DD and on or before end.

end
string<date> | null

The end date of the purchase order. Must be in the form YYYY-MM-DD and on or after start.

notes
string | null

Notes about the purchase order (max 5000 chars).

contactId
string | null

The contact ID (uuid) for the purchase order. Must be a contact of the client.

Response

200

id
string

The unique identifier for the object.

number
string

The purchase order number issued by the client.

name
string

The name of the purchase order.

amount
number

The total amount authorized by the purchase order, in the purchase order's currency.

currency
string

The ISO 4217 currency code of the purchase order.

includeTax
boolean

Whether tax on invoices and credit notes counts toward amountUsed.

isActive
boolean

Whether the purchase order is active. Only active purchase orders can be added to projects, invoices, and credit notes.

start
string<date> | null

The start date of the purchase order. Will be in the form YYYY-MM-DD. null when the purchase order has no start date.

end
string<date> | null

The end date of the purchase order. Will be in the form YYYY-MM-DD. null when the purchase order has no end date.

notes
string | null

Notes about the purchase order.

createdAt
string<date-time>

The timestamp when the object was created.

client
object

The client the purchase order belongs to.

contact
object | null

The client contact associated with the purchase order.

amountUsed
number

The total of open and paid invoices on the purchase order, less open and applied credit notes. Excludes tax when includeTax is false. This is a calculated value.

amountAvailable
number

The amount remaining after amountUsed is subtracted. Negative when the purchase order is exceeded. This is a calculated value.