Banqup API Docs

What they are

Product registers are the tax engine’s catalog of “tax products” or “tax classifications”, covering both goods and services, to which product-level tax content is assigned.

Each product entry describes what goods, service or group of goods and services is intended, will assign certain classifications to that tax product, and will allow the mapping of detailed, country specific, product level tax content (like any reduced rate or tax deduction limitation).

Product registers act as the placeholder for the products the engine will “recognize” during the tax call and to which it will be able to apply the right taxation.

The tax engine includes:

Admin-level (standard) registers, maintained by the platform with predefined products and maintained, up-to-date product-level tax content.
The ability for clients to create their own product registers and define their own tax content, or link their registers to the admin registers to benefit from standard content.

Why they matter

Different goods and services can be taxed differently. To enable automation, the engine needs to store product level tax content and to do so, it needs to do this in the most efficient and flexible way. Therefore, the engine has designed product registers, where users can define the categories / labels relevant for tax determination, and store the content behind these defined categories that are made available for product mapping purposes (see later).

By using product registers:

The tax engine can automatically apply the correct product-level rules.
Clients no longer need to manually decide tax treatment per transaction.
Standard registers provide “ready-made” product tax content for common scenarios.
Custom registers allow clients to handle unique or industry-specific products.

In short, product registers ensure that product classification drives tax logic, making results consistent, scalable, and compliant.

What the client does

Clients use product registers in configuration to:

Map their products or product codes to items in a register.
Choose whether to use standard admin registers.
Create their own registers if the standard admin registers are not sufficient.
Assign custom tax content or link custom registers to admin registers where needed to get access to the appropriate product level tax content.

This gives clients control over how their product catalog translates into tax behavior.

Outcome

By configuring product registers (in combination with the product mapping):

The tax engine recognizes the client’s products correctly.
Product-level tax content is applied automatically during calculation.
Standard content can be used immediately, reducing setup effort.
Custom content can support unique business or tax requirements.
Transactions become more accurate, automated, and repeatable.

Ultimately, product registers are the foundational component that enables product-based tax determination.

Additional remark: two types of registers

In the engine, there are two types of product registers, available for both admin and client level use:

Standard registers: the standard registers allow users to create products, sub-products etc that will be available for product level content storage and product mapping. Each product or sub-product in a register will have a unique identifier and will function as an individual product.
Lookup enabled registers: a second type of register is designed for storing products that have a structured, multi-level format, that require a multi-level lookup as the data sent to the engine might be on different levels. An example of such a structured dataset requiring multi-level lookup would be the HSN code register.

What it is

Product mapping links the goods or services you sell or purchase to the tax characteristics that the engine needs to determine the correct VAT treatment.

Why it matters

Different products may be taxed differently (e.g., standard vs. reduced rates). By mapping your product categories to the appropriate tax attributes, the engine can apply the right tax rules automatically.

What the client does

Assign each product or product group to the correct tax-related classification.
Ensure new or updated products are mapped before use.
Maintain mappings as your product catalog evolves.

Outcome

Every transaction sent to the tax engine includes the product context needed for accurate tax determination.

Additional remark: override mapping

Next to the classical product mapping, the engine provides users the ability to create separate ‘override mappings’. These are rules based mappings that can be configured in a separate workbench and allow users to bypass the product mapping under specific conditions and thus further fine tune the configuration.

What it is

Country-level tax content represents the core tax rules stored in the tax engine for each country. These rules define how tax should be applied based on country-specific legislation, such as place of supply rules, liability rules, exemptions etc..

On admin level the engine has configured the standard rules for the countries supported with content. This has been done using configurable rules within a predefined framework that governs how the tax engine evaluates a transaction for each country.

By default, for the countries supported, these rules apply at the admin level out of the box. However, clients have the ability to create their own versions of these rules for specific countries if they require different outcomes by layering their own custom rules on top of the admin rules.

When client-defined rules exist, custom logic overrides has higher priority than admin-level content, becoming the active logic used in tax determination.

Why it matters

Country-level tax rules are important decisive factors in determining the correct tax outcome. They define:

Which country’s tax rules apply.
Who is liable for the tax.
Whether tax should be charged or exempt.
Which scenario triggers which tax treatment.

Because tax legislation and business models vary, clients may encounter situations where:

The standard rules do not reflect their specific business needs.
They operate under special industry arrangements.
They require custom decision paths for compliance or internal policy.

Admin level engine country tax content is not standard for all countries and during implementation, country coverage should be reviewed. Depending on the requirements:

The standard coverage may be sufficient.
Clients require tax content in non-supported jurisdictions and can fill the geographical coverage gaps using the custom country tax content configuration.

The ability to configure custom country-level tax content ensures the tax engine can adapt to real-world operational and regulatory complexity as well as broad geographical coverage, rather than forcing a one-size-fits-all approach.

What the client does

Within the configuration framework, clients can:

Select a country for which they want to create custom rules.
Define new rule logic within the provided structure and rule types.
Adjust outcomes for place of supply, liability, exemptions, or other country-level factors.
Replace or override the standard (admin-level) logic for that country.
Create new content for countries that are not supported by admin level content.
Maintain, update, or deactivate their custom rules as business needs evolve.

Outcome

Once custom country-level tax content is activated:

The tax engine applies the client’s rule logic instead of the standard admin logic for that country.
Tax outcomes become aligned with the client’s specific interpretation, policy, or compliance needs.
Manual overrides and exception handling are reduced.
Tax logic becomes more predictable, consistent, and tailored.

In short, clients gain the ability to drive the actual tax logic that governs their transactions, ensuring the engine reflects the way their business needs to operate.

What it is

Tax code mapping connects your organization’s internal tax codes, often used for reporting or accounting, to the tax outcomes generated by the engine.

Why it matters

While the engine determines the correct VAT treatment, your internal systems may require a specific tax code for posting, reporting, or ERP integration. Mapping ensures the engine’s output seamlessly aligns with your internal processes.

What the client does

Define which internal tax codes correspond to each calculated tax outcome.
Configure codes needed for financial reporting or compliance purposes.
Update mappings when tax rules or reporting structures change.

Outcome

The tax engine’s results can be used directly in your downstream systems without manual translation or reclassification.

Additional remark: admin level tax codes

The tax engine also has systems generated tax codes that can be used. They are generated according to a defined schedule and if they serve your purpose, there is no need to configure custom tax codes.

Admin level tax codes and custom tax codes use different fields in the API.

What it is

Invoice wording configuration allows users to define the textual statements or messages that can be used for invoicing as a result of tax outcomes, for example references to exemptions, reverse charge, special schemes, or legal notes.

Using a rules-based workbench, clients can create custom invoice wordings and specify the conditions under which each wording should be applied. This ensures that the right message is automatically assigned when a transaction meets certain tax criteria.

Why it matters

In many cases the tax outcome alone is not enough, invoices must include specific text to comply with legal, industry, or customer requirements. The correct invoice wording can:

Support compliance with country or scenario-specific legislation.
Provide clarity to customers and auditors.
Document exemptions, liabilities, or special treatments.
Reduce manual edits and post-processing.

For situations requiring more detailed or scenario-specific statements, custom configurations ensure the invoice fully reflects the underlying tax logic.

What the client does

Clients configure invoice wordings by:

Defining custom wording text relevant to their business or compliance needs.
Creating rules that specify when a wording should be applied (e.g., based on country, exemption status, liability, product, or tax outcome).
Testing and refining the rules to ensure the correct wording is allocated in each scenario.
Updating wordings and rules when requirements change.

This allows invoice messaging to align tightly with operational, legal, and internal communication needs.

Outcome

Configured invoice wordings ensure that:

The correct text automatically appears on invoices based on tax results.
Manual intervention and rework are minimized.
Compliance and transparency are strengthened.
Downstream invoicing processes run more smoothly.

In short, invoice wording configuration enables precise, automated communication of tax-related information on invoices.

Additional remark: admin-level invoice wordings

The tax engine includes a set of admin-level, system-provided invoice wordings that are available out of the box. They are designed to cover broad, standard scenarios. If these standard wordings meet the client’s needs, no custom configuration is required.

However, when more detailed, business-specific, or legally precise wording is required, clients can define and activate their own custom invoice wordings.

Admin level invoice wordings and custom invoice wordings use different fields in the API.

What they are

These rules allow you to define how the engine should handle missing, incorrect, or inconsistent data before tax calculation takes place (custom input rules) and allow you to change any tax conclusion at the end of the tax call, before outputting the result (custom output rules).

Why they matter

Not all source data is perfect. Input rules help prevent errors, improve calculation quality, and reduce failed transactions. Also, sometimes users will know that under certain circumstances, the engine result will not fit their needs. A custom output rule is one way of adjusting or customizing the engine result.

What the client can do

Set default values when data is missing.
Flag or correct invalid data formats.
Override certain inputs when business exceptions apply.
Add custom fields or memos to the tax output.
Transform tax results into specific internal formats.
Trigger custom outcomes for specific scenarios.

Outcome

Cleaner, more reliable data enters the engine, resulting in more accurate tax outcomes. Ensure any required custom results deviating from the general rules are configured and do not require manual intervention.

What they are

Lookup tables are user-defined reference tables that store lists of values or attributes that can be used inside custom rules throughout the tax engine. They act as a structured data source that rules can query, for example to identify specific products, partners, countries, tax statuses, or special conditions.

Instead of hard-coding values directly into rules, lookup tables provide a central place to store data that rules can reference dynamically.

Why they matter

Lookup tables make custom rules:

More flexible and maintainable: values can be changed without rebuilding the rule logic.
More scalable: large value sets (e.g., product lists, customer groups) can be managed efficiently and reused in different rules.
More precise: rules can target specific lists or categories rather than broad conditions or a list of values embedded in the rule.

This allows clients to manage complex or variable tax logic in a structured reusable way, especially when working with large catalogs, segmented customer groups, or frequently changing conditions.

What the client does

Clients can:

Create new lookup tables and define the data fields they contain.
Populate the tables with values relevant to their tax logic.
Reference these tables inside custom input rules, output rules, product rules, or country-level rules.
Update or expand the tables over time without modifying the rules themselves.
Use lookup tables to trigger targeted conditions (e.g., “apply this logic only if the customer is in this list”).

This gives clients data-driven control over how rules behave.

Outcome

With lookup tables in place:

Custom rules become cleaner, reusable, and easier to maintain.
Tax logic can adapt quickly when business data changes.
Users avoid manual edits across multiple rules.
Complex targeting or segmentation becomes simple to manage.

Overall, lookup tables enable smart, data-powered rule behavior without redesigning rule logic every time data changes.

What they are

Sourcing rules define where the tax engine should obtain a country value when a non-mandatory country field required for certain tax logic (e.g., special place of supply scenarios) is missing in the API request.

Under standard operation:

Some country fields are mandatory and always provided.
Other country fields are optional but may be needed for specific tax conclusions depending on the transaction at hand (e.g., where a service physically occurs, where an immovable good is located).

If the engine needs such a non-mandatory field to determine the place of supply or otherwise, and this field is empty, the engine uses a predefined sourcing sequence, pulling the value from other fields until it reaches a mandatory field, ensuring the engine always has a usable country value and does not fail.

This sourcing system exists at admin level by default. The user can define custom sourcing rules, which replace the admin sourcing logic for the relevant fields.

Why they matter

In special place-of-supply scenarios, the correct country is critical to determining:

Which country’s tax rules apply.
Whether tax is charged or exempt.
Who is liable.

If required country fields are empty, the engine could otherwise:

Fail to reach a tax conclusion.
Misclassify the transaction.
Produce incorrect tax outcomes.

Sourcing rules ensure:

The engine always finds a country value to calculate with.
Missing data does not break the logic.
Special scenarios remain fully automated.

Custom sourcing rules go further, allowing clients to:

Reflect their data structures and business flows more accurately.
Improve precision when the default sourcing path is not optimal.
Tailor how country values are derived for their specific use cases.

What the client does

In case standard sourcing rules are not deemed sufficient or desired, clients can configure sourcing rules by:

Selecting which country fields the sourcing logic should apply to (limited list).
Defining the sequence of fallback fields the engine should use when a field is empty.
Aligning the sourcing logic with their own data availability and business processes.
Testing how the sourcing behaves across scenarios.
Updating the sourcing definitions as data flows or system integrations evolve.

When custom sourcing rules are activated, they take precedence over admin-level sourcing rules for the relevant fields.

Outcome

With custom sourcing rules configured:

The engine always has a valid country value to work with, in line with client specific requirements.
Special place-of-supply logic runs reliably even when inputs are incomplete.
Clients reduce calculation errors and failed transactions.
Country determination better reflects the client’s business model.
Manual intervention to correct missing fields is minimized.

In short, custom sourcing rules ensure resilient, accurate, and business-aligned country determination, even when optional fields are not populated.

What they are

Sourcing rules define where the tax engine should obtain a country value when a non-mandatory country field required for certain tax logic (e.g., special place of supply scenarios) is missing in the API request.

Under standard operation:

Some country fields are mandatory and always provided.
Other country fields are optional but may be needed for specific tax conclusions depending on the transaction at hand (e.g., where a service physically occurs, where an immovable good is located).

If the engine needs such a non-mandatory field to determine the place of supply or otherwise, and this field is empty, the engine uses a predefined sourcing sequence, pulling the value from other fields until it reaches a mandatory field, ensuring the engine always has a usable country value and does not fail.

This sourcing system exists at admin level by default. The user can define custom sourcing rules, which replace the admin sourcing logic for the relevant fields.

Why they matter

In special place-of-supply scenarios, the correct country is critical to determining:

Which country’s tax rules apply.
Whether tax is charged or exempt.
Who is liable.

If required country fields are empty, the engine could otherwise:

Fail to reach a tax conclusion.
Misclassify the transaction.
Produce incorrect tax outcomes.

Sourcing rules ensure:

The engine always finds a country value to calculate with.
Missing data does not break the logic.
Special scenarios remain fully automated.

Custom sourcing rules go further, allowing clients to:

Reflect their data structures and business flows more accurately.
Improve precision when the default sourcing path is not optimal.
Tailor how country values are derived for their specific use cases.

What the client does

In case standard sourcing rules are not deemed sufficient or desired, clients can configure sourcing rules by:

Selecting which country fields the sourcing logic should apply to (limited list).
Defining the sequence of fallback fields the engine should use when a field is empty.
Aligning the sourcing logic with their own data availability and business processes.
Testing how the sourcing behaves across scenarios.
Updating the sourcing definitions as data flows or system integrations evolve.

When custom sourcing rules are activated, they take precedence over admin-level sourcing rules for the relevant fields.

Outcome

With custom sourcing rules configured:

The engine always has a valid country value to work with, in line with client specific requirements.
Special place-of-supply logic runs reliably even when inputs are incomplete.
Clients reduce calculation errors and failed transactions.
Country determination better reflects the client’s business model.
Manual intervention to correct missing fields is minimized.

In short, custom sourcing rules ensure resilient, accurate, and business-aligned country determination, even when optional fields are not populated.

What they are

Transaction memos are automated notification messages that the tax engine can attach to a transaction when certain conditions or scenarios occur. These memos act as alerts or flags, informing users that a transaction may require review, attention, or follow-up based on the data provided or the tax outcome generated.

In essence, transaction memos allow the engine to communicate insights or warnings back to business users, without changing the tax result, by adding memo items into the transaction output.

Why they matter

Transaction memos help organizations:

Detect unusual or exceptional transaction scenarios.
Identify potential data issues or inconsistencies.
Highlight outcomes that may require manual validation.
Support review processes, audit readiness, and quality control.
Reduce the risk of unnoticed tax errors or anomalies.

They ensure that important signals are proactively surfaced, rather than relying on manual monitoring or downstream discovery.

What the client does

Clients configure transaction memos by:

Creating memo items and descriptions in a dedicated workbench.
Defining rule conditions under which a memo should be triggered (e.g., certain data patterns, missing inputs, unusual tax outcomes).
Assigning specific memos to those conditions.
Testing memo behavior across transactions.
Updating memo content or rule conditions as business processes evolve.

Once configured, the system automatically applies memos when the defined conditions are met, ensuring consistent detection and communication.

Outcome

With transaction memos in place:

Business users receive clear signals when transactions need review.
Potential issues are identified earlier and more consistently.
Review and validation processes become more efficient and targeted.
Risk and manual effort are reduced.
Transaction oversight becomes structured and auditable.

In short, transaction memos enhance visibility, control, and governance over tax-relevant transactions.

Additional remarks

Memo items must be created before use

Before memos can be used in rules, users must create memo items and descriptions in a separate workbench. Only once created can these memo items be referenced in transaction memo rules.

This ensures a controlled and consistent library of memo messages.

Admin-level and custom memos

The engine provides:

Admin-level transaction memos (standard, predefined options).
Custom transaction memos created by users.

If the admin options are sufficient, no custom memos are required. If more detailed, business-specific messages are needed, users can define their own.

Two types of transaction memos

There are two distinct memo types, each returned in different output fields of the response API:

A. General Transaction Memos

Triggered based on data conditions or transaction outcomes.
Act as alerts or guidance for business review.
Attached directly to the transaction output.
Used for operational oversight and exception handling.

B. Transaction Diff Memos

Used in a separate comparison workbench.
Designed to compare key values sent in the request (e.g., tax rate, tax amount) with the engine’s recalculated results.
Identify differences or discrepancies for validation purposes, allowing tolerances to be set.
Returned in a separate API output field from general memos.

These memos support structured validation workflows, especially when checking pre-calculated inputs against engine results.

Tax configuration

See also

Tax configuration​

See also​

Tax configuration

See also