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

Elements for PurchaseOrders

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 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
The following are only returned on a GET request
<CurrencyRate> The currency rate for a multicurrency purchase order. As no rate can be specified, the XE.com day rate is used.
<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

The <LineItems> collection can contain any number of individual <LineItem> sub-elements. At least one LineItem is required to create a complete PurchaseOrder.
<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.
The following are only returned on GET requests (read-only)
<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)

POST PurchaseOrders

Use this method to create or update purchase orders.

Examples for POST PurchaseOrders

Example of a simple draft purchase order.
<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 of creating an authorised purchase order with a 20% discount on a line item

<PurchaseOrder>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </Contact>
  <Date>2015-11-30</Date>
  <DueDate>2015-12-20</DueDate>
  <LineAmountTypes>Exclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Orange cushions</Description>
      <Quantity>10</Quantity>
      <UnitAmount>100.00</UnitAmount>
      <DiscountRate>20</DiscountRate>
    </LineItem>
  </LineItems>
</PurchaseOrder>

Example of a purchase order that is inclusive of tax, uses foreign currency (USD) and assigns a tracking category to a line item.

<PurchaseOrder>
  <CurrencyCode>USD</CurrencyCode>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </Contact>
  <Date>2015-11-30</Date>
  <DeliveryDate>2015-12-20</DeliveryDate>
  <LineAmountTypes>Inclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Laptop Stand</Description>
      <Quantity>5.0000</Quantity>
      <UnitAmount>99</UnitAmount>
      <Tracking>
          <TrackingCategory>
            <Name>Region</Name>
            <Option>North</Option>
          </TrackingCategory>
      </Tracking>
    </LineItem>
  </LineItems>
</PurchaseOrder>

Example of a purchase order using an item code (2015-TABLE-WHITE). NB The UnitAmount and AccountCode are not specified so the default UnitAmount and AccountCode of the Item will be used. If the UnitAmount and AccountCode were specified then those values would override the defaults.

<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>White Table</Description>
      <Quantity>5</Quantity>
      <ItemCode>2015-TABLE-WHITE</ItemCode>
    </LineItem>
  </LineItems>
</PurchaseOrder>

Example of a purchase order with every element being specified:

<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 of updating a draft purchase order to a status of deleted.

<PurchaseOrder>
  <PurchaseOrderNumber>PO-239</PurchaseOrderNumber>
  <Status>DELETED</Status>
</PurchaseOrder>

Example of updating a purchase order to mark it as sent

<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. To utilise this functionality you'll need to append ?summarizeErrors=false to the end of your API calls e.g. POST /api.xro/2.0/PurchaseOrders?summarizeErrors=false

Below is an example of the response format. 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.

<Response>
  <PurchaseOrders>
    <PurchaseOrder status="OK">
      ...
    </PurchaseOrder>
    <PurchaseOrder status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </PurchaseOrder>
    <PurchaseOrder status="OK">
      ...
    </PurchaseOrder>
</PurchaseOrders>
</Response>

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.

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
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 for GET 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>