Tracking Categories


Overview

URL https://api.xero.com/api.xro/2.0/TrackingCategories
Methods Supported GET, PUT, POST, DELETE
Description Retrieve tracking categories and options for a Xero organisation
Add new tracking categories and options
Rename tracking categories and options
Update the status of tracking categories and options
Delete unused tracking categories and options

GET TrackingCategories

Elements for Tracking Categories

TrackingCategoryID The Xero identifier for a tracking category
e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
Name The name of the tracking category e.g. Department, Region (max length = 100)
Status The status of a tracking category
Options See Tracking Options

Elements for Tracking Options

TrackingOptionID The Xero identifier for a tracking option
e.g. ae777a87-5ef3-4fa0-a4f0-d10e1f13073a
Name The name of the tracking option e.g. Marketing, East (max length = 100)
Status The status of a tracking option

Optional parameters for GET TrackingCategories

TrackingCategoryID Filter by a tracking category
e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)
includeArchived e.g. includeArchived=true - Categories and options with a status of ARCHIVED will be included in the response

Example response for retrieving TrackingCategories

GET https://api.xero.com/api.xro/2.0/TrackingCategories
<TrackingCategories>
  <TrackingCategory>
    <Name>Region</Name>
    <Status>ACTIVE</Status>
    <TrackingCategoryID>093af706-c2aa-4d97-a4ce-2d205a017eac</TrackingCategoryID>
    <Options>
      <Option>
        <TrackingOptionID>ae777a87-5ef3-4fa0-a4f0-d10e1f13073a</TrackingOptionID>
        <Name>Eastside</Name>
        <Status>ACTIVE</Status>
      </Option>
      <Option>
        <TrackingOptionID>3f05cdf9-246b-46a2-bf6f-441da1b09b89</TrackingOptionID>
        <Name>North</Name>
        <Status>ACTIVE</Status>
      </Option>
      <Option>
        <TrackingOptionID>9f93bb09-3c8c-4d43-a6fe-862772d77bd9</TrackingOptionID>
        <Name>South</Name>
        <Status>ACTIVE</Status>
      </Option>
      <Option>
        <TrackingOptionID>2ba6a2af-11cb-452d-9867-dce88add6856</TrackingOptionID>
        <Name>West Coast</Name>
        <Status>ACTIVE</Status>
      </Option>
    </Options>
  </TrackingCategory>
</TrackingCategories>

PUT TrackingCategories

Use this method to create tracking categories and options

Elements for Tracking Categories

Name The name of the tracking category e.g. Department, Region (max length = 100)
Status The status of a tracking category
Options See Tracking Options

Elements for Tracking Options

TrackingOptionID The Xero identifier for a tracking option
e.g. ae777a87-5ef3-4fa0-a4f0-d10e1f13073a
Name The name of the tracking option e.g. Marketing, East (max length = 50)
Status The status of a tracking option

Note: A Xero organisation can have a maximum of two ACTIVE tracking categories and four tracking categories total (ACTIVE and ARCHIVED)

Example request to create a Tracking Category

PUT https://api.xero.com/api.xro/2.0/TrackingCategories
<TrackingCategories>
  <TrackingCategory>
    <Name>New Category</Name>
  </TrackingCategory>
</TrackingCategories>

Example request to create Tracking Options

PUT https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}/Options
<Options>
  <Option>
    <Name>New Option</Name>
  </Option>
  <Option>
    <Name>Another New Option</Name>
  </Option>
</Options>

POST TrackingCategories

Use this method to update tracking categories and options.

Example request to update a Tracking Category Name

POST https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}
<TrackingCategories>
  <TrackingCategory>
    <Name>New Name</Name>
  </TrackingCategory>
</TrackingCategories>

Example request to update a Tracking Category Status

POST https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}
<TrackingCategories>
  <TrackingCategory>
    <Status>ARCHIVED</Status>
  </TrackingCategory>
</TrackingCategories>

Example request to update a tracking option name

POST https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}/Options/{TrackingOptionID}
<Options>
  <Option>
    <Name>New Name</Name>
  </Option>
</Options>

Example request to update a tracking option status

POST https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}/Options/{TrackingOptionID}
<Options>
  <Option>
    <Status>ARCHIVED</Status>
  </Option>
</Options>

DELETE TrackingCategories

Example request to delete a Tracking Category

DELETE https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}

Example request to delete a Tracking Option

DELETE https://api.xero.com/api.xro/2.0/TrackingCategories/{TrackingCategoryID}/Options/{TrackingOptionID}