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

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
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
Status The status of a tracking option

PUT TrackingCategories

Use this method to create tracking categories and options

1. Create Tracking Categories

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

PUT /TrackingCategories/

<TrackingCategories> 
    <TrackingCategory>
      <Name>New Category</Name>
    </TrackingCategory>
</TrackingCategories>

2. Create Tracking Options

PUT 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.

1. Update a Tracking Category Name
POST /TrackingCategories/{TrackingCategoryID}

<TrackingCategories> 
    <TrackingCategory>
      <Name>New Name</Name>
    </TrackingCategory>
</TrackingCategories>

2. Update a Tracking Category Status
POST /TrackingCategories/{TrackingCategoryID}

<TrackingCategories> 
    <TrackingCategory>
      <Status>ARCHIVED</Status>
    </TrackingCategory>
</TrackingCategories>

3. Update a tracking option name
POST TrackingCategories/{TrackingCategoryID}/Options/{TrackingOptionID}

<Options> 
    <Option>
      <Name>New Name</Name>
    </Option>
</Options>

4. Update a tracking option status
POST TrackingCategories/{TrackingCategoryID}/Options/{TrackingOptionID}

<Options> 
    <Option>
      <Status>ARCHIVED</Status>
    </Option>
</Options>

GET TrackingCategories

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

DELETE TrackingCategories

Delete a Tracking Category

DELETE TrackingCategories/{TrackingCategoryID}

Delete a Tracking Option

DELETE TrackingCategories/{TrackingCategoryID}/Options/{TrackingOptionID}