PurchaseOrders

Used to query, insert, and update purchase orders in Xero. Purchase orders are used to track items or services that the organization intends to buy from suppliers.

Table Specific Information

The PurchaseOrders table allows you to SELECT, INSERT, and UPDATE PurchaseOrder lines for a Xero organization. The Id column is generated by the cmdlet; it combines the index of the line item with the unique, Xero-generated PurchaseOrderId.

SELECT

The Xero API allows extensive filtering and ordering. You can define WHERE and ORDER BY clauses in a query to filter and order the results using any non-line-item column.

Note: The Xero API does not support filtering on line items or journal lines.

INSERT

To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new Purchase Order, the ContactId and Date fields are required in addition to at least one line item. A PurchaseOrder line item must at minimum contain a description (LineItem_Description).

You can insert a new Purchase Order with multiple line items using an XML aggregate. The elements supported here are the same as the LineItem columns without the "LineItem_" prefix. Please refer to the Xero documentation of the Purchase Order API for more details.
```
INSERT INTO PurchaseOrders (Contact_ContactId, LineItemAggregate) VALUES (
  '883628bc-7f22-4234-8a4c-81571816a8a1',
  '<LineItem>
		<Description>Example Description</Description>
   </LineItem>
   <LineItem>
		...
   </LineItem>'
)
```
You can also create multiple Purchase Orders in a single query by using a bulk insert. To do this, you should not include a PurchaseOrderId in your query, then specify the values for the first line item of each PurchaseOrder to add.
```
INSERT INTO PurchaseOrders (Contact_ContactId, LineItem_Description)
  VALUES
('37ec4d02-dc3f-4a4c-a943-e8ae8c7db93a', 'Example1'),
('abcd1234-1234-1b2c-a123-abcde12345ab', 'Example2')
```
You can also insert new line items on an existing object by specifying the Xero-generated value of the existing record. For example, to add 2 new line items to an existing Purchase Order:
```
INSERT INTO PurchaseOrders (PurchaseOrderId, LineItem_Description)
  VALUES
('fbb38812-dcc4-4e07-9ebd-2c38e1409b18', 'Example1'),
('fbb38812-dcc4-4e07-9ebd-2c38e1409b18', 'Example2')
```

Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.

UPDATE

You can update any field that is not read-only.

Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.

Columns


Name	Type	ReadOnly	Description
Id [KEY]	String	True	The unique combination of the position of the history item and its associated purchase order ID.
PurchaseOrderId	String	False	The unique Xero identifier for the purchase order, linking the item to the corresponding purchase order.
PurchaseOrderNumber	String	False	A unique identifier that represents the purchase order, making it easy to track and refer to the order.
Reference	String	False	An optional field to store a reference number for the purchase order for further identification or tracking.
Type	String	False	The purchase order type. Valid values are 'ACCPAYCREDIT' for credit notes related to accounts payable, and 'ACCRECCREDIT' for credit notes related to accounts receivable.
Contact_ContactId	String	False	The unique identifier of the contact associated with the purchase order, linking it to a specific supplier or customer.
Contact_Name	String	False	The name of the contact associated with the purchase order, typically the name of the supplier or customer.
DeliveryDate	Date	False	The date when the goods or services are scheduled to be delivered as per the purchase order.
ExpectedArrivalDate	Date	False	The expected date of arrival for the goods or services specified in the purchase order.
DeliveryAddress	String	False	The address where the goods or services from the purchase order are to be delivered.
AttentionTo	String	False	The person to whom the delivery is directed or who is responsible for receiving it.
Telephone	String	False	The phone number of the person receiving the delivery, allowing for easy contact in case of issues.
DeliveryInstructions	String	False	A free-form field to include any specific instructions or details required to complete the delivery.
Date	Date	False	The date when the purchase order was created, marking its initiation in the system.
Status	String	False	The current status of the purchase order. Common statuses include 'DRAFT', 'SUBMITTED', 'AUTHORISATION_PENDING', and 'CLOSED'.
LineAmountTypes	String	False	Specifies whether the line amounts in the purchase order include tax (default). Valid values are 'Exclusive', 'Inclusive', and 'NoTax'.
LineItem_LineItemId	String	False	The unique Xero-generated identifier for a line item in the purchase order. If 'LineItemIds' are not provided during an update request, the existing line items are deleted and recreated.
LineItem_Description	String	False	The description for each line item, explaining the product or service being purchased. This field must contain at least one character and is required for invoice approval.
LineItem_Quantity	Double	False	The quantity of the item being ordered in the line item. This value must be a positive number or zero for the order to be approved.
LineItem_UnitAmount	Decimal	False	The unit price of the item, which is the cost per single unit of the product or service ordered.
LineItem_ItemCode	String	False	The code that uniquely identifies the item being purchased, as defined by the supplier or organization.
LineItem_AccountCode	String	False	The account code associated with the item. This account code must be active within the organization for the purchase order to be approved.
LineItem_TaxType	String	False	The tax type that applies to the line item, overriding the default tax code for the account, if necessary.
LineItem_TaxAmount	Decimal	False	The total tax applied to the line item, calculated based on the 'TaxType' and 'UnitAmount'.
LineItem_LineAmount	Decimal	False	The total amount of the line item, calculated as the quantity multiplied by the unit amount, with discounts applied if any.
LineItem_DiscountRate	Double	False	The discount percentage applied to the line item. Discounts are only supported for 'ACCREC'-type (sales) purchase orders.
LineItemAggregate	String	False	This field is used to define multiple line item rows using XML values. It should only be included when performing an INSERT operation.
SubTotal	Decimal	False	The subtotal of the purchase order, which excludes any applicable taxes.
TotalTax	Decimal	False	The total tax amount applied to the entire purchase order.
Total	Decimal	False	The total amount of the purchase order, including both the subtotal and the applicable tax.
LineItem_TrackingCategory1_CategoryId	String	False	The ID of the first tracking category, if used. The API allows up to two optional tracking categories to be defined for each line item.
LineItem_TrackingCategory1_CategoryName	String	False	The name of the first tracking category, if used.
LineItem_TrackingCategory1_OptionId	String	False	The ID of the first tracking category option, if used. Tracking categories allow you to track multiple attributes in your accounts.
LineItem_TrackingCategory1_OptionName	String	False	The name of the first tracking category option, if used.
LineItem_TrackingCategory1_Option_Stat	String	False	The status of the first tracking category option, if used.
LineItem_TrackingCategory2_CategoryId	String	False	The ID of the second tracking category, if used.
LineItem_TrackingCategory2_CategoryName	String	False	The name of the second tracking category, if used.
LineItem_TrackingCategory2_OptionId	String	False	The ID of the second tracking category option, if used.
LineItem_TrackingCategory2_OptionName	String	False	The name of the second tracking category option, if used.
LineItem_TrackingCategory2_Option_Stat	String	False	The status of the second tracking category option, if used.
UpdatedDateUTC	Datetime	True	The timestamp for when the purchase order was last updated in the system.
HasAttachments	Boolean	True	Indicates whether the purchase order has any attached files or documents.
CurrencyCode	String	False	The currency used for the purchase order. This value corresponds to the ISO 4217 currency code.
BrandingThemeId	String	False	The ID of the branding theme used for the purchase order.
CurrencyRate	Decimal	False	The exchange rate applied when the purchase order is processed in a non-base currency. If this is not provided, either the user-defined rate or the XE.com day rate will be applied.
TenantId	String	False	The ID of the tenant to query, used for multi-tenant environments to ensure the correct data is returned.

Copyright (c) 2025 CData Software, Inc. - All rights reserved.

Build 25.0.9434