Skip to main content
Add or remove purchase order approvers

Authorizations

Authorization
string
header
required

Personal API key sent as a bearer token, together with X-Organization-Id. The key must have at least the access level the endpoint requires (read, write or admin).

Headers

X-Organization-Id
string

The organization to act in. Required for personal API keys; list the organizations you can access with GET /v1/organizations.

Path Parameters

id
string<uuid>
required

Body

application/json
add_user_ids
string[]

Members to add as approvers: members with write access who can see the order.

Maximum array length: 20
Required string length: 1 - 255
remove_user_ids
string[]

People to remove as approvers.

Maximum array length: 20
Required string length: 1 - 255
add_team_ids
string<uuid>[]

Teams to add as approvers: each counts as one approver, and any member with write access who can see the order may decide for it. Each needs such a member.

Maximum array length: 20
remove_team_ids
string<uuid>[]

Teams to remove as approvers.

Maximum array length: 20

Response

The purchase order.

company_id
string<uuid>
required

The company that places the order. Its buyer is the company's own recipient, unless an imported order names another.

id
string<uuid>
required
number
string | null
required
title
string | null
required
status
enum<string>
required

closed means closed for invoicing, set by a person; it is not derived from an ERP receipt status. Waiting for approval is not a status: see awaiting_approval.

Available options:
draft,
open,
closed,
cancelled
awaiting_approval
boolean
required

The order has an approval request pending: a draft opens once approved; on an opened order it decides the proposed revision, while the current revision stays in force and can be sent and pushed.

approvers
object[]
required

The people the pending approval request waits for, in the order they were added; empty when none is pending. Teams it waits for are on approval.approver_teams. Who decided an earlier request is on approval.

archived
boolean
required
supplier
object | null
required
buyer
object | null
required

A recipient: the legal entity that placed the order.

owner_user_id
string | null
required
Required string length: 1 - 200
Pattern: ^[A-Za-z0-9_-]+$
agreement
object | null
required
currency_code
string | null
required
commitment_basis
enum<string>
required

lines: the order commits to its active lines. amount_limit: it commits to amount_limit for the scope in scope_description; its lines are price references.

Available options:
lines,
amount_limit
totals
object
required
billing
object
required
revision
integer | null
required

The current commercial revision; null for a draft.

open_alert_count
integer
required

Visible, live alerts from checking the order's invoices against it: neither dismissed, skipped nor credited.

Required range: x >= 0
valid_until
string | null
required
origin
enum<string>
required

Where the order was born and is edited: native in Watchdog, imported in the ERP in source.

Available options:
native,
imported
source
object | null
required

The order's ERP. An imported order's terms, lines and cancellation change there and the next sync brings them in; a native order is pushed there and its copy follows Watchdog.

from_import
boolean
required

Drafted from documents through createPurchaseOrderImport; import has the details.

created_at
string<date-time>
required
updated_at
string<date-time>
required
lifecycle
object
required
emails
object
required

Which emails the order may send its supplier, as the send endpoints enforce them. None for an imported or archived order; messages also after it is closed or cancelled.

status_reason
string | null
required
owner
object | null
required
invoice_approvers
object
required

Who approves the invoices matched to the order, by step and then in the order they were added; not approval.approvers, who approve the order itself. An invoice that bills the order gets them in their steps once Watchdog has read and checked it, in place of the approval rules' approvers. Set with updatePurchaseOrder invoice_approvers.

amount_limit
string | null
required

Excluding VAT.

Pattern: ^-?\d+(?:\.\d+)?$
unordered_charges
enum<string>
required

Invoice lines the order's lines don't cover, like freight: flag raises an unordered_charge alert, accept accepts them up to unordered_charges_limit.

Available options:
flag,
accept
unordered_charges_limit
string | null
required

Set only with accept: the most accepted across the order's invoices, excluding VAT; null accepts them all.

Pattern: ^-?\d+(?:\.\d+)?$
scope_description
string | null
required
issued_date
string | null
required
valid_from
string | null
required
delivery_date
string | null
required

When the goods or service are expected. Needed to push the order.

delivery
object | null
required

Where to deliver. Null delivers to the buyer's own address. Changing it on an opened order records a revision.

buyer_reference
string | null
required

While a draft, empty or still the owner's name, it follows the owner's name. A reference a person writes stays.

sales_order_reference
string | null
required

The supplier's order or confirmation number (Peppol SalesOrderID).

contract_reference
string | null
required

While a draft, empty or still the linked agreement's number, it follows the agreement's number.

project_reference
string | null
required

While a draft, empty or still the code of the order's project (its value of a project dimension), it follows that code.

dimension_values
object[]
required

Where the order's cost is booked, in its company: each line takes these, except where it holds its own value for that dimension, and invoices billing the order take them as coding suggestions. Not part of the terms, so revisions leave it out.

note_to_supplier
string | null
required

Free text for the supplier, printed on the order (Peppol Order Note).

internal_note
string | null
required
budget
string | null
required

Excluding VAT, internal: what the organization expects to spend. Never printed, sent or pushed.

Pattern: ^-?\d+(?:\.\d+)?$
billing_review
object
required

Visible unresolved billing findings. Single invoice is exposed only when exactly one live accepted invoice exists and is accessible.

invoice_checks
object
required

Checks of the accepted invoices against this order, counted over every invoice like billing.

line_items
object[]
required
push_targets
object[]
required

Connections a native order can be pushed to; empty once the ERP holds it, and for imported orders.

latest_push
object | null
required

The latest push of the order.

push_readiness
object[]
required

What the order is missing before it can be pushed; empty when it is ready.

to_fill
object[]
required

What an order made in Watchdog should still get: each dimension the organization requires that a draft does not carry yet (opening needs it), then the agreements that may cover it, while it links none. Fill each, or ask the person. Empty when nothing is missing, and for orders synced from an accounting system.

sent_to_supplier
object | null
required

The latest revision sent to the supplier through Watchdog (sendPurchaseOrder), counting sends that went out or may have (accepted or unconfirmed emails); null when none went out.

supplier_revision
integer | null
required

The latest revision whose terms the supplier has, or may have: sent through Watchdog or marked as sent outside it (sendPurchaseOrder), made by accepting the supplier's own proposal, or revision 1 of an order they confirmed before it opened. Null when they have none.

placement
enum<string>
required

watchdog: placed through Watchdog, with its approval and send. external: ordered outside Watchdog (a web shop, the phone) and recorded here; it needed no order approval and is not sent.

Available options:
watchdog,
external
approval
object | null
required

The order's approval request. A draft's latest: pending, or its decision. Past a draft, the one deciding a proposed revision while one waits, else the one that approved the terms in force. Null when it needed none (opened without approval, or imported), or a draft's request was withdrawn.

approval_required
boolean
required

A draft that an approval rule for orders matches: opening it asks for approval instead. False for opened and imported orders.

opened_at
string<date-time> | null
required
closed_at
string<date-time> | null
required
cancelled_at
string<date-time> | null
required
archived_at
string<date-time> | null
required
import
object | null
required

The import that drafted the order from documents: what they show (intent), what the draft still needs (missing) and the parties as printed. Null for an order created otherwise.

proposed_revision
object | null
required

A change to the order's terms waiting for a decision: an edit that needs approval, or what a supplier's confirmation prints differently. The order keeps its current revision, which is what is sent and pushed, until it is accepted; its terms cannot change meanwhile. Null when none waits.

supplier_reply
object
required

What the order waits for from its supplier, and whether they confirmed it. Derived from the emails sent and the supplier's documents received.