VAT Returns
VAT returns (MVA-melding) allow you to generate VAT reports and submit VAT returns to the Norwegian tax authorities. The API supports generating reports in JSON and PDF format, listing past submissions, and creating new submissions.
Endpoints
Get VAT Report
GET /api/v2/vat-return/report
Generates a VAT report for a given period showing tax code breakdowns with debit/credit amounts.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | ID of the client account |
| from_date | date | Yes | Start date in YYYY-MM-DD format |
| to_date | date | Yes | End date in YYYY-MM-DD format |
Content Negotiation
| Accept Header | Response |
|---|---|
application/json |
JSON report data |
application/pdf |
PDF file download |
JSON Response
The endpoint returns a bare JSON array, not wrapped in a data envelope. tax_code always includes its tax_account and acquisition_tax_account relations (see Tax Codes).
[
{
"tax_code": {
"id": 3,
"code": "3",
"tax_rate": "25.00",
"category": "input",
"tax_account_id": 12,
"acquisition_tax_account_id": 34,
"active_from": "2023-01-01",
"active_to": null,
"compensation": false,
"description": "Purchases 25% VAT",
"tax_account": {
"id": 12,
"account_code": "2700",
"description": "Output VAT",
"mandatory_dimensions": []
},
"acquisition_tax_account": {
"id": 34,
"account_code": "2710",
"description": "Input VAT",
"mandatory_dimensions": []
}
},
"base_debit_amount": 40000.00,
"base_credit_amount": 0.00,
"tax_debit_amount": 10000.00,
"tax_credit_amount": 0.00,
"posted_tax_debit_amount": 10000.00,
"posted_tax_credit_amount": 0.00,
"reconciliation_debit_amount": 0.00,
"reconciliation_credit_amount": 0.00,
"reportable_tax_amount": -10000.00,
"reportable_acquisition_tax_amount": 0.00,
"discrepancy_note": null
}
]
List Submissions
GET /api/v2/vat-return/submissions
Retrieves a paginated list of VAT return submissions.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer or comma/semicolon/space-separated list | No | Filter by client account(s). Defaults to every client account the caller can access |
| from_date | date | No | Filter submissions from this date |
| to_date | date | No | Filter submissions to this date |
| order_by | string | No | Sort field |
| page | integer | No | Page number (default: 1) |
| page_size | integer | No | Items per page (default: 100) |
Response
{
"data": [
{
"id": 1,
"created_at": "2024-03-15T10:00:00Z",
"created_by_id": 7,
"client_account_id": 7,
"from_date": "2024-01-01",
"to_date": "2024-02-28",
"settlement_voucher_id": 123,
"settlement_journal_entry_id": 456,
"payment_voucher_id": 789,
"payment_document_id": 101,
"return_content": "...",
"message_content": "...",
"status": "SUBMITTED"
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 100,
"records": 1
}
}
Submit VAT Return
POST /api/v2/vat-return/submissions
Submits a VAT return for a specified period.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | ID of the client account |
| from_date | date | Yes | Start date of the VAT period |
| to_date | date | Yes | End date of the VAT period |
| ignore_warnings | boolean | No | Ignore validation warnings (default: true) |
Response
Returns the created VAT return submission with status 200 OK.
Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | Unique identifier (read-only) |
| created_at | datetime | Creation timestamp (read-only) |
| created_by_id | integer | ID of the user who created the submission (read-only) |
| client_account_id | integer | ID of the client account |
| from_date | date | Start date of the VAT period |
| to_date | date | End date of the VAT period |
| settlement_voucher_id | integer | ID of the settlement voucher |
| settlement_journal_entry_id | integer | ID of the settlement journal entry |
| payment_voucher_id | integer | ID of the payment voucher |
| payment_document_id | integer | ID of the payment document |
| return_content | string | XML content of the submitted return |
| message_content | string | Response message from tax authority |
| status | string | Submission status: SUBMITTED, REJECTED, APPROVED, PAID, or CANCELLED |
Relationships
| Relationship | Type | Description |
|---|---|---|
| created_by | User | The user who created the submission |
Error Responses
Errors use the standard error envelope. Branch on code, not on
message. In addition to the common codes, the VAT
return endpoints return:
| Code | HTTP status | When |
|---|---|---|
vat_return.missing_client_account_id |
400 | client_account_id is missing on GET /vat-return/report or POST /vat-return/submissions |
vat_return.missing_period |
400 | from_date or to_date is missing |
vat_return.no_default_payment_account |
400 | The client account has no default payment bank account, which the settlement payment document requires |
vat_return.validation_failed |
400 | Skatteetaten rejected the return; details.reasons lists the validation messages |
vat_return.access_denied |
403 | A requested client_account_id is outside your eligible client accounts |
id_porten.not_connected |
403 | The user is not signed in with ID-porten, which Skatteetaten’s validation of the return requires |
altinn.not_connected |
403 | The user is not signed in to Altinn, which submitting the return requires |
common.not_acceptable |
406 | GET /vat-return/report was asked for a representation other than JSON or PDF |
Example Error Response
{
"error": {
"code": "vat_return.missing_period",
"message": "Missing from_date or to_date",
"request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}