Explore PurchaseOrders endpoints in Swagger.

Overview

Purchase orders represent a business's intent to purchase goods or services from a supplier and normally include information such as expected delivery dates and shipping details.

This information can be used to provide visibility on a business's expected payables and to track a purchase through the full procurement process. You may also choose to use the billRef field to identify bills raised from a purchase order so you can perform a 3-way match.

Supported integrations

You can currently view a business's purchase orders using our QuickBooks Online and Xero integrations.

We're working on adding support to our other integrations. You can see updates on this and register your interest for specific integrations on our public roadmap.

Data model

Field	Type	Description
id	string	Identifier for the purchase order, unique for the company in the accounting platform.
purchaseOrderNumber	string	Friendly reference for the purchase order, commonly generated by the accounting platform.
issueDate	date	Date of the purchase order as recorded in the accounting platform.
deliveryDate	date	Actual delivery date for any goods that have been ordered.
expectedDeliveryDate	date	Expected delivery date for any goods that have been ordered.
paymentDueDate	date	Date the supplier is due to be paid.
note	string	Any additional information associated with the purchase order.
billRef	billRef	Reference to the bill issued by the supplier for this purchase order.
supplierRef	supplierRef	Supplier that the purchase order is recorded against in the accounting system.
shipTo	ShipTo	Delivery details for any goods that have been ordered.
status	string	Current state of the purchase order, either: `Draft` `Open` `Closed` `Void` `Unknown`
currency	string	Currency of the purchase order. See currency
currencyRate	decimal	Rate for converting the total amount of the purchase order into the base currency for the company. See currency rate
lineItems	Array of PurchaseOrderLineItems
totalDiscount	decimal	Total value of any discounts applied to the purchase order.
subTotal	decimal	Total amount of the purchase order, including discounts but excluding tax.
totalTaxAmount	decimal	Total amount of tax included in the purchase order.
totalAmount	decimal	Total amount of the purchase order, including discounts and tax.
modifiedDate	date	Date the purchase order was last updated in the Codat system.
sourceModifiedDate	date	Date the purchase order was last changed in the accounting system.

Lines

Field	Type	Description
description	string	Description of the goods / services that have been ordered.
accountRef	accountRef	Reference to the account to which the line item is linked.
itemRef	itemRef	Reference to the product or inventory item to which the line item is linked.
trackingCategoryRefs	Array of trackingCategoryRefs	Reference to the tracking categories to which the line item is linked.
unitAmount	decimal	Price of each unit.
quantity	decimal	Number of units that have been ordered.
discountAmount	decimal	Value of any discounts applied.
discountPercentage	decimal	Percentage rate (from 0 to 100) of any discounts applied to the unit amount.
subTotal	decimal	Amount of the line, inclusive of discounts but exclusive of tax.
taxAmount	decimal	Amount of tax for the line.
taxRateRef	TaxRateRef	Reference to the tax rate to which the line item is linked.
totalAmount	decimal	Total amount of the line, inclusive of discounts and tax.

ShipTo

Field	Type	Description
contact	PurchaseOrderContact	Details of the named contact at the delivery address.
address	Address	Delivery address for any goods that have been ordered.

PurchaseOrderContact

Field	Type	Description
name	string	Name of the contact at the delivery address.
email	string	Email address of the contact at the delivery address.
phone	string	Phone number of the contact at the delivery address.

Example purchase order

This is a sample purchase order from our Sandbox integration. To view more examples, enable purchase orders in your sync settings and synchronise data for a company.

{
    "id": "7e2380af-b51f-4393-92d7-6ff0382da26c",
    "purchaseOrderNumber": "89443280",
    "issueDate": "2020-10-24T00:00:00Z",
    "deliveryDate": "2021-02-02T00:00:00Z",
    "expectedDeliveryDate": "2021-01-29T00:00:00Z",
    "paymentDueDate": "2021-09-13T00:00:00Z",
    "note": "purchaseorder with 1 line items, totalling 1138.5",
    "billRef": {
        "id": "0fa70e12-6ffe-4644-a40c-01e9762499b2",
        "reference": "85561359"
    },
    "supplierRef": {
        "id": "7ff6add1-b0e7-496f-b655-48e20c8fdb2e",
        "supplierName": "Carlton Innovations"
    },
    "shipTo": {
        "contacts": {
            "name": "Carlton Innovations",
            "email": "[email protected]",
            "phone": ""
        },
        "address": {
            "type": "Billing",
            "line1": "1 Carolyns Circle",
            "line2": "",
            "city": "Dallas",
            "region": "Texas",
            "country": "USA",
            "postalCode": "511210"
        }
    },
    "status": "Closed",
    "currency": "GBP",
    "currencyRate": 1,
    "lineItems": [
        {
            "description": "Electric Eye purchase",
            "accountRef": {
                "id": "13931cbf-ea06-4d6e-9538-a8457fa66011",
                "name": "Cost of Goods Sold"
            },
            "itemRef": {
                "id": "9409d23d-1011-432e-98a4-591fcd8d5404",
                "name": "ACME Electric Eye"
            },
            "trackingCategoryRefs": [],
            "unitAmount": 115,
            "quantity": 9,
            "discountAmount": 0,
            "discountPercentage": 0,
            "subTotal": 1035,
            "taxAmount": 103.5,
            "taxRateRef": {
                "id": "6c88aff3-7cb9-4980-a3d3-443e72e02498",
                "name": "ACME Sales Tax (10%)"
            },
            "totalAmount": 1138.5
        }
    ],
    "totalDiscount": 0,
    "subTotal": 1035,
    "totalTaxAmount": 103.5,
    "totalAmount": 1138.5,
    "modifiedDate": "2020-11-17T21:11:20Z",
    "sourceModifiedDate": "2020-10-25T06:37:33Z"
}