Use this method to retrieve one or many quotes.
The following elements are returned in the quotes response:
Contact | See Contacts |
Date | Date quote was issued - YYYY-MM-DD |
ExpiryDate | Date quote expires - YYYY-MM-DD |
Status | See Quote Status Codes |
LineAmountTypes | See Line Amount Types |
LineItems | See LineItems. The LineItems collection can contain any number of individual LineItem sub-elements. |
SubTotal | Total of quote excluding taxes |
TotalTax | Total tax on quote |
Total | Total of Quote tax inclusive (i.e. SubTotal + TotalTax) |
TotalDiscount | Total of discounts applied on the quote line items |
UpdatedDateUTC | Last modified date UTC format |
CurrencyCode | The currency that quote has been raised in (see Currencies) |
CurrencyRate | The currency rate for a multicurrency quote |
QuoteID | Xero generated unique identifier for a quote |
QuoteNumber | Unique alpha numeric code identifying a quote |
Reference | Additional reference number |
BrandingThemeID | See BrandingThemes |
Title | The title of the quote |
Summary | The summary of the quote |
Terms | The terms of the quote |
Elements for LineItems | |
Description | The description of the line item |
Quantity | LineItem Quantity |
UnitAmount | Lineitem unit amount. By default, unit amount will be rounded to four decimal places. |
ItemCode | See Items |
AccountCode | See Accounts |
LineItemID | The Xero generated identifier for a LineItem |
TaxType | Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes. |
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) |
DiscountRate | Percentage discount being applied to a line item |
Tracking | Section for optional Tracking Category - see TrackingCategory. Any LineItem can have a maximum of 2 TrackingCategory elements. |
Elements for TrackingCategory | |
TrackingCategoryID | Xero assigned unique ID for the category |
TrackingOptionID | Xero assigned unique ID for the option |
Name | Name of the tracking category |
Option | Name of the option (required) |
Examples response when retrieving a collection of quotes
GET https://api.xero.com/api.xro/2.0/Quotes?page=1
QuoteID | You can specify an individual record by appending the QuoteID to the endpoint, i.e. GET https://.../Quotes/{identifier} |
Modified After | The ModifiedAfter filter is actually an HTTP header: ' If-Modified-Since'. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only quotes created or modified since this timestamp will be returned e.g. 2015-11-12T00:00:00 |
QuoteNumber | Filter by quote number (e.g. GET https://.../Quotes?QuoteNumber=QU-0001) |
Status | Filter by quote status (e.g. GET https://.../Quotes?status=DRAFT) |
DateFrom and DateTo | Filter by quote date (e.g. GET https://.../Quotes?DateFrom=2018-12-01&DateTo=2018-12-31) |
ExpiryDateFrom and ExpiryDateTo | Filter by quote expiry dates (e.g. GET https://.../Quotes?ExpiryDateFrom=2019-12-01&ExpiryDateTo=2019-12-31) |
ContactID | Filter by a Contact (e.g. GET https://.../Quotes?ContactID=f5f1fcb0-2a57-4cb1-836d-3ec207bfa61f) |
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. |
Use this method to create or update one or many quotes.
The following are required to create a draft quote | |
Contact | See Contacts |
Date | Date quote was issued - YYYY-MM-DD |
LineItems | See LineItems. The LineItems collection can contain any number of individual LineItem sub-elements. At minimum, a description is required to create a complete quote. |
The following are required when updating one or many quotes | |
QuoteID | QuoteID GUID is automatically generated and is returned after create or GET. |
The following are optional when creating or updating quotes. |
LineAmountTypes | See Line Amount Types |
Status | See Quote Status Codes |
ExpiryDate | Date quote expires - YYYY-MM-DD |
CurrencyCode | The currency that quote has been raised in (see Currencies) |
QuoteNumber | Unique alpha numeric code identifying a quote (Max Length = 255) |
Reference | Additional reference number |
BrandingThemeID | See BrandingThemes |
Title | The title of the quote (Max Length = 100) |
Summary | The summary of the quote (Max Length = 3000) |
Terms | The terms of the quote (Max Length = 4000) |
Elements for LineItems | |
Description | Description needs to be at least 1 char long. A line item with just a description (i.e no unit amount or quantity) can be created by specifying just a Description element that contains at least 1 character (max length = 4000) |
Quantity | LineItem Quantity |
UnitAmount | Lineitem unit amount. By default, 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 | Section for optional Tracking Category - see TrackingCategory. Any LineItem can have a maximum of 2 TrackingCategory elements. Tracking is limited to TrackingOptionID only for Quotes. |
Elements for TrackingCategory | |
TrackingOptionID | Xero assigned unique ID for the option |
The following state changes are valid when updating quotes.
Existing status | New status |
DRAFT | SENT |
DRAFT | DELETED |
SENT | ACCEPTED |
SENT | INVOICED |
SENT | DECLINED |
SENT | DELETED |
DECLINED | SENT |
DECLINED | DELETED |
ACCEPTED | SENT |
ACCEPTED | DELETED |
INVOICED | SENT |
INVOICED | DELETED |
The following fields changes are valid when updating quotes in a specific status.
Existing status | Editable Fields |
DRAFT | All fields |
SENT | All fields |
DECLINED | Contact details Notes |
ACCEPTED | Contact details Notes |
INVOICED | Contact details Notes |
Example of minimum elements required to create a single draft quote
POST https://api.xero.com/api.xro/2.0/Quotes
Example to create a single draft quote with all possible elements
POST https://api.xero.com/api.xro/2.0/Quotes
Example of minimum elements required to update a single draft quote
POST https://api.xero.com/api.xro/2.0/Quotes
Example of maximum elements required to update a single draft quote
POST https://api.xero.com/api.xro/2.0/Quotes
View a summary of the actions made by all users to the quote. See the History and Notes page for more details.
Add a note which will appear in the history against an quote. See the History and Notes page for more details.