Sales Tax Periods

Only available to US and Universal companies

Minimum access level:

Estimates & Invoices to read
Full Access to create, update, or delete

Attributes

Attributes marked Required should be present in the request to create new sales tax periods.

Required	Attribute	Description	Kind
	url	The unique identifier for the sales tax period	URI
✔	sales_tax_name	Name of sales tax e.g. VAT, GST, Sales Tax	String
✔	sales_tax_registration_status	One of the following: `Not Registered` `Registered`	String
✔	sales_tax_rate_1	First rate of the sales tax	Decimal
	sales_tax_rate_2	Second rate of the sales tax	Decimal
	sales_tax_rate_3	Third rate of the sales tax	Decimal
✔	sales_tax_is_value_added	`true` if you can reclaim tax on what you buy, `false` otherwise	Boolean
	sales_tax_registration_number	Do not specify if no registration number is required	String
✔	effective_date	When the sales tax period takes effect, in `YYYY-MM-DD` format	Date
	is_locked	`true` if no changes can be made, `false` otherwise	Boolean
	locked_reason	The reason for the sales tax period being locked	Boolean

Extra attributes for Universal companies

All attributes displayed below are optional.

Attribute	Description	Kind
second_sales_tax_name	Name of second sales tax (e.g. PST in some Canadian provinces) Do not specify if no second Sales Tax is to be charged	String
second_sales_tax_rate_1	First rate of the second sales tax	Decimal
second_sales_tax_rate_2	Second rate of the second sales tax	Decimal
second_sales_tax_rate_3	Third rate of the second sales tax	Decimal
second_sales_tax_is_compound	`true` if applied on top of the main sales tax instead of independently, `false` otherwise	Boolean

List all sales tax periods for a company

GET https://api.freeagent.com/v2/sales_tax_periods

Response

Status: 200 OK

{
  "sales_tax_periods": [
    {
      "url": "https://api.freeagent.com/v2/sales_tax_periods/1",
      "sales_tax_name": "First Tax",
      "sales_tax_rate_1": "2.0",
      "sales_tax_rate_2": "3.0",
      "sales_tax_rate_3": "4.0",
      "sales_tax_is_value_added": true,
      "sales_tax_registration_status": "Registered",
      "sales_tax_registration_number": "12345678",
      "effective_date": "2016-09-21",
      "is_locked": false,
      "second_sales_tax_name": "Second Tax",
      "second_sales_tax_rate_1": "10.0",
      "second_sales_tax_rate_2": "20.0",
      "second_sales_tax_rate_3": "50.0",
      "second_sales_tax_is_compound": true
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <sales-tax-periods type="array">
    <sales-tax-period>
      <url>https://api.freeagent.com/v2/sales_tax_periods/1</url>
      <sales-tax-name>First Tax</sales-tax-name>
      <sales-tax-rate-1 type="decimal">2.0</sales-tax-rate-1>
      <sales-tax-rate-2 type="decimal">3.0</sales-tax-rate-2>
      <sales-tax-rate-3 type="decimal">4.0</sales-tax-rate-3>
      <sales-tax-is-value-added type="boolean">true</sales-tax-is-value-added>
      <sales-tax-registration-status>Registered</sales-tax-registration-status>
      <sales-tax-registration-number>12345678</sales-tax-registration-number>
      <effective-date type="date">2016-09-21</effective-date>
      <is-locked type="boolean">false</is-locked>
      <second-sales-tax-name>Second Tax</second-sales-tax-name>
      <second-sales-tax-rate-1 type="decimal">10.0</second-sales-tax-rate-1>
      <second-sales-tax-rate-2 type="decimal">20.0</second-sales-tax-rate-2>
      <second-sales-tax-rate-3 type="decimal">50.0</second-sales-tax-rate-3>
      <second-sales-tax-is-compound type="boolean">true</second-sales-tax-is-compound>
    </sales-tax-period>
  </sales-tax-periods>
</freeagent>

Show as JSON

Get a single sales tax period

GET https://api.freeagent.com/v2/sales_tax_periods/:id

Response

Status: 200 OK

{
  "sales_tax_period": {
    "url": "https://api.freeagent.com/v2/sales_tax_periods/2",
    "sales_tax_name": "First Tax",
    "sales_tax_rate_1": "2.0",
    "sales_tax_rate_2": "3.0",
    "sales_tax_rate_3": "4.0",
    "sales_tax_is_value_added": true,
    "sales_tax_registration_status": "Registered",
    "sales_tax_registration_number": "12345678",
    "effective_date": "2016-09-21",
    "is_locked": false,
    "second_sales_tax_name": "Second Tax",
    "second_sales_tax_rate_1": "10.0",
    "second_sales_tax_rate_2": "20.0",
    "second_sales_tax_rate_3": "50.0",
    "second_sales_tax_is_compound": true
  }
}

Show as XML

<freeagent>
  <sales-tax-period>
    <url>https://api.freeagent.com/v2/sales_tax_periods/2</url>
    <sales-tax-name>First Tax</sales-tax-name>
    <sales-tax-rate-1 type="decimal">2.0</sales-tax-rate-1>
    <sales-tax-rate-2 type="decimal">3.0</sales-tax-rate-2>
    <sales-tax-rate-3 type="decimal">4.0</sales-tax-rate-3>
    <sales-tax-is-value-added type="boolean">true</sales-tax-is-value-added>
    <sales-tax-registration-status>Registered</sales-tax-registration-status>
    <sales-tax-registration-number>12345678</sales-tax-registration-number>
    <effective-date type="date">2016-09-21</effective-date>
    <is-locked type="boolean">false</is-locked>
    <second-sales-tax-name>Second Tax</second-sales-tax-name>
    <second-sales-tax-rate-1 type="decimal">10.0</second-sales-tax-rate-1>
    <second-sales-tax-rate-2 type="decimal">20.0</second-sales-tax-rate-2>
    <second-sales-tax-rate-3 type="decimal">50.0</second-sales-tax-rate-3>
    <second-sales-tax-is-compound type="boolean">true</second-sales-tax-is-compound>
  </sales-tax-period>
</freeagent>

Show as JSON

Create a sales tax period

POST https://api.freeagent.com/v2/sales_tax_periods

Payload should have a root sales_tax_period element, containing elements listed under Attributes.

Response

Status: 201 Created
Location: https://api.freeagent.com/v2/sales_tax_periods/123

{
  "sales_tax_period": {
    "url": "https://api.freeagent.com/v2/sales_tax_periods/2",
    "sales_tax_name": "First Tax",
    "sales_tax_rate_1": "2.0",
    "sales_tax_rate_2": "3.0",
    "sales_tax_rate_3": "4.0",
    "sales_tax_is_value_added": true,
    "sales_tax_registration_status": "Registered",
    "sales_tax_registration_number": "12345678",
    "effective_date": "2016-09-21",
    "is_locked": false,
    "second_sales_tax_name": "Second Tax",
    "second_sales_tax_rate_1": "10.0",
    "second_sales_tax_rate_2": "20.0",
    "second_sales_tax_rate_3": "50.0",
    "second_sales_tax_is_compound": true
  }
}

Show as XML

<freeagent>
  <sales-tax-period>
    <url>https://api.freeagent.com/v2/sales_tax_periods/2</url>
    <sales-tax-name>First Tax</sales-tax-name>
    <sales-tax-rate-1 type="decimal">2.0</sales-tax-rate-1>
    <sales-tax-rate-2 type="decimal">3.0</sales-tax-rate-2>
    <sales-tax-rate-3 type="decimal">4.0</sales-tax-rate-3>
    <sales-tax-is-value-added type="boolean">true</sales-tax-is-value-added>
    <sales-tax-registration-status>Registered</sales-tax-registration-status>
    <sales-tax-registration-number>12345678</sales-tax-registration-number>
    <effective-date type="date">2016-09-21</effective-date>
    <is-locked type="boolean">false</is-locked>
    <second-sales-tax-name>Second Tax</second-sales-tax-name>
    <second-sales-tax-rate-1 type="decimal">10.0</second-sales-tax-rate-1>
    <second-sales-tax-rate-2 type="decimal">20.0</second-sales-tax-rate-2>
    <second-sales-tax-rate-3 type="decimal">50.0</second-sales-tax-rate-3>
    <second-sales-tax-is-compound type="boolean">true</second-sales-tax-is-compound>
  </sales-tax-period>
</freeagent>

Show as JSON

Update a sales tax period

PUT https://api.freeagent.com/v2/sales_tax_periods/:id

Payload should have a root sales_tax_period element, containing elements listed under Attributes that you wish to update.

Response

Status: 200 OK

Delete a sales tax period

Note: Deleting a locked period is not allowed.

DELETE https://api.freeagent.com/v2/sales_tax_periods/:id

Response

Status: 200 OK