GuidesAPI Reference

VAT Status Cache

Suggest Edits

After a Tax ID is validated, its status is stored in the cache (results for invalid IDs are not stored). This cached status can be used to facilitate validation without the need to check the tax authority’s database again. This can help with performance and availability issues.

The caching mechanism retains data from the last 30 days by default. However, you can change this by using a control flag in each request.

If you do not want to use the cache at all, you can ask Vertex to set the cache to 0. However, this is not recommended as your validations may fail if a tax authority's service is not available, due to scheduled downtime or any other reason. For this reason, we recommend using the cache with a minimum value of at least 1 day.

UI Setting

If you want, you can set the timeout value in the UI. See Country Settings.

API Integration

🚧

This only works with integrated deployments of Validator

The following example shows a retention period that is set to 30 days using the control flag:

{ "private_token": "*******",
  "transaction": {
    "currency_code": "EUR",
    "control_flags": [
      {
        "key": "b2b-number-service-cache-expiry-days",
        "value": "30"
      }
    ],
    "billing_country_code": "NO",
    "transaction_lines": [
      {
        "custom_id": "1",
        "amount": 100
      }
    ],
    "buyer_ip": "",
    "buyer_tax_number": "NO123456789",
  }
}

Tax ID Cache Control Flags

You can use Control Flags in your requests to adjust the settings that control how values are stored in the cache:

SettingDetailsDescription
b2b-number-service-timeoutms-<country or region>Maximum Length: 64
Default Value: 2000ms
Minimum Value: 1000ms
Maximum Value: 3000ms		This setting specifies the timeout value for the service that validates the number.
For example if the setting is b2b-number-service-timeoutms-EU: 2000, EU validations will wait 2 seconds for a response from VIES.
b2b-number-service-cache-expiry-daysDefault Value: 30
Minimum Value: 0
Maximum Value: 365		This setting specifies the number of days that before the cached data is refreshed.
You can set it to 0 to force the service to bypass the cache and use the validation service in real-time.
b2b-number-service-on-errorPossible Values: accept or block
Maximum Length: 16 		If set to accept, the transaction is treated as successful even if the validation check fails due to a timeout or any other issue.
If set to block, the transaction is blocked, the response will be a HTTP 400 error with a warning.

Here is an example of a block response with a warning:

"errors": [
        "Business number validation service unavailable. Please re-submit your request later."
],
"warnings": [
    {
        "type": "ukraine-b2b-error",
        "message": "connect timed out"
    }
]

Here is an example of the control flags in an example transaction:

{
  "transaction": {
    "buyer_name": "John Smith",
    "currency_code": "EUR",
    "status":"N",
    "invoice_address": {
          "region": "",
          "city": "",
          "postal_code": "",
          "street_name":"",
          "address_details":""
      },
    "transaction_lines": [
      {
        "custom_id": "Test",
        "amount": 100,
        "quantity": 1
      }
    ],
    "control_flags": [
        {
            "key": "b2b-number-service-cache-expiry-days",
            "value": "30"
        },
        {
            "key": "b2b-number-service-on-error",
            "value": "accept"
        }
    ],
    "buyer_tax_number": "CZ12345678",
    "order_date": null,
    "billing_country_code": "CZ",
    "buyer_ip":"192.168.0.1"
  }
}

Updated about 2 months ago