Purchase Orders


Overview

URL https://api.xero.com/api.xro/2.0/PurchaseOrders
Methods Supported GET, PUT, POST
Description Allows you to retrieve purchase orders
Allows you to add or update purchase orders
Allows you to delete purchase orders

GET PurchaseOrders

Use this method to retrieve one or many purchase orders.
  • By default responses are formatted as XML. You can also retrieve responses in JSON format.
  • When you retrieve multiple purchase orders, paging is enforced by default. 100 purchase orders are returned per page.
  • Individual purchase orders (e.g. PurchaseOrders/97c2dc5-cc47-4afd-8ec8-74990b8761e9) can also be returned as PDF's see our HTTP GET documentation
Contact See Contacts.
Date Date purchase order was issued - YYYY-MM-DD
DeliveryDate Date the goods are to be delivered - YYYY-MM-DD
LineAmountTypes See Line Amount Types
PurchaseOrderNumber Unique alpha numeric code identifying purchase order
Reference Additional reference number
LineItems See LineItems. The LineItems collection can contain any number of individual LineItem sub-elements.
BrandingThemeID See BrandingThemes
CurrencyCode The currency that purchase order has been raised in (see Currencies)
Status See Purchase Order Status Codes
SentToContact Boolean to set whether the purchase order should be marked as "sent"
DeliveryAddress The address the goods are to be delivered to
AttentionTo The person that the delivery is going to
Telephone The phone number for the person accepting the delivery
DeliveryInstructions A free text feild for instructions
ExpectedArrivalDate The date the goods are expected to arrive.
PurchaseOrderID Xero generated unique identifier for purchase order
CurrencyRate The currency rate for a multicurrency purchase order
SubTotal Total of purchase order excluding taxes
TotalTax Total tax on purchase order
Total Total of Purchase Order tax inclusive (i.e. SubTotal + TotalTax)
TotalDiscount Total of discounts applied on the purchase order line items
HasAttachments boolean to indicate if a purchase order has an attachment
UpdatedDateUTC Last modified date UTC format
Elements for Line Items
Description The description of the line item. A line item can be created with only a description (i.e no unit amount or quantity)
Quantity LineItem Quantity. If Quantity is specified then a UnitAmount must be specified
UnitAmount Lineitem unit amount. Will be rounded to four decimal places
ItemCode See Items
AccountCode See Accounts
TaxType Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes.
DiscountRate Percentage discount being applied to a line item
Tracking Optional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements.
LineItemID The Xero generated identifier for a LineItem. If LineItemIDs are not included with line items in an update request then the line items are deleted and recreated.
TaxAmount The tax amount is auto calculated as a percentage of the line amount based on the tax rate.
LineAmount The line amount reflects the discounted price if a DiscountRate has been used . i.e LineAmount = Quantity * Unit Amount * ((100 - DiscountRate)/100)

Optional parameters

Record filter You can specify an individual record by appending the value to the endpoint, i.e. GET https://.../PurchaseOrders/{identifier}
PurchaseOrderID - The Xero identifier for a PurchaseOrder e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
PurchaseOrderNumber - The PurchaseOrderNumber e.g. PO-01514
Modified After The ModifiedAfter filter is actually an HTTP header: 'If-Modified-Since'. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only purchase orders created or modified since this timestamp will be returned e.g. 2015-11-12T00:00:00
Status Filter by purchase order status (e.g. GET https://.../PurchaseOrders?status=DRAFT)
DateFrom and DateTo Filter by purchase order date (e.g. GET https://.../PurchaseOrders?DateFrom=2015-12-01&DateTo=2015-12-31)
order Order by any element returned (see Order By)
page To specify a page, append the page parameter to the URL e.g. ?page=1. If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned.

Example response retrieving PurchaseOrders

GET https://api.xero.com/api.xro/2.0/PurchaseOrders
<PurchaseOrders>
  <PurchaseOrder>
    <Contact>
      <ContactID>9b9ba9e5-e907-4b4e-8210-54d82b0aa479</ContactID>
      <Name>CoolStuffDirect</Name>
    </Contact>
    <Date>2015-12-24T00:00:00</Date>
    <DeliveryDate>2015-12-25T00:00:00</DueDate>
    <Status>BILLED</Status>
    <LineAmountTypes>Inclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Cool things</Description>
        <UnitAmount>77.3949</UnitAmount>
        <TaxType>INPUT2</TaxType>
        <TaxAmount>11.61</TaxAmount>
        <LineAmount>77.39</LineAmount>
        <AccountCode>445</AccountCode>
        <Quantity>1.0000</Quantity>
        <LineItemID>9361c7b9-7f85-44f6-9ce0-1225d63a36bd</LineItemID>
      </LineItem>
    </LineItems>
    <SubTotal>77.39</SubTotal>
    <TotalTax>11.61</TotalTax>
    <Total>89.00</Total>
    <UpdatedDateUTC>2015-11-12T12:55:16.347</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <PurchaseOrderID>22b3fab4-ef56-4d70-a110-a7cc3c1a26cd</PurchaseOrderID>
    <PurchaseOrderNumber>PO-123</PurchaseOrderNumber>
    <CurrencyRate>1.000000</CurrencyRate>
    <DeliveryAddress>23 Main Street, Central City, Marineville,1234</DeliveryAddress>
    <AttentionTo>Bob</AttentionTo>
    <Telephone>0800 1234 5678</Telephone>
    <DeliveryInstructions>Don't forget the secret knock</DeliveryInstructions>
    <ExpectedArrivalDate>2015-12-12</ExpectedArrivalDate>
    <HasAttachments>false</HasAttachments>
  </PurchaseOrder>
  <PurchaseOrder>
    <Contact>
      <ContactID>9b9ba9e5-e907-4b4e-8210-54d82b0aa479</ContactID>
      <Name>CoolStuffDirect</Name>
    </Contact>
    <Date>2015-12-24T00:00:00</Date>
    <DeliveryDate>2015-12-25T00:00:00</DueDate>
    <Status>DRAFT</Status>
    <LineAmountTypes>Inclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>More cool stuff</Description>
        <UnitAmount>78.2600</UnitAmount>
        <TaxType>INPUT2</TaxType>
        <TaxAmount>11.74</TaxAmount>
        <LineAmount>78.26</LineAmount>
        <AccountCode>445</AccountCode>
        <Quantity>1.0000</Quantity>
        <LineItemID>ba9d40de-2da8-4288-80ed-a7ececa5a343</LineItemID>
      </LineItem>
    </LineItems>
    <SubTotal>78.26</SubTotal>
    <TotalTax>11.74</TotalTax>
    <Total>90.00</Total>
    <UpdatedDateUTC>2015-11-12T14:28:14.303</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <PurchaseOrderID>96988e67-ecf9-466d-bfbf-0afa1725a649</PurchaseOrderID>
    <PurchaseOrderNumber>RPT445-1</PurchaseOrderNumber>
    <CurrencyRate>1.000000</CurrencyRate>
    <DeliveryAddress>23 Main Street, Central City, Marineville,1234</DeliveryAddress>
    <AttentionTo>Bob</AttentionTo>
    <Telephone>0800 1234 5678</Telephone>
    <DeliveryInstructions>Don't forget the secret knock</DeliveryInstructions>
    <ExpectedArrivalDate>2015-12-12</ExpectedArrivalDate>
    <HasAttachments>false</HasAttachments>
  </PurchaseOrder>
...
</PurchaseOrders>

POST PurchaseOrders

Use this method to create or update purchase orders.

The following are required to create a purchase order
Contact The PurchaseOrders endpoint does not create new contacts. You need to provide the ContactID or ContactNumber of an existing contact. For more information on creating contacts see Contacts.
LineItems See LineItems. The LineItems collection can contain any number of individual LineItem sub-elements. At least one LineItem is required to create a complete PurchaseOrder.
The following are optional for a PUT / POST request
Date Date purchase order was issued - YYYY-MM-DD. If the Date element is not specified then it will default to the current date based on the timezone setting of the organisation
DeliveryDate Date the goods are to be delivered - YYYY-MM-DD
LineAmountTypes Line amounts are exclusive of tax by default if you don't specify this element. See Line Amount Types
PurchaseOrderNumber Unique alpha numeric code identifying purchase order (when missing will auto-generate from your Organisation Invoice Settings)
Reference Additional reference number
BrandingThemeID See BrandingThemes
CurrencyCode The currency that purchase order has been raised in (see Currencies)
Status See Purchase Order Status Codes
SentToContact Boolean to set whether the purchase order should be marked as "sent". This can be set only on purchase orders that have been approved or billed
DeliveryAddress The address the goods are to be delivered to
AttentionTo The person that the delivery is going to
Telephone The phone number for the person accepting the delivery
DeliveryInstructions A free text feild for instructions (500 characters max)
ExpectedArrivalDate The date the goods are expected to arrive.
PurchaseOrderID Xero generated unique identifier for purchase order
Elements for Line Items
Description The description of the line item. A line item can be created with only a description (i.e no unit amount or quantity)
Quantity LineItem Quantity. If Quantity is specified then a UnitAmount must be specified
UnitAmount Lineitem unit amount. Will be rounded to four decimal places
ItemCode See Items
AccountCode See Accounts
TaxType Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes.
DiscountRate Percentage discount being applied to a line item
Tracking Optional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements.
LineItemID The Xero generated identifier for a LineItem. If LineItemIDs are not included with line items in an update request then the line items are deleted and recreated.

Creating, updating and deleting line items when updating purchase orders

In an update (POST) request:

  • Providing an existing LineItem with its LineItemID will update that line item.
  • Providing a LineItem with no LineItemID will create a new line item.
  • Not providing an existing LineItem with it's LineItemID will result in that line item being deleted.

PUT PurchaseOrders

The PUT method is similar to the POST PurchaseOrders method, however you can only create new purchase orders with this method.

Example request to create a simple draft purchase order

POST https://api.xero.com/api.xro/2.0/PurchaseOrders
<PurchaseOrder>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </Contact>
  <Date>2015-11-30</Date>
  <DeliveryDate>2015-12-20</DeliveryDate>
  <LineAmountTypes>Exclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Office Chairs</Description>
      <Quantity>5.0000</Quantity>
      <UnitAmount>120.00</UnitAmount>
    </LineItem>
  </LineItems>
</PurchaseOrder>

Example request to create a purchase order with all elements specified

POST https://api.xero.com/api.xro/2.0/PurchaseOrders
<PurchaseOrder>
  <PurchaseOrderNumber>PO-0292</PurchaseOrderNumber>
  <Date>2015-11-12</Date>
  <DeliveryDate>2015-12-12</DeliveryDate>
  <Reference>REF123</Reference>
  <Contact>
    <ContactID>d7b78c9c-b34a-4dad-b999-c3c2504c7877</ContactID>
  </Contact>
  <BrandingThemeID>4c82c365-35cb-467f-bb11-dce1f2f2f67c</BrandingThemeID>
  <Status>AUTHORISED</Status>
  <LineAmountTypes>Exclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <ItemCode>GB1-White</ItemCode>
      <Description>Golf balls - white single. Wholesale catalog item #020812-1</Description>
      <UnitAmount>4.2595</UnitAmount>
      <TaxType>INPUT2</TaxType>
      <AccountCode>300</AccountCode>
      <Tracking>
        <TrackingCategory>
          <Name>Region</Name>
          <Option>Eastside</Option>
        </TrackingCategory>
        <TrackingCategory>
          <Name>Salesperson</Name>
          <Option>Adam</Option>
        </TrackingCategory>
      </Tracking>
      <Quantity>1.0000</Quantity>
      <DiscountRate>10.00</DiscountRate>
    </LineItem>
  </LineItems>
  <CurrencyRate>0.615310</CurrencyRate>
  <CurrencyCode>EUR</CurrencyCode>
  <DeliveryAddress>23 Main Street, Central City, Marineville,1234</DeliveryAddress>
  <AttentionTo>Bob</AttentionTo>
  <Telephone>0800 1234 5678</Telephone>
  <DeliveryInstructions>Don't forget the secret knock</DeliveryInstructions>
  <ExpectedArrivalDate>2015-12-12</ExpectedArrivalDate>
</PurchaseOrder>

Example request to update a draft purchase order to a status of deleted.

POST https://api.xero.com/api.xro/2.0/PurchaseOrders/22b3fab4-ef56-4d70-a110-a7cc3c1a26cd
<PurchaseOrder>
  <PurchaseOrderNumber>PO-239</PurchaseOrderNumber>
  <Status>DELETED</Status>
</PurchaseOrder>

Example request to update a purchase order to mark it as sent

POST https://api.xero.com/api.xro/2.0/PurchaseOrders/8694c9c5-7097-4449-a708-b8c1982921a4
<PurchaseOrder>
<PurchaseOrderID>8694c9c5-7097-4449-a708-b8c1982921a4</PurchaseOrderID>
<SentToContact>true</SentToContact>
</PurchaseOrder>

Summarize Errors

If you are entering many purchase orders in a single API call then we recommend you utilise the summarizeErrors parameter which provides a response format that shows validation errors for each purchase order. Note that each Purchase Order is returned with a status element which will either contain the value OK or ERROR. If a purchase order has an error then one or more validation errors will be returned.

Example of the altered response format using the SummarizeErrors=false parameter

POST https://api.xero.com/api.xro/2.0/PurchaseOrders?SummarizeErrors=false 
<Response>
  <PurchaseOrders>
    <PurchaseOrder status="OK">
      ...
    </PurchaseOrder>
    <PurchaseOrder status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </PurchaseOrder>
    <PurchaseOrder status="OK">
      ...
    </PurchaseOrder>
</PurchaseOrders>
</Response>