Purchase orders

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"
}

Did this page help you?