Pact Tax API (2020-beta)

Download OpenAPI specification:Download

The Pact API Team: api@pact.tax

The Pact API specification.

Authentication

Authentication details will go here.

ApiKeyAuth

Security Scheme Type API Key
Header parameter name: x-api-key

Transactions

Transactions are a collection of lines with contextual data. They represent an order, invoice or sale generated by a point of sale or eCommerce system.

Transactions follow a lifecycle (show lifecycle here with a simple diagram).

Create a new transaction

Create a new transaction for comprehensive tax rating.

Successful requests will return the detailed transaction complete with ratings for every tax available in the appropriate jurisdictions.

Authorizations:
header Parameters
PactApiVersion
required
string
Value: "2020-beta"

Pact API version selector. Backward incompatible changes will always change the version.

Request Body schema: application/json
calculation_time
string <date-time> (TransactionCalculationTime)

Optional timestamp used to calculate a tax rating at a given point in time.

We use this timestamp to determine which taxes and rules a should apply to this transaction at the given time.

Defaults to the current time.

object (TransactionDestinationAddress)

Optional destination address. Most commonly used for delivery destinations. But it must be used whenever a transaction is completed at a location other than the origin address.

Very important: Taxation is subject to a jurisdiction's source rules and may be based on the location that the goods or services exchanged hands. For this reason it's imperative that the address where the goods or services were exchanged is provided here.

For example, when an order is delivered to a customer's home the destination address would be the customer's address, the address where the product is delivered.

If the goods or services are exchanged anywhere but the origin address and you do not include a destination address there is a very high likelihood your tax calculation will be incorrect and reported to the wrong taxing authority or jurisdiction, potentially resulting in significant fines and penalties.

external_id
string (TransactionExternalId) [ 1 .. 100 ] characters

External id of a transaction. This field is optional and always reflects the value provided when the transaction was created.

Use it when you want to associate custom information to find the corresponding local state.

For example, it could be used to associate a Pact transaction with your cart or order id.

required
Array of objects (TransactionLines) [ 1 .. 1024 ] items

Lines that are part of a transaction. Many other systems will call these "line items", but we've used lines so that we avoid verbose semantics like line_items.item. We mention this to reduce confusion and help to map the concept to other systems.

medical
boolean (TransactionMedicalFlag)

If true the transaction is calculated with all possible medical exemptions.

When absent or set to false no medical exemptions apply.

required
object (TransactionOriginAddress)

Origin address of the transaction, typically the address of the facility.

The origin address is used to look up the appropriate tax rate for transactions without a destination address or jurisdictions that are origin sourced.

This address, like destination_address is geolocated and provides the matched_origin_address field. The accuracy of these addresses will affect the confidence scoring.

taxes_included
Array of strings (TransactionIncludedTaxes) unique
Items Enum: "ca.local.cannabis_business_tax" "ca.sales_and_use_tax" "ca.state.cannabis_excise_tax" "or.local.option_tax" "or.state.marijuana_tax"

Taxes can be included in prices or added to them. Use this field to indicate what taxes should be included in prices.

Note that this field affects all items in a transaction. General practice is to add a notice somewhere on premises or on the receipt stating that all taxes are included.

You can find all currently supported taxes including associated tax ids at GET /taxes.

Example:

  • Item A is $10.00
  • The local cannabis business tax is 3%.
  • taxes_included includes ca.local.cannabis_business_tax.
  • Taxable amount is $9.71 and the tax is $0.29 for a total of $10.00
type
required
string (TransactionType)
Enum: "refund" "sale"

Type of the transaction.

This field affects reporting and returns. Ratings are not affected.

Responses

Request samples

Content type
application/json
{
  • "calculation_time": "2019-08-24T14:15:22Z",
  • "destination": {
    },
  • "external_id": "string",
  • "lines": [
    ],
  • "medical": true,
  • "origin": {
    },
  • "taxes_included": [
    ],
  • "type": "refund"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "business_entity_id": "1e39e50d-3419-4cb0-83f0-69adb28fbb26",
  • "calculation_time": "2019-08-24T14:15:22Z",
  • "destination": {
    },
  • "external_id": "string",
  • "facility_id": "82d24387-b696-4928-8926-f6f7f16d3353",
  • "flags": {
    },
  • "lines": [
    ],
  • "matched_destination_address": {
    },
  • "matched_origin_address": {
    },
  • "medical": true,
  • "origin": {
    },
  • "score": 0,
  • "stage": "completed",
  • "taxes_included": [
    ],
  • "total": 0,
  • "total_lines": 0,
  • "total_tax": 0,
  • "tax_results": [
    ],
  • "tax_result_summary": {
    },
  • "type": "refund"
}

Get a transaction

Get an individual transaction identified by the id path parameter. We generate a UUID for each unique transaction to identify it throughout the transaction lifecycle.

On success the response body contains the transaction as it was returned when it was created.

We don't recalculate transactions until you update them with a PATCH /transactions/{id} request.

Authorizations:
path Parameters
id
required
string <uuid> (ResourceId)

Unique id of a transaction generated by us. This is not an external ID reference.

We do provide a way to associate external IDs generated by your system. If you want to tie our transaction to one of yours see ExternalId.

header Parameters
PactApiVersion
required
string
Value: "2020-beta"

Pact API version selector. Backward incompatible changes will always change the version.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "business_entity_id": "1e39e50d-3419-4cb0-83f0-69adb28fbb26",
  • "calculation_time": "2019-08-24T14:15:22Z",
  • "destination": {
    },
  • "external_id": "string",
  • "facility_id": "82d24387-b696-4928-8926-f6f7f16d3353",
  • "flags": {
    },
  • "lines": [
    ],
  • "matched_destination_address": {
    },
  • "matched_origin_address": {
    },
  • "medical": true,
  • "origin": {
    },
  • "score": 0,
  • "stage": "completed",
  • "taxes_included": [
    ],
  • "total": 0,
  • "total_lines": 0,
  • "total_tax": 0,
  • "tax_results": [
    ],
  • "tax_result_summary": {
    },
  • "type": "refund"
}

Update a transaction

Update an individual transaction identified by the id path parameter. We generate a UUID for each unique transaction to identify it throughout the transaction lifecycle.

On success the response body contains the updated transaction, with an updated calculation result.

Authorizations:
path Parameters
id
required
string <uuid> (ResourceId)

Unique id of a transaction generated by us. This is not an external ID reference.

We do provide a way to associate external IDs generated by your system. If you want to tie our transaction to one of yours see ExternalId.

header Parameters
PactApiVersion
required
string
Value: "2020-beta"

Pact API version selector. Backward incompatible changes will always change the version.

Request Body schema: application/json
calculation_time
string <date-time> (TransactionCalculationTime)

Optional timestamp used to calculate a tax rating at a given point in time.

We use this timestamp to determine which taxes and rules a should apply to this transaction at the given time.

Defaults to the current time.

object (TransactionDestinationAddress)

Optional destination address. Most commonly used for delivery destinations. But it must be used whenever a transaction is completed at a location other than the origin address.

Very important: Taxation is subject to a jurisdiction's source rules and may be based on the location that the goods or services exchanged hands. For this reason it's imperative that the address where the goods or services were exchanged is provided here.

For example, when an order is delivered to a customer's home the destination address would be the customer's address, the address where the product is delivered.

If the goods or services are exchanged anywhere but the origin address and you do not include a destination address there is a very high likelihood your tax calculation will be incorrect and reported to the wrong taxing authority or jurisdiction, potentially resulting in significant fines and penalties.

external_id
string (TransactionExternalId) [ 1 .. 100 ] characters

External id of a transaction. This field is optional and always reflects the value provided when the transaction was created.

Use it when you want to associate custom information to find the corresponding local state.

For example, it could be used to associate a Pact transaction with your cart or order id.

required
Array of objects (TransactionLines) [ 1 .. 1024 ] items

Lines that are part of a transaction. Many other systems will call these "line items", but we've used lines so that we avoid verbose semantics like line_items.item. We mention this to reduce confusion and help to map the concept to other systems.

medical
boolean (TransactionMedicalFlag)

If true the transaction is calculated with all possible medical exemptions.

When absent or set to false no medical exemptions apply.

required
object (TransactionOriginAddress)

Origin address of the transaction, typically the address of the facility.

The origin address is used to look up the appropriate tax rate for transactions without a destination address or jurisdictions that are origin sourced.

This address, like destination_address is geolocated and provides the matched_origin_address field. The accuracy of these addresses will affect the confidence scoring.

taxes_included
Array of strings (TransactionIncludedTaxes) unique
Items Enum: "ca.local.cannabis_business_tax" "ca.sales_and_use_tax" "ca.state.cannabis_excise_tax" "or.local.option_tax" "or.state.marijuana_tax"

Taxes can be included in prices or added to them. Use this field to indicate what taxes should be included in prices.

Note that this field affects all items in a transaction. General practice is to add a notice somewhere on premises or on the receipt stating that all taxes are included.

You can find all currently supported taxes including associated tax ids at GET /taxes.

Example:

  • Item A is $10.00
  • The local cannabis business tax is 3%.
  • taxes_included includes ca.local.cannabis_business_tax.
  • Taxable amount is $9.71 and the tax is $0.29 for a total of $10.00
type
required
string (TransactionType)
Enum: "refund" "sale"

Type of the transaction.

This field affects reporting and returns. Ratings are not affected.

Responses

Request samples

Content type
application/json
{
  • "calculation_time": "2019-08-24T14:15:22Z",
  • "destination": {
    },
  • "external_id": "string",
  • "lines": [
    ],
  • "medical": true,
  • "origin": {
    },
  • "taxes_included": [
    ],
  • "type": "refund"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "business_entity_id": "1e39e50d-3419-4cb0-83f0-69adb28fbb26",
  • "calculation_time": "2019-08-24T14:15:22Z",
  • "destination": {
    },
  • "external_id": "string",
  • "facility_id": "82d24387-b696-4928-8926-f6f7f16d3353",
  • "flags": {
    },
  • "lines": [
    ],
  • "matched_destination_address": {
    },
  • "matched_origin_address": {
    },
  • "medical": true,
  • "origin": {
    },
  • "score": 0,
  • "stage": "completed",
  • "taxes_included": [
    ],
  • "total": 0,
  • "total_lines": 0,
  • "total_tax": 0,
  • "tax_results": [
    ],
  • "tax_result_summary": {
    },
  • "type": "refund"
}

Transition transaction stage

Transition an individual transactions to a target stage.

Please refer to the TransactionStage documentation for details of allowed transitions and their roles.

Transaction Lifecycle

Authorizations:
path Parameters
id
required
string <uuid> (ResourceId)

Unique id of a transaction generated by us. This is not an external ID reference.

We do provide a way to associate external IDs generated by your system. If you want to tie our transaction to one of yours see ExternalId.

stage
required
string (TransactionStage)
Enum: "completed" "draft" "placed" "reported" "void"

Target transaction stage.

header Parameters
PactApiVersion
required
string
Value: "2020-beta"

Pact API version selector. Backward incompatible changes will always change the version.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Taxes

There are two major types of categories: state tracking system categories and taxability categories. These endpoints are available to discover state specific categories for both types. (In development)

List available taxes

Get a detailed list of all available taxes.

Among other uses, this endpoint can be used to discover which taxes can used for taxes_included.

Authorizations:
header Parameters
PactApiVersion
required
string
Value: "2020-beta"

Pact API version selector. Backward incompatible changes will always change the version.

Responses

Response samples

Content type
application/json
[
  • {
    }
]