Quotes

Overview

URL https://api.xero.com/api.xro/2.0/Quotes
Methods Supported GET, PUT, POST
Description Retrieve quotes
Create quotes

GET Quotes

Use this method to retrieve one or many quotes.

  • By default responses are formatted as XML. You can also retrieve responses in JSON format.
  • Individual invoices (e.g. Quotes/97c2dc5-cc47-4afd-8ec8-74990b8761e9) can also be returned as PDF's see our HTTP GET documentation

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

Optional parameters

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
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 status (e.g. GET https://.../Quotes?DateFrom=2019-12-01&DateTo=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.

POST Quotes

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.
NOTE: Some fields cannot be updated when a quote is in a specific state. See editable fields for more information

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
 

Quote status changes

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
 

Status based editible fields

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

Retrieving History

View a summary of the actions made by all users to the quote. See the History and Notes page for more details.

Add Notes to a Quote

Add a note which will appear in the history against an quote. See the History and Notes page for more details.

PUT Quotes

The PUT method is similar to the POST Quotes method, however you can only create new quotes with this method.