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": [