logo
API docs by Redocly

Anrok API (1.1)

Download OpenAPI specification:Download

E-mail: support@anrok.com License: All rights reserved Terms of Service
API Tutorials

API reference

The Anrok API server is accessible at https://api.anrok.com.

All requests are HTTP POSTs with JSON in the body.

Authentication is via an HTTP header Authorization: Bearer {apiKey}.

The default rate limit for a seller account is 10 API requests per second.

Customer certificates

Customer exemption certificates

Create customer certificate

This endpoint is used to create a new customer certificate in Anrok.

Authorizations:
http
Request Body schema: application/json
customerId
required
string (CustomerId)

The Anrok customer ID used to link transactions for the same customer and to look up tax exemption certificates for a customer. This is typically the billing system's customer ID with a prefix to disambiguate.

  • If customerId is provided without customerName, that customer object must already exist in Anrok.
  • If both customerId and customerName are provided, the customer object will be created if it is not already present.
  • Customer IDs are unique across the entire seller account.
customerName
string (CustomerName)

The name of the customer. This is used for display purposes only.

effectiveDateBegin
required
string <date>

Effective date of certificate

exemptionNumber
string

Certificate exemption number. This is used for display purposes only.

notes
string

Optional internal notes.

required
object (CustomerCertificateFile)
required
Array of objects (CustomerCertificateJuris)

Jurisdictions for which certificate applies

Responses

Request samples

Content type
application/json
{
  • "customerId": "cus_123",
  • "customerName": "Acme Inc",
  • "effectiveDateBegin": "2022-01-01",
  • "exemptionNumber": "cert-100",
  • "certificateFile": {
    },
  • "jurises": [
    ]
}

Response samples

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

Archive customer certificate

This endpoint is used to archive/invalidate a customer certificate.

Authorizations:
http
path Parameters
certificateId
required
string

ID of the certificate you want to archive.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Transactions

This documentation describes how to use Anrok's Transactions API to synchronize transactions between Anrok and your billing system, as well as calculate sales tax for new invoices. Use of this API is generally recommended for sellers with custom billing systems or workflows that prevent you from using one of our pre-built platform integrations. Sellers utilizing Stripe Subscriptions or Checkout may also use this API to calculate and add tax on initial invoices, while continuing to use Anrok's Stripe integration to manage tax for subsequent billing cycles.

Invoice lifecycle

  1. When an invoice is created: the billing system should call the createEphemeral endpoint to calculate the sales tax amount.
  2. When an invoice is updated: same as above.
  3. When an invoice is finalized and ready to send to the customer: the billing system should call the createOrUpdate endpoint so that the transaction is recorded in Anrok.
  4. When an invoice is paid: Anrok does not need to be notified. Sellers are required to remit sales tax to a state upon invoice, not receipt of payment.

While the above covers a standard invoice lifecycle, the Transactions API also includes endpoints for exceptional states like voiding and negating invoices, which are described below.

Create or update transaction

Given the details of an invoice, calculate sales tax and save it as a transaction in Anrok. Saved transactions are used by Anrok to file sales tax returns and monitor sales thresholds.

Authorizations:
http
Request Body schema: application/json
required
Array of objects (TransactionLineItem)

The line items in the transaction.

currencyCode
required
string = 3 characters

Three letter ISO currency code (case insensitive).

required
Address (object) or Legacy US only address (object)

The address where the product will be delivered or used. This address determines the taxing jurisdictions and rates for destination-based sourcing. For SaaS companies, this is typically the billing address. All address fields are optional: fields can be omitted or have null value, but empty strings are not allowed. Anrok will return an error if the address does not have enough information to determine the top-level taxing jurisdiction with high confidence. International is a premium feature. Please contact support@anrok.com for more information.

customerName
string (CustomerName)

The name of the customer. This is used for display purposes only.

Array of objects (CustomerTaxId)

Tax IDs for the customer receiving the product

accountingDate
string <date>

The date that this transaction occurred, for accounting purposes. Accounting date will typically correspond to the invoice date. This is used to determine which tax return the transaction belongs to.

accountingTime
string <date-time>

The time that this transaction occurred, for accounting purposes. If accountingDate is not provided, accountingTime is required to compute an accounting date for the transaction.

accountingTimeZone
string
Enum: "UTC" "America/New_York" "America/Chicago" "America/Denver" "America/Los_Angeles" "America/Anchorage" "Pacific/Honolulu"

A “tz database” string used to compute an accounting date from the request's accountingTime. The request cannot provide both an accountingDate and an accountingTimeZone. If accountingTime is provided without specifying an accountingTimeZone, the time zone configured on the seller account will be used.

taxDate
string <date>

The date to use for tax calculations. If omitted, Anrok will use the minimum of the accounting date and two days in the future.

customerId
string (CustomerId)

The Anrok customer ID used to link transactions for the same customer and to look up tax exemption certificates for a customer. This is typically the billing system's customer ID with a prefix to disambiguate.

  • If customerId is provided without customerName, that customer object must already exist in Anrok.
  • If both customerId and customerName are provided, the customer object will be created if it is not already present.
  • Customer IDs are unique across the entire seller account.
id
required
string

The ID of the new transaction. This must be unique across the entire seller account. This is typically the billing system's invoice ID with some prefix to disambiguate different systems.

Responses

Request samples

Content type
application/json
{
  • "id": "stripe:in_1JSW342eZvKYlo2C",
  • "currencyCode": "usd",
  • "accountingTime": "2022-01-02T03:30:00Z",
  • "accountingTimeZone": "UTC",
  • "lineItems": [
    ],
  • "customerAddress": {
    }
}

Response samples

Content type
application/json
{
  • "version": 1,
  • "taxAmountToCollect": 722,
  • "lineItems": [
    ],
  • "preTaxAmount": "68577.3304",
  • "jurisSummaries": [
    ]
}

Create ephemeral transaction

Given the details of an invoice, calculate sales tax without saving the transaction in Anrok. Ephemeral transactions are not used by Anrok to file sales tax returns or monitor sales thresholds.

Authorizations:
http
Request Body schema: application/json
required
Array of objects (TransactionLineItem)

The line items in the transaction.

currencyCode
required
string = 3 characters

Three letter ISO currency code (case insensitive).

required
Address (object) or Legacy US only address (object)

The address where the product will be delivered or used. This address determines the taxing jurisdictions and rates for destination-based sourcing. For SaaS companies, this is typically the billing address. All address fields are optional: fields can be omitted or have null value, but empty strings are not allowed. Anrok will return an error if the address does not have enough information to determine the top-level taxing jurisdiction with high confidence. International is a premium feature. Please contact support@anrok.com for more information.

customerName
string (CustomerName)

The name of the customer. This is used for display purposes only.

Array of objects (CustomerTaxId)

Tax IDs for the customer receiving the product

accountingDate
string <date>

The date that this transaction occurred, for accounting purposes. Accounting date will typically correspond to the invoice date. This is used to determine which tax return the transaction belongs to.

accountingTime
string <date-time>

The time that this transaction occurred, for accounting purposes. If accountingDate is not provided, accountingTime is required to compute an accounting date for the transaction.

accountingTimeZone
string
Enum: "UTC" "America/New_York" "America/Chicago" "America/Denver" "America/Los_Angeles" "America/Anchorage" "Pacific/Honolulu"

A “tz database” string used to compute an accounting date from the request's accountingTime. The request cannot provide both an accountingDate and an accountingTimeZone. If accountingTime is provided without specifying an accountingTimeZone, the time zone configured on the seller account will be used.

taxDate
string <date>

The date to use for tax calculations. If omitted, Anrok will use the minimum of the accounting date and two days in the future.

customerId
string

The Anrok customer ID used to link transactions for the same customer and to look up tax exemption certificates for a customer. This is typically the billing system's customer ID with a prefix to disambiguate.

  • If customerId is provided without customerName, that customer object must already exist in Anrok.
  • Customer IDs are unique across the entire seller account.

Responses

Request samples

Content type
application/json
{
  • "currencyCode": "usd",
  • "accountingTime": "2022-01-02T03:30:00Z",
  • "accountingTimeZone": "UTC",
  • "lineItems": [
    ],
  • "customerAddress": {
    }
}

Response samples

Content type
application/json
{
  • "taxAmountToCollect": 722,
  • "lineItems": [
    ],
  • "preTaxAmount": "68577.3304",
  • "jurisSummaries": [
    ]
}

Create negation

Creates a new transaction that is the exact inverse of the given transaction. The sale prices and tax amounts will add up to zero.

Authorizations:
http
Request Body schema: application/json
originalTransactionId
required
string

The ID of the transaction you want to negate.

newTransactionId
required
string

The ID for the new negated transaction.

originalTransactionExpectedVersion
integer <int32>

The expected transaction version. The refund will fail if this is not the latest version of the transaction.

Responses

Request samples

Content type
application/json
{
  • "originalTransactionId": "stripe:in_1JSW342eZvKYlo2C",
  • "newTransactionId": "stripe:in_1JSW342eZvKYlo2C_refund"
}

Response samples

Content type
application/json
{ }

Void transaction

Mark a previously-created transaction as void. It will no longer be included in returns or sales totals.

Authorizations:
http
path Parameters
transactionId
required
string

ID of the transaction you want to void.

Request Body schema: application/json
transactionExpectedVersion
integer <int32>

The expected transaction version. The void will fail if this is not the latest version of the transaction.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{ }

Product mappings

Distinct from Anrok's Transaction API, these endpoints enable you to manage your Product IDs in Anrok via API. You may use these endpoints to supplement your core integration, whether that's through our Transaction API or one of our partner integrations. This API is designed to support you in dynamically mapping new Products and viewing a comprehensive list of existing mappings. Because we aim to keep your product list in Anrok minimal and focused on truly distinct offerings, we use mappings to associate various products in your billing system with the equivalent products in Anrok. This API enables you to confirm that each product on any transaction seen by Anrok is mapped to a defined product and will be assessed properly for taxability calculations as a result.

List product mappings

Lists all Product ID mappings for this integration.

Authorizations:
http
path Parameters
integrationId
required
string

Your unique integration ID.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Add product mapping

Adds a product ID mapping for this integration.

Authorizations:
http
path Parameters
integrationId
required
string

Your unique integration ID.

Request Body schema: application/json
sourceId
required
string

Source product ID from billing system.

targetId
required
string

Target product ID on Anrok. This product must already exist in Anrok.

shouldOverwrite
boolean
Default: false

Whether this request should override an existing sourceId mapping.

Responses

Request samples

Content type
application/json
{
  • "sourceId": "billing system ID",
  • "targetId": "anrok ID"
}

Response samples

Content type
application/json
{ }

Tax ID validation

The Anrok Tax ID Validation endpoint is a premium feature. Please contact hello@anrok.com for more information to enable this on your Anrok seller account.

  1. Pass a customer address and an empty array of customerTaxIds:
    • Anrok verifies the customer address is valid for tax calculation.
    • Anrok responds with the list of customer tax IDs to collect.
  2. Collect the customer tax IDs and call the API endpoint again to validate them:
    • Anrok provides a list of valid tax IDs for each applicable jurisdiction.

Validate tax IDs

This endpoint is used to assist in the collection and validation of customer tax IDs.

Authorizations:
http
Request Body schema: application/json
required
object (CustomerAddress)

The customer address. This address determines the applicable taxable jurisdictions for the customer. If the provided address cannot be resolved to a taxable jurisdiction with high confidence Anrok will return customerAddressCouldNotResolve.

required
Array of objects

The tax IDs to validate.

Responses

Request samples

Content type
application/json
{
  • "customerAddress": {
    },
  • "customerTaxIds": [
    ]
}

Response samples

Content type
application/json
{
  • "jurises": [
    ]
}