---
title: "Save and calculate VAT figures"
method: PUT
path: "/api/v1/me/tax/vat/filings/{filingId}"
tags: ["Quarterly VAT"]
---

# Save and calculate VAT figures

`PUT /api/v1/me/tax/vat/filings/{filingId}`

## Request

- Base URL: `https://portal.eprospera.com`
- URL: `https://portal.eprospera.com/api/v1/me/tax/vat/filings/{filingId}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://portal.eprospera.com/api/oauth/authorize`
    - Token URL: `https://portal.eprospera.com/api/oauth/token` scopes: `eprospera:person.tax.vat.write`
  - OAuth 2
    - Authorization code: `https://portal.eprospera.com/api/oauth/authorize`
    - Token URL: `https://portal.eprospera.com/api/oauth/token` scopes: `eprospera:entity.tax.vat.write`
- TypeScript: <https://skmtc.dev/eprospera/apis/e-pro-spera-api/docs/api/v1/me/tax/vat/filings/:filingId/put.ts> (a function with typed inputs; its response is checked against the schema)

Replace all reported figures using decimal strings and the latest revision. Stale revisions return 412. Submitted filings and processed invoices cannot be edited; an unprocessed invoice is voided before recalculation. A successful write returns a new revision. After a timeout, read the filing before retrying.

Account deactivation revokes personal API keys, including Agent Keys, and OAuth authorizations. Account reactivation requires new API keys, including new Agent Keys, and consent; previously issued credentials remain invalid.

## Path parameters

- `filingId` string, uuid, required

## Request body

- object
  - `revision` string, required
  - `currency` 'usd', required
  - `accountingMethod` 'cash' | 'accrual', required
  - `grossIncome` string, required: Non-negative USD decimal string with at most 12 integer digits and 2 decimal places.
  - `taxCredit` string, required: Non-negative USD decimal string with at most 12 integer digits and 2 decimal places.
  - `taxWithheld` string, required: Non-negative USD decimal string with at most 12 integer digits and 2 decimal places.

## Response `200`

Saved draft and calculated liability.

- object
  - `data` VatFiling, required
    - `id` string, uuid, required
    - `subject` object, required
      - `type` 'natural_person' | 'legal_entity', required
      - `id` string, uuid, required
      - `name` string, required
      - `residentPermitNumber` string, nullable, required: 14-digit Resident Permit Number.
    - `period` object, required
      - `year` integer, required
      - `quarter` integer, required
    - `status` 'draft' | 'submitted', required
    - `revision` string, required
    - `currency` 'usd', required
    - `accountingMethod` string, nullable, required
    - `reported` object, required
      - `grossIncome` string, nullable, required
      - `taxCredit` string, nullable, required
      - `taxWithheld` string, nullable, required
    - `taxLiability` string, nullable, required
    - `readyToSubmit` boolean, required: Figures and payment are ready; permissions, period eligibility, and declaration are rechecked on submission.
    - `creditReviewRequired` boolean, required
    - `creditReviewStatus` string, nullable, required
    - `paymentRequired` boolean, required
    - `invoice` object, nullable, required
      - `id` string, uuid, required
      - `status` string, required
    - `submittedAt` string, date-time, nullable, required
    - `links` object, required
      - `portal` string, required
      - `assessment` string, nullable, required

## Other responses

- `400`: Invalid request, incomplete figures, or payment not satisfied.
- `401`: Missing, expired, or revoked authorization.
- `403`: VAT write scope is missing or no longer allowed for this OAuth client.
- `404`: Taxpayer or filing not accessible through this authorization.
- `409`: Period unavailable, multiple drafts, unsupported filing, missing RPN, or concurrent change. Refresh before retrying.
- `412`: Stale revision or unmet tax-credit approval. Read the filing, review current figures, and resolve any required credit review before retrying.
- `429`: Rate limit exceeded: 60 requests per minute per client and user.
- `500`: Internal server error.

## Changes

- **2026-10-19** `271098460337`: 2 info
  - the security scope `eprospera:person.tax.vat.write` was added to the endpoint's security scheme `oauth2`
  - the security scope `eprospera:entity.tax.vat.write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-14** `f68c9a4d8ec8`: 2 info
  - the security scope `eprospera:person.tax.vat.write` was added to the endpoint's security scheme `oauth2`
  - the security scope `eprospera:entity.tax.vat.write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-14** `7d4bb4aede91`: 2 info
  - the security scope `eprospera:person.tax.vat.write` was added to the endpoint's security scheme `oauth2`
  - the security scope `eprospera:entity.tax.vat.write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-08** `d6ef6f72daa1`: 2 info
  - the security scope `eprospera:person.tax.vat.write` was added to the endpoint's security scheme `oauth2`
  - the security scope `eprospera:entity.tax.vat.write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-06** `7254e19987ac`: 2 info
  - the security scope `eprospera:person.tax.vat.write` was added to the endpoint's security scheme `oauth2`
  - the security scope `eprospera:entity.tax.vat.write` was removed from the endpoint's security scheme `oauth2`

[Operation history](https://skmtc.dev/eprospera/apis/e-pro-spera-api/changes/api/v1/me/tax/vat/filings/:filingId/put.md)

---

[API](https://skmtc.dev/eprospera/apis/e-pro-spera-api.md) - [All operations](https://skmtc.dev/eprospera/apis/e-pro-spera-api/llms.txt) - [OpenAPI document](https://skmtc.dev/eprospera/apis/e-pro-spera-api/revisions/271098460337?raw)