purchasing API · Marula PSA docs

API reference

27 operations in purchasing. Raw spec: openapi.json.

DELETE/api/v1/external-links/{id}

DELETE /api/external-links/{id}

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`204`
`404`	link not visible in scope

Security: bearer

GET/api/v1/projects/{id}/cost-rollup

GET /api/projects/{id}/cost-rollup — posted PO bills in base currency (ADR 0002 locked) plus the project budget for comparison.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`404`	project not visible in scope

Security: bearer

GET/api/v1/purchase-orders

GET /api/purchase-orders

Parameters

Name	In	Type	Required
`status`	query	—	No
`vendor_id`	query	—	No
`project_id`	query	—	No
`q`	query	—	No

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/purchase-orders

POST /api/purchase-orders

Request body

CreateOrderRequest

Responses

Status	Description
`200`
`404`	vendor or project not visible in scope
`409`	order number already exists

Security: bearer

GET/api/v1/purchase-orders/{id}

GET /api/purchase-orders/{id} — header + lines + receipts + bill.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`404`	order not visible in scope

Security: bearer

PATCH/api/v1/purchase-orders/{id}

PATCH /api/purchase-orders/{id} — draft-only header edits.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

UpdateOrderRequest

Responses

Status	Description
`200`
`404`	order not visible in scope
`409`	order is not a draft

Security: bearer

GET/api/v1/purchase-orders/{id}/bill

GET /api/purchase-orders/{id}/bill

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`404`	no bill recorded for this order

Security: bearer

PUT/api/v1/purchase-orders/{id}/bill

PUT /api/purchase-orders/{id}/bill — record or edit the draft bill.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

RecordBillRequest

Responses

Status	Description
`200`
`409`	order not billable yet, or the bill is already posted

Security: bearer

POST/api/v1/purchase-orders/{id}/bill/post

POST /api/purchase-orders/{id}/bill/post — the rollup moment: locks the ADR 0002 FX snapshot and stamps `posted_at`.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

CloseOrderRequest

Responses

Status	Description
`200`
`404`	no bill recorded
`409`	the bill is already posted

Security: bearer

POST/api/v1/purchase-orders/{id}/cancel

POST /api/purchase-orders/{id}/cancel — draft|ordered, nothing received.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

CancelOrderRequest

Responses

Status	Description
`200`
`409`	order already received goods or is terminal

Security: bearer

POST/api/v1/purchase-orders/{id}/close

POST /api/purchase-orders/{id}/close — received|partially_received → closed; the close disposition is the typed under-receipt record.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

CloseOrderRequest

Responses

Status	Description
`200`
`409`	order is not in a closable state

Security: bearer

GET/api/v1/purchase-orders/{id}/deeplinks

GET /api/purchase-orders/{id}/deeplinks — the one-click open list: vendor portal links first, then PO-level links, then per-line links (with their line context), each https-validated at write time.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`404`	order not visible in scope

Security: bearer

POST/api/v1/purchase-orders/{id}/lines

POST /api/purchase-orders/{id}/lines — draft-only line add.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

OrderLineInput

Responses

Status	Description
`200`
`409`	order is not a draft
`422`	line validation failed

Security: bearer

PATCH/api/v1/purchase-orders/{id}/lines/{line_id}

PATCH /api/purchase-orders/{id}/lines/{line_id} — draft-only line edit.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes
`line_id`	path	string	Yes

Request body

AddOrderLineRequest

Responses

Status	Description
`200`
`404`	order or line not visible in scope
`409`	order is not a draft or the line already received goods

Security: bearer

DELETE/api/v1/purchase-orders/{id}/lines/{line_id}

DELETE /api/purchase-orders/{id}/lines/{line_id} — draft-only.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes
`line_id`	path	string	Yes

Request body

DeleteOrderLineRequest

Responses

Status	Description
`200`
`404`	order or line not visible in scope
`409`	order is not a draft

Security: bearer

GET/api/v1/purchase-orders/{id}/links

GET /api/purchase-orders/{id}/links

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/purchase-orders/{id}/links

POST /api/purchase-orders/{id}/links — PO-level or (with `line_id`) a per-line order/tracking URL.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

CreateExternalLinkRequest

Responses

Status	Description
`200`
`404`	order or line not visible in scope
`422`	line not in this order, or non-https url

Security: bearer

POST/api/v1/purchase-orders/{id}/order

POST /api/purchase-orders/{id}/order — draft → ordered.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

CloseOrderRequest

Responses

Status	Description
`200`
`409`	order is not a draft or has no lines

Security: bearer

POST/api/v1/purchase-orders/{id}/receive

POST /api/purchase-orders/{id}/receive — the receipt that posts into the lane-1 movement ledger at `location_id`.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

ReceiveOrderRequest

Responses

Status	Description
`200`
`404`	order or location not visible in scope
`409`	order not receivable, over-receipt without acknowledgement, or a line without a stock item
`422`	serial numbers inconsistent with the received quantity

Security: bearer

GET/api/v1/vendors

GET /api/vendors

Parameters

Name	In	Type	Required	Description
`q`	query	—	No
`include_inactive`	query	boolean	No

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/vendors

POST /api/vendors

Request body

CreateVendorRequest

Responses

Status	Description
`200`
`409`	vendor code already exists

Security: bearer

GET/api/v1/vendors/{id}

GET /api/vendors/{id} — entity + contacts + links.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`404`	vendor not visible in scope

Security: bearer

PATCH/api/v1/vendors/{id}

PATCH /api/vendors/{id}

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

UpdateVendorRequest

Responses

Status	Description
`200`
`404`	vendor not visible in scope
`409`	vendor code already exists or version conflict

Security: bearer

GET/api/v1/vendors/{id}/contacts

GET /api/vendors/{id}/contacts

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/vendors/{id}/contacts

POST /api/vendors/{id}/contacts — replace-on-write.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

ReplaceContactsRequest

Responses

Status	Description
`200`
`404`	vendor not visible in scope

Security: bearer

GET/api/v1/vendors/{id}/links

GET /api/vendors/{id}/links

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/vendors/{id}/links

POST /api/vendors/{id}/links

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

CreateExternalLinkRequest

Responses

Status	Description
`200`
`404`	vendor not visible in scope
`422`	the url must be https

Security: bearer