API Documentation
Purchase Orders ¶
Purchase Orders ¶
In Productive purchase orders are documents that serve as a buyer’s request to a seller to order goods or services. You can find out more about purchase orders in our Help documentation: Purchase Orders
Purchase Orders always belong to a budget and a vendor (seller). They can have multiple expenses, bills and bill items.
Following diagram shows services in our data hierarchy:
The enumeration status_id can be:
-
1 (Draft)
-
2 (Finalized)
The enumeration payment_status_id can be:
-
1 (Not received)
-
2 (Partially received)
-
3 (Fully received)
Supported filter params
-
deal_id (array)
-
vendor_id (array)
-
id
-
deal_id
-
vendor_id
-
status_id
-
issued_on
-
delivery_on
-
sent_on
-
received_on
-
created_at
-
total_cost
-
total_cost_with_tax
-
total_received
Supported sort params
-
deal_id
-
vendor_id
-
deal_id
-
vendor_id
-
status_id
-
issued_on
-
delivery_on
-
sent_on
-
received_on
-
created_at
-
total_cost
-
total_cost_with_tax
-
total_received
GET /api/v2/purchase_orders/22
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonHeaders
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "22",
"type": "purchase_orders",
"attributes": {
"subject": null,
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": null,
"received_on": null,
"created_at": "2025-11-15T05:07:05.962+01:00",
"number": "1",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "e6a632be9f9199828dbe2222c46ea9a2",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1061"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}Gets a purchase orderGET/api/v2/purchase_orders/{id}
- id
number(required) Example: 1purchase order id
POST /api/v2/purchase_orders
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_orders",
"attributes": {
"currency": "EUR",
"issued_on": "2025-11-15"
},
"relationships": {
"deal": {
"data": {
"type": "quotes",
"id": "703"
}
},
"vendor": {
"data": {
"type": "clients",
"id": "2652"
}
}
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "24",
"type": "purchase_orders",
"attributes": {
"subject": null,
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": null,
"received_on": null,
"created_at": "2025-11-15T05:07:06.092+01:00",
"number": "2",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "4de1f976926e26bff3d551d169d02678",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1062"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}POST /api/v2/purchase_orders
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_orders",
"attributes": {
"currency": "EUR",
"issued_on": "2025-11-15"
},
"relationships": {
"deal": {
"data": {
"type": "quotes",
"id": "0"
}
},
"vendor": {
"data": {
"type": "clients",
"id": "2655"
}
}
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "attribute is invalid",
"source": {
"pointer": "data/attributes/deal"
}
}
]
}Create a purchase orderPOST/api/v2/purchase_orders
PATCH /api/v2/purchase_orders/28
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_orders",
"attributes": {
"currency": "EUR",
"issued_on": "2025-11-15"
},
"relationships": {
"deal": {
"data": {
"type": "quotes",
"id": "708"
}
},
"vendor": {
"data": {
"type": "clients",
"id": "2667"
}
},
"subscribers": {
"data": [
{
"type": "people",
"id": "3781"
},
{
"type": "people",
"id": "3782"
}
]
}
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "28",
"type": "purchase_orders",
"attributes": {
"subject": null,
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": null,
"received_on": null,
"created_at": "2025-11-15T05:07:06.525+01:00",
"number": "1",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "533b6ebc543dd103e62bc98359afd0d7",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1066"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}PATCH /api/v2/purchase_orders/29
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_order",
"attributes": {
"currency": "EUR",
"issued_on": "2025-11-15"
},
"relationships": {
"deal": {
"data": {
"type": "quotes",
"id": "0"
}
}
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "attribute is invalid",
"source": {
"pointer": "data/attributes/deal"
}
}
]
}PATCH /api/v2/purchase_orders/30
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_order",
"attributes": {},
"relationships": {
"deal": {
"vendor": {
"type": "clients",
"id": "0"
}
}
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/deal"
}
}
]
}Update a purchase orderPATCH/api/v2/purchase_orders/{id}
- id
number(required) Example: 1purchase order id
DELETE /api/v2/purchase_orders/31
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonDeletes a purchase orderDELETE/api/v2/purchase_orders/{id}
- id
number(required) Example: 1purchase order id
POST /api/v2/purchase_orders/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_order",
"attributes": {
"template_id": 32,
"deal_id": 712
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "33",
"type": "purchase_orders",
"attributes": {
"subject": "template",
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": null,
"received_on": null,
"created_at": "2025-11-15T05:07:07.152+01:00",
"number": "2",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "ca7303f3187ebff829ed95d226b4ff3c",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1070"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}POST /api/v2/purchase_orders/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_order",
"attributes": {
"template_id": 34,
"deal_id": 714
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "35",
"type": "purchase_orders",
"attributes": {
"subject": "template",
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": null,
"received_on": null,
"created_at": "2025-11-15T05:07:07.320+01:00",
"number": "2",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "0b77de22a6835df3f6293659b7db3b93",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1071"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}POST /api/v2/purchase_orders/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_order",
"attributes": {
"template_id": 36,
"deal_id": 716
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "37",
"type": "purchase_orders",
"attributes": {
"subject": null,
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": null,
"received_on": null,
"created_at": "2025-11-15T05:07:07.600+01:00",
"number": "2",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "f78b35001accbaa8de13df47634b243d",
"payment_status_id": 1,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 10000,
"total_cost_default": 12500,
"total_cost_normalized": 10000,
"total_cost_with_tax": 10000,
"total_cost_with_tax_default": 12500,
"total_cost_with_tax_normalized": 10000,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1072"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}Copies a purchase orderPOST/api/v2/purchase_orders/copy
- id
number(required) Example: 1purchase order id
PATCH /api/v2/purchase_orders/38/send
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_orders",
"attributes": {
"to": [
"test@email.com"
],
"cc": [
"test@productive.io",
"test-2@productive.io"
],
"bcc": [
"mail@something.com"
],
"subject": "Mail title",
"body": "Lorem ipsum dolor si amet"
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "38",
"type": "purchase_orders",
"attributes": {
"subject": null,
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": "2025-11-15",
"received_on": null,
"created_at": "2025-11-15T05:07:07.731+01:00",
"number": "1",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "4a1be556489c61a350873e4613fdd217",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1073"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}PATCH /api/v2/purchase_orders/42/send
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_orders",
"attributes": {
"to": [
"invalid mail"
]
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "invalid mail is not an email",
"source": {
"pointer": "data/attributes/to"
}
},
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/subject"
}
},
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/body"
}
}
]
}PATCH /api/v2/purchase_orders/43/send
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "purchase_orders",
"attributes": {
"to": [
"test@email.com"
],
"cc": [
"test@productive.io",
"test-2@productive.io"
],
"bcc": [
"mail@something.com"
],
"subject": "Mail title",
"body": "Lorem ipsum dolor si amet"
}
}
}Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "43",
"type": "purchase_orders",
"attributes": {
"subject": null,
"status_id": null,
"issued_on": "2025-11-15",
"delivery_on": null,
"sent_on": "2025-11-15",
"received_on": null,
"created_at": "2025-11-15T05:07:08.834+01:00",
"number": "1",
"note": null,
"footer": null,
"note_interpolated": null,
"footer_interpolated": null,
"email_key": "3f96e115318bb2131ee8c92da04a4e03",
"payment_status_id": 3,
"exchange_rate": "1.25",
"exchange_date": "2025-11-15",
"exported": false,
"exported_at": null,
"export_integration_type_id": null,
"export_id": null,
"export_url": null,
"currency": "EUR",
"currency_default": "USD",
"currency_normalized": "EUR",
"total_cost": 0,
"total_cost_default": 0,
"total_cost_normalized": 0,
"total_cost_with_tax": 0,
"total_cost_with_tax_default": 0,
"total_cost_with_tax_normalized": 0,
"total_received": 0,
"total_received_default": 0,
"total_received_normalized": 0
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1078"
}
},
"vendor": {
"meta": {
"included": false
}
},
"deal": {
"meta": {
"included": false
}
},
"creator": {
"meta": {
"included": false
}
},
"document_type": {
"meta": {
"included": false
}
},
"attachment": {
"meta": {
"included": false
}
},
"bill_to": {
"meta": {
"included": false
}
},
"bill_from": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}Sends a purchase orderPATCH/api/v2/purchase_orders/{id}/send
- id
number(required) Example: 1purchase order id
Generated by aglio on 15 Nov 2025