VAT Rate Notifications

This section describes notifications sent when VAT (tax) rates are created, updated, or deleted — either through a direct change or via the scheduled tax rate change mechanism.

History of changes

Change tag	Change description	Change date
IAP-28451	Initial version of VAT rate notifications	30.06.2026

Overview

Nexway Monetize allows merchants to configure tax rates per country and region and optionally schedule upcoming VAT rate changes for a future date and time. Whenever a tax rate is created, updated, or deleted — whether immediately or through the scheduler — a notification is sent to the configured receiver.

There are two groups of notifications, distinguished by the type field:

type value	Triggered by
tax_rate	A direct (immediate) create, update, or delete of a tax rate
scheduled_tax_rate	A create or update of a scheduled tax rate change record, or a failure when the scheduler tries to apply one

The outcome (success or failure) and the specific operation are encoded inside the vatRate object rather than in the top-level type field.

Event list

Direct tax rate events (type=tax_rate)

• Tax Rate Created — vatRate.operation=created, vatRate.failed=false
• Tax Rate Updated — vatRate.operation=updated, vatRate.failed=false
• Tax Rate Deleted — vatRate.operation=deleted, vatRate.failed=false
• Tax Rate Failed — vatRate.failed=true (any operation)

Scheduled tax rate events (type=scheduled_tax_rate)

• Scheduled Tax Rate Change Created — vatRate.operation=created, vatRate.failed=false
• Scheduled Tax Rate Change Updated — vatRate.operation=updated, vatRate.failed=false
• Scheduled Tax Rate Change Failed — vatRate.failed=true

Important: When a scheduled change is applied successfully at the planned time, the system sends a standard Tax Rate Updated (type=tax_rate, operation=updated) notification — identical in structure to a direct manual update. There is no dedicated "applied" event type.

List of fields

Name	Description	R/O
subject	Always tax-management for VAT rate notifications	R
type	tax_rate for direct changes; scheduled_tax_rate for scheduled change records	R
objectId	Unique identifier of the tax rate or scheduled change object	R
eventDate	Date and time of the event in ISO 8601 format	R
vatRate {object}	Tax rate details object	R
vatRate.operation	The operation performed: created, updated, or deleted	R
vatRate.failed	true if the operation failed; false if it succeeded	R
vatRate.iso2CountryCode	ISO 3166-1 alpha-2 country code, e.g. FR, CA	R
vatRate.regionCode	Region or province code, e.g. CA-QC. Present only if the rate applies to a specific region	O
vatRate.startDate	Planned activation time as a Unix epoch timestamp (milliseconds). Present only for scheduled_tax_rate notifications	O
vatRate.newTaxRates [{object}]	Array of tax rate entries. For multi-rate countries the array contains one entry per tax category	R
vatRate.newTaxRates[].value	Tax rate as a decimal, e.g. 0.05 for 5%	R
vatRate.newTaxRates[].taxCategory	Tax category identifier, e.g. STANDARD, FEDERAL, STATE, VAT	R
vatRate.newTaxRates[].taxName	Human-readable name of the tax, e.g. Federal Tax, QST	O

Examples

Tax Rate Created

{
  "subject": "tax-management",
  "type": "tax_rate",
  "objectId": "83353aee-427f-473d-a628-55727f590641",
  "eventDate": "2026-05-04T14:55:34Z",
  "vatRate": {
    "operation": "created",
    "failed": false,
    "iso2CountryCode": "VG",
    "regionCode": "VG-TEST",
    "newTaxRates": [
      {
        "value": 0.05,
        "taxCategory": "STANDARD"
      }
    ]
  }
}

Tax Rate Updated

This notification is sent for both direct (manual) updates and when the scheduler applies a planned change at its activation time. The payload is identical in both cases.

{
  "subject": "tax-management",
  "type": "tax_rate",
  "objectId": "11109753-db0f-435b-abf4-5119a6af3ab0",
  "eventDate": "2026-05-04T16:00:00Z",
  "vatRate": {
    "operation": "updated",
    "failed": false,
    "iso2CountryCode": "FR",
    "newTaxRates": [
      {
        "value": 0.08,
        "taxCategory": "STANDARD"
      }
    ]
  }
}

Tax Rate Deleted

{
  "subject": "tax-management",
  "type": "tax_rate",
  "objectId": "83353aee-427f-473d-a628-55727f590641",
  "eventDate": "2026-05-04T14:55:34Z",
  "vatRate": {
    "operation": "deleted",
    "failed": false,
    "iso2CountryCode": "VG",
    "regionCode": "VG-TEST",
    "newTaxRates": [
      {
        "value": 0.05,
        "taxCategory": "STANDARD"
      }
    ]
  }
}

Tax Rate Failed

The failed flag is set to true for both direct (tax_rate) and scheduled (scheduled_tax_rate) failures. The operation field reflects what was attempted.

{
  "subject": "tax-management",
  "type": "tax_rate",
  "objectId": "83353aee-427f-473d-a628-55727f590641",
  "eventDate": "2026-05-04T14:55:34Z",
  "vatRate": {
    "operation": "updated",
    "failed": true,
    "iso2CountryCode": "FR",
    "newTaxRates": [
      {
        "value": 0.08,
        "taxCategory": "STANDARD"
      }
    ]
  }
}

Scheduled Tax Rate Change Created

Sent when a new scheduled change record is created. The startDate field contains the planned activation time as a Unix epoch timestamp in milliseconds.

{
  "subject": "tax-management",
  "type": "scheduled_tax_rate",
  "objectId": "a19667ce-ccae-4fba-9666-6ba09ec25748",
  "eventDate": "2026-04-30T10:26:58Z",
  "vatRate": {
    "operation": "created",
    "failed": false,
    "iso2CountryCode": "FR",
    "startDate": 1777555858000,
    "newTaxRates": [
      {
        "value": 0.08,
        "taxCategory": "STANDARD"
      }
    ]
  }
}

Scheduled Tax Rate Change Updated

Sent when an existing scheduled change record is modified before its activation date.

{
  "subject": "tax-management",
  "type": "scheduled_tax_rate",
  "objectId": "a2678204-e5b9-457b-affb-2c4a23689e6d",
  "eventDate": "2026-05-04T16:34:59Z",
  "vatRate": {
    "operation": "updated",
    "failed": false,
    "iso2CountryCode": "VG",
    "regionCode": "CA-SK-3",
    "startDate": 1777915807000,
    "newTaxRates": [
      {
        "value": 0.16,
        "taxCategory": "STATE",
        "taxName": "TEST REMOVE"
      }
    ]
  }
}

Scheduled Tax Rate Change Failed

Sent when the scheduled job could not apply the planned rate change at the activation time. The existing rate remains unchanged. You may need to re-create the scheduled change or apply the update manually.

{
  "subject": "tax-management",
  "type": "scheduled_tax_rate",
  "objectId": "a19667ce-ccae-4fba-9666-6ba09ec25748",
  "eventDate": "2026-05-01T00:00:00Z",
  "vatRate": {
    "operation": "updated",
    "failed": true,
    "iso2CountryCode": "FR",
    "startDate": 1777555858000,
    "newTaxRates": [
      {
        "value": 0.08,
        "taxCategory": "STANDARD"
      }
    ]
  }
}

Notes

• The vatRate.newTaxRates array contains the full set of rates for the given country/region in this operation, not a diff.
• For countries with multiple tax categories (e.g. federal and state), each category appears as a separate entry in newTaxRates.
• The system allows only one planned scheduled change per country/region tax object at any given time.
• When a scheduled change is applied at the planned time, the system sends a regular type=tax_rate / operation=updated notification — the same payload as a direct manual update, with no startDate field. There is no separate "applied" event for scheduled changes.
• The vatRate.failed=true pattern is the same for both tax_rate and scheduled_tax_rate notification types.