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-25",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-25T06:06:53.731+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "59757856ec7f02a622d2bb9c776a4d9e",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": "1056"
        }
      },
      "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-25"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "700"
        }
      },
      "vendor": {
        "data": {
          "type": "clients",
          "id": "2631"
        }
      }
    }
  }
}
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-25",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-25T06:06:53.872+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "8cb36f42ccc30ec363842bd98ab84505",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": "1057"
        }
      },
      "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-25"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "0"
        }
      },
      "vendor": {
        "data": {
          "type": "clients",
          "id": "2634"
        }
      }
    }
  }
}
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-25"
    },
    "relationships": {
      "deal": {
        "data": {
          "type": "quotes",
          "id": "705"
        }
      },
      "vendor": {
        "data": {
          "type": "clients",
          "id": "2646"
        }
      },
      "subscribers": {
        "data": [
          {
            "type": "people",
            "id": "3768"
          },
          {
            "type": "people",
            "id": "3769"
          }
        ]
      }
    }
  }
}
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-25",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-25T06:06:54.331+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "ba0b24422638ada679cc9b3674e5ca95",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": {}
}

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-25"
    },
    "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": 709
    }
  }
}
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-25",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-25T06:06:54.965+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "da4c4832256bf2d486a9c4b1c063915f",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": "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": {}
}

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": 711
    }
  }
}
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-25",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-25T06:06:55.132+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "e85e55014a678ad209d6ece41a0f0f1b",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": {}
}

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": 713
    }
  }
}
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-25",
      "delivery_on": null,
      "sent_on": null,
      "received_on": null,
      "created_at": "2025-10-25T06:06:55.422+02:00",
      "number": "2",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "2ee341cd1fbeddac6c0329bd84671411",
      "payment_status_id": 1,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": "1067"
        }
      },
      "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-25",
      "delivery_on": null,
      "sent_on": "2025-10-25",
      "received_on": null,
      "created_at": "2025-10-25T06:06:55.560+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "ac9c2d9ee4cd6146cdc64be0069795fd",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": "1068"
        }
      },
      "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-25",
      "delivery_on": null,
      "sent_on": "2025-10-25",
      "received_on": null,
      "created_at": "2025-10-25T06:06:56.929+02:00",
      "number": "1",
      "note": null,
      "footer": null,
      "note_interpolated": null,
      "footer_interpolated": null,
      "email_key": "6607af2bcc04f1e6f0f0e0639ece029d",
      "payment_status_id": 3,
      "exchange_rate": "1.25",
      "exchange_date": "2025-10-25",
      "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": {}
}

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 25 Oct 2025