API Documentation

API Endpoint

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:

Purchase Order diagram

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/1
Requestsreturns purchase orders

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+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "22",
    "type": "purchase_orders",
    "attributes": {
      "subject": null,
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-04T02:08:05.583+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "5547aa85ae48391a7395d34bd1245dfb",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": "1054"
        }
      },
      "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 order
GET/api/v2/purchase_orders/{id}

URI Parameters
HideShow
id
number (required) Example: 1

purchase order id

POST /api/v2/purchase_orders
Requestscreates purchase orderreturns error

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+json
Body
{
  "data": {
    "type": "purchase_orders",
    "attributes": {
      "currency": "EUR",
      "issued_on": "2025-10-04"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "702"
        }
      },
      "vendor": {
        "data": {
          "type": "clients",
          "id": "2627"
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "24",
    "type": "purchase_orders",
    "attributes": {
      "subject": null,
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-04T02:08:05.748+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "d5302f7343f438b8510935bd28e77b33",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": "1055"
        }
      },
      "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+json
Body
{
  "data": {
    "type": "purchase_orders",
    "attributes": {
      "currency": "EUR",
      "issued_on": "2025-10-04"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "0"
        }
      },
      "vendor": {
        "data": {
          "type": "clients",
          "id": "2630"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "attribute is invalid",
      "source": {
        "pointer": "data/attributes/deal"
      }
    }
  ]
}

Create a purchase order
POST/api/v2/purchase_orders

PATCH /api/v2/purchase_orders/1
Requestsupdates purchase orderreturns errorreturns error

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+json
Body
{
  "data": {
    "type": "purchase_orders",
    "attributes": {
      "currency": "EUR",
      "issued_on": "2025-10-04"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "707"
        }
      },
      "vendor": {
        "data": {
          "type": "clients",
          "id": "2642"
        }
      },
      "subscribers": {
        "data": [
          {
            "type": "people",
            "id": "3699"
          },
          {
            "type": "people",
            "id": "3700"
          }
        ]
      }
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "28",
    "type": "purchase_orders",
    "attributes": {
      "subject": null,
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-04T02:08:06.235+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "14dffc0df309e8360a0979134b9b164a",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": "1059"
        }
      },
      "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+json
Body
{
  "data": {
    "type": "purchase_order",
    "attributes": {
      "currency": "EUR",
      "issued_on": "2025-10-04"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "0"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "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+json
Body
{
  "data": {
    "type": "purchase_order",
    "attributes": {},
    "relationships": {
      "deal": {
        "vendor": {
          "type": "clients",
          "id": "0"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "can't be blank",
      "source": {
        "pointer": "data/attributes/deal"
      }
    }
  ]
}

Update a purchase order
PATCH/api/v2/purchase_orders/{id}

URI Parameters
HideShow
id
number (required) Example: 1

purchase order id

DELETE /api/v2/purchase_orders/1
Requestsdeletes purchse_order

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+json
Responses204
This response has no content.

Deletes a purchase order
DELETE/api/v2/purchase_orders/{id}

URI Parameters
HideShow
id
number (required) Example: 1

purchase order id

POST /api/v2/purchase_orders/copy
Requestscopy from templatecopy from templatecopies the purchase order and expenses

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+json
Body
{
  "data": {
    "type": "purchase_order",
    "attributes": {
      "template_id": 32,
      "deal_id": 711
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "33",
    "type": "purchase_orders",
    "attributes": {
      "subject": "template",
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-04T02:08:06.896+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "45d7aebbd55ae00ad7394d3294f8d3e6",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": "1063"
        }
      },
      "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+json
Body
{
  "data": {
    "type": "purchase_order",
    "attributes": {
      "template_id": 34,
      "deal_id": 713
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "35",
    "type": "purchase_orders",
    "attributes": {
      "subject": "template",
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-04T02:08:07.099+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "99411522d8f5b9f7ee2c689c3a50fa13",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": "1064"
        }
      },
      "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+json
Body
{
  "data": {
    "type": "purchase_order",
    "attributes": {
      "template_id": 36,
      "deal_id": 715
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "37",
    "type": "purchase_orders",
    "attributes": {
      "subject": null,
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-04T02:08:07.429+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "682e30b69a257ae8c10bc8037b6cdbe0",
      "payment_status_id": 1,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": "1065"
        }
      },
      "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 order
POST/api/v2/purchase_orders/copy

URI Parameters
HideShow
id
number (required) Example: 1

purchase order id

PATCH /api/v2/purchase_orders/1/send
Requestssends purchase_order via mailreturns errorsends purchase_order via mail

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+json
Body
{
  "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"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "38",
    "type": "purchase_orders",
    "attributes": {
      "subject": null,
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": "2025-10-04",
      "received_on": null,
      "created_at": "2025-10-04T02:08:07.580+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "cd3a96d410985c7ff4fe965fa1b002c6",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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/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+json
Body
{
  "data": {
    "type": "purchase_orders",
    "attributes": {
      "to": [
        "invalid mail"
      ]
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "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+json
Body
{
  "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"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "43",
    "type": "purchase_orders",
    "attributes": {
      "subject": null,
      "status_id": null,
      "issued_on": "2025-10-04",
      "delivery_on": null,
      "sent_on": "2025-10-04",
      "received_on": null,
      "created_at": "2025-10-04T02:08:08.747+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "ded26f311c39a27930ee5c6980f0acaa",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-04",
      "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": {}
}

Sends a purchase order
PATCH/api/v2/purchase_orders/{id}/send

URI Parameters
HideShow
id
number (required) Example: 1

purchase order id

Generated by aglio on 04 Oct 2025