Committing Calculations

Once a calculation results in a sale, you can update the status of a calculation to committed by sending an HTTP POST to https://api.fonoa.com/tax/calculations/<uuid>/commit with a body containing:

{
  "timestamp": "2026-01-15T20:48:59.000Z",
}

On receipt, the API will respond with an HTTP 202 Accepted, and an empty response body.

Committing a calculation will update its status and include it for revenue tracking if applicable.

Listen for a webhook

Once a commit has been processed, a webhook notification will be sent to the URL set during the onboarding process.

Webhooks have the same payload across the Fonoa platform. More info about it can be found here. Here’s an example payload you will receive from us.

Content-Type: application/json
X-Fonoa-Hmac-SHA256: SIGNATURE (See webhooks documentation)
 
{
  "webhook_id": "875bd24499d303cbe8afb3db1987d8aa522d63bb",
  "event_type": "tax.calculation_committed",
  "delivered_at": "2066-01-02T15:04:05Z",
  "resource_id": "1010b4d8-9361-4a7e-98cc-9419dbba695c",
  "resource_url": "https://api.fonoa.com/tax/v2/calculations/1010b4d8-9361-4a7e-98cc-9419dbba695c"
}

The resource_id field will contain the id of the calculation.

The calculation can be accessed using the GET endpoint in resource_url.

⚠️
Do not use the resource_id to construct URLs. Always use the resource_url.

If the commit was successful, the status of the calculation will now have changed to committed:

{
    "data": {
        "uuid": "1010b4d8-9361-4a7e-98cc-9419dbba695c",
        "status": "committed",
        "input": {
            "supplier": {
                "taxable": true,
                "country": "gb"
            },
            "customer": {
                "taxable": false,
                "country": "nl"
            },
            "transaction": {
                "price_includes_tax": false,
                "date": "2026-01-14T20:48:59.000Z",
                "items": [
                    {
                        "id": "34db79d1-24bf-4c22-863e-1f7832f24be3",
                        "unit_price": 100,
                        "tax_category_code": "fs_0503010000",
                        "quantity": 1
                    }
                ]
            }
        },
        "output": {
            "id": "1010b4d8-9361-4a7e-98cc-9419dbba695c",
            "result": {
                "total_gross": 121,
                "total_net": 100,
                "total_indirect_tax_amount": 21,
                "items": [
                    {
                        "id": "34db79d1-24bf-4c22-863e-1f7832f24be3",
                        "gross_amount": 121,
                        "net_amount": 100,
                        "indirect_tax_amount": 21,
                        "effective_indirect_tax_rate": 0.21,
                        "tax_breakdown": [
                            {
                                "country": "nl",
                                "country_name": "Netherlands",
                                "rate_class": "s",
                                "tax_level": "federal",
                                "name": "BTW",
                                "rate": 0.21,
                                "amount": 21
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Reverting Calculations

A committed calculation can be reverted by sending an HTTP POST to https://api.fonoa.com/tax/calculations/<uuid>/revert with a body containing:

{
    "timestamp": "2026-01-16T20:48:59.000Z",
}

On receipt, the API will response with an HTTP 202 Accepted and an empty response body.

Reverting a calculation will change its status to reverted and remove it from revenue tracking if previously included

Listen for a webhook

Similar to a commit, a webhook notification will be sent to the URL configured during onboarding after the revert has been processed:

Content-Type: application/json
X-Fonoa-Hmac-SHA256: SIGNATURE (See webhooks documentation)
 
{
  "webhook_id": "875bd24499d303cbe8afb3db1987d8aa522d63bb",
  "event_type": "tax.calculation_reverted",
  "delivered_at": "2066-01-02T15:04:05Z",
  "resource_id": "1010b4d8-9361-4a7e-98cc-9419dbba695c",
  "resource_url": "https://api.fonoa.com/tax/v2/calculations/1010b4d8-9361-4a7e-98cc-9419dbba695c"
}

Errors

If there is an error during the processing of a commit or a revert, a webhook notification will be sent to the URL configured during onboarding:

Content-Type: application/json
X-Fonoa-Hmac-SHA256: SIGNATURE (See webhooks documentation)
 
{
  "webhook_id": "875bd24499d303cbe8afb3db1987d8aa522d63bb",
  "event_type": "tax.calculation_commit_failed",
  "delivered_at": "2066-01-02T15:04:05Z",
  "resource_id": "1010b4d8-9361-4a7e-98cc-9419dbba695c",
  "resource_url": "https://api.fonoa.com/tax/v2/calculations/1010b4d8-9361-4a7e-98cc-9419dbba695c",
  "errors": [
    {
      "code": "INVALID_COMMIT_TIMESTAMP",
      "message": "The commit timestamp has to be on or after the transaction.date of the calculation"
    }
  ]
}

An errors field indicates that the commit/revert was unsuccessfully processed, and will have to be retried after fixing the issue

How updates are processed

All updates to a calculation are processed in the order of the timestamp sent in the body of the POST, regardless of the order in which they are submitted.

Can the client submit multiple commits/reverts?

Yes. All commits will be accepted and applied in the order of timestamp.

Note: Only the first commit will include the calculation in revenue tracking; subsequent commits will have no effect on revenue.

Can a reverted calculation be committed again?

Yes, reverted is not a final status. Submitting a commit for a reverted calculation will change its status back to committed

How are two updates with the same timestamp processed?

Updates with identical timestamp values in the body will be processed in the order that the client submitted them

Can a calculation be marked as committed during the initial submission?

Yes. Clients can set the transaction.commit field to true in the request body of the HTTP POST to https://api.fonoa.com/tax/v2/calculations.

This will save the calculation with the status of committed and include the calculation in revenue tracking