VAT Status Cache
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:
Setting | Details | Description |
---|---|---|
b2b-number-service-timeoutms-<country or region> | Maximum Length: 64 Default Value: 20000ms 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: 20000 , EU validations will wait 20 seconds for a response from VIES. |
b2b-number-service-cache-expiry-days | Default 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-error | Possible 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 25 days ago