---
title: "Get invoice data"
method: GET
path: "/sales/invoice"
tags: ["Sales"]
---

# Get invoice data

`GET /sales/invoice`

## Request

- Base URL: `https://api.altera.co`
- URL: `https://api.altera.co/sales/invoice`
- Auth: API key in header `Authorization`

Retrieve data for a particular invoice available in the system

This endpoint may be used as a base for new invoice data that we wish to create based on a set of related invoices

If you wish to generate such object base you will need to provide both:
* `related` parameter, listing the related invoices
* `invoiceType` of the new invoice we wish to create

The return object will be a temporary invoice object you may further extend before saving it.

Missing, permanently deleted and other-company invoices return 404 NOT_FOUND with a generic message. Own soft-deleted invoices return 404 NOT_FOUND with "Invoice has been deleted" and no invoice data. This applies to ref and related lookups. For CORRECTION, rows come from the referenced document, without applying later corrections automatically. Reference the previous correction to use its stored after-correction state.

## Query parameters

- `ref` integer
- `related` unknown[]
  - unknown
- `invoiceType` 'SALES' | 'CORRECTION' | 'INTERIM_FINAL'

## Response `200`

OK

- object
  - `result` string
  - `data` object
    - `invoice` Invoice: Invoice model for objects returned from server
      - `modelType` string
      - `readOnly` boolean
      - `basicInformation` object
        - `invoiceId` integer, required
        - `invoiceType` 'SALES' | 'PRO_FORMA' | 'INTERIM' | 'INTERIM_FINAL' | 'CORRECTION', required
        - `invoiceFormat` string, required
        - `invoiceNumber` string
        - `year` integer, required
        - `month` integer, required
        - `invoiceNumberInPeriod` integer
        - `statusId` string
        - `isReceipt` boolean
        - `isRelated` boolean
        - `netPrice` integer
        - `grossPrice` number
        - `currency` string: Invoice currency stored as a three-letter code.
        - `exchangeRate` number
        - `vatPLN` number
        - `issueDate` string
        - `saleDate` string
        - `uploadDate` string
        - `relatedInvoicesIds` object[]
        - `priceTypeId` string
        - `language` 'pl' | 'en' | 'de' | 'es' | 'en_pl' | 'de_pl': Language of the invoice document: pl, en, de, es, en_pl or de_pl.
        - `isDeleted` union: Soft-deletion marker. Public GET excludes soft-deleted documents and returns 404 instead of their data.
          - boolean
          - 0 | 1
      - `contractor` object
        - `contractorName` string
        - `contractorId` integer
        - `taxIdentificationNumber` string
        - `country` string
        - `contractorType` string
        - `contractorRegion` string
        - `defaultCurrency` string
        - `city` string
        - `street` string
        - `houseNumber` string
        - `flatNumber` string
        - `postCode` string
        - `email` string
        - `phoneNumber` string
        - `areaNumber` string
      - `seller` object
        - `taxIdentificationNumber` string
        - `contractorName` string
      - `payments` object
        - `paymentMethod` string
        - `dueDate` string
        - `isSplitPayment` boolean
        - `isPaid` boolean
        - `paidAmount` integer
        - `bankAccountNumber` string
      - `ksef` object
        - `ksefId` string
        - `ksefSubmissionDate` string
        - `ksefStatus` 'ACCEPTED' | 'PENDING' | 'ERROR'
        - `ksefErrorMessage` string
        - `ksefRetryCount` integer
        - `ksefSourceXmlKey` string
      - `offlineMode` boolean
      - `offlineModeReason` string
      - `invoicePosition` object[]
        - `invoiceProductId` integer
        - `positionType` string
        - `productPosition` integer
        - `productCategory` string
        - `productCategoryId` integer
        - `productName` string
        - `unit` string
        - `unitNetPrice` integer
        - `unitGrossPrice` number
        - `quantity` integer
        - `discount` integer
        - `vat` string: VAT rate for this invoice line. np I and np II are distinct supported values and map to separate KSeF summary fields P_13_8 and P_13_9. The generic np value is retained for legacy invoices and maps to np I; use an explicit np I or np II value for new invoices.
        - `priceNet` integer
        - `netPrice` string
        - `vatAmt` number
        - `priceGross` number
        - `grossPrice` string
        - `gtu` string, nullable: Optional GTU classification for this invoice line. Use a string from 1 to 13, for example "2"; zero-padded values such as "02" and KSeF values such as "GTU_02" are also supported. KSeF export converts the numeric value to GTU_01 through GTU_13. Omit, pass null or an empty string when no GTU applies.
      - `vatExemptionReason` 'Zwolnienie podmiotowe z art. 113 ust. 1 i 9' | 'Zwolnienie przedmiotowe z art. 43 ust. 1' | 'Zwolnienie przedmiotowe z art. 82 ust. 3', nullable: Legal basis for VAT exemption selected for an invoice containing a line with the `zw` VAT rate.
      - `vatExemptionReasonDetailed` string, nullable: Optional detailed wording shown on the invoice below the selected VAT exemption legal basis.
      - `additionalParties` InvoiceAdditionalParty[]: Additional parties, including a separate recipient (Podmiot3). Each entry is a snapshot; contractor continues to identify the buyer.
        - `semanticRole` 'FACTOR' | 'RECIPIENT' | 'BRANCH' | 'ORIGINAL_ENTITY' | 'ADDITIONAL_BUYER' | 'ISSUER' | 'PAYEE' | 'JST_ISSUER' | 'JST_RECIPIENT' | 'VAT_GROUP_ISSUER' | 'VAT_GROUP_RECIPIENT' | 'EMPLOYEE' | 'OTHER': Role of this additional party (Podmiot3). Use RECIPIENT for a separate invoice recipient. JST_RECIPIENT has distinct KSeF semantics; do not select it solely because the recipient is a school.
        - `internalId` string, nullable: Optional five-digit suffix, preserving leading zeros. KSeF export requires a Polish 10-digit NIP and Polish country and emits IDWew as NIP-internalId, for example 5260250274-00123.
        - `contractorType` 'COMPANY' | 'PRIVATE_PERSON'
        - `contractorRegion` 'POLAND' | 'EU' | 'OUTSIDE_OF_EU'
        - `contractorName` string
        - `taxIdentificationNumber` string
        - `city` string
        - `street` string
        - `houseNumber` string
        - `flatNumber` string
        - `postCode` string
        - `email` string
        - `phoneNumber` string
        - `areaNumber` string
        - `roleOther` string: Description of the role when semanticRole is OTHER; exported as OpisRoli with RolaInna=1.
        - `extraInfo` string
        - `country` string
        - `tinCountry` string
        - `defaultCurrency` string
        - `partyOrder` integer: Optional display order; defaults to the zero-based position in additionalParties.
        - `sharePercent` number: Optional share percentage for the additional party.
    - `relatedInvoices` Invoice[]
      - `modelType` string
      - `readOnly` boolean
      - `basicInformation` object
        - `invoiceId` integer, required
        - `invoiceType` 'SALES' | 'PRO_FORMA' | 'INTERIM' | 'INTERIM_FINAL' | 'CORRECTION', required
        - `invoiceFormat` string, required
        - `invoiceNumber` string
        - `year` integer, required
        - `month` integer, required
        - `invoiceNumberInPeriod` integer
        - `statusId` string
        - `isReceipt` boolean
        - `isRelated` boolean
        - `netPrice` integer
        - `grossPrice` number
        - `currency` string: Invoice currency stored as a three-letter code.
        - `exchangeRate` number
        - `vatPLN` number
        - `issueDate` string
        - `saleDate` string
        - `uploadDate` string
        - `relatedInvoicesIds` object[]
        - `priceTypeId` string
        - `language` 'pl' | 'en' | 'de' | 'es' | 'en_pl' | 'de_pl': Language of the invoice document: pl, en, de, es, en_pl or de_pl.
        - `isDeleted` union: Soft-deletion marker. Public GET excludes soft-deleted documents and returns 404 instead of their data.
          - boolean
          - 0 | 1
      - `contractor` object
        - `contractorName` string
        - `contractorId` integer
        - `taxIdentificationNumber` string
        - `country` string
        - `contractorType` string
        - `contractorRegion` string
        - `defaultCurrency` string
        - `city` string
        - `street` string
        - `houseNumber` string
        - `flatNumber` string
        - `postCode` string
        - `email` string
        - `phoneNumber` string
        - `areaNumber` string
      - `seller` object
        - `taxIdentificationNumber` string
        - `contractorName` string
      - `payments` object
        - `paymentMethod` string
        - `dueDate` string
        - `isSplitPayment` boolean
        - `isPaid` boolean
        - `paidAmount` integer
        - `bankAccountNumber` string
      - `ksef` object
        - `ksefId` string
        - `ksefSubmissionDate` string
        - `ksefStatus` 'ACCEPTED' | 'PENDING' | 'ERROR'
        - `ksefErrorMessage` string
        - `ksefRetryCount` integer
        - `ksefSourceXmlKey` string
      - `offlineMode` boolean
      - `offlineModeReason` string
      - `invoicePosition` object[]
        - `invoiceProductId` integer
        - `positionType` string
        - `productPosition` integer
        - `productCategory` string
        - `productCategoryId` integer
        - `productName` string
        - `unit` string
        - `unitNetPrice` integer
        - `unitGrossPrice` number
        - `quantity` integer
        - `discount` integer
        - `vat` string: VAT rate for this invoice line. np I and np II are distinct supported values and map to separate KSeF summary fields P_13_8 and P_13_9. The generic np value is retained for legacy invoices and maps to np I; use an explicit np I or np II value for new invoices.
        - `priceNet` integer
        - `netPrice` string
        - `vatAmt` number
        - `priceGross` number
        - `grossPrice` string
        - `gtu` string, nullable: Optional GTU classification for this invoice line. Use a string from 1 to 13, for example "2"; zero-padded values such as "02" and KSeF values such as "GTU_02" are also supported. KSeF export converts the numeric value to GTU_01 through GTU_13. Omit, pass null or an empty string when no GTU applies.
      - `vatExemptionReason` 'Zwolnienie podmiotowe z art. 113 ust. 1 i 9' | 'Zwolnienie przedmiotowe z art. 43 ust. 1' | 'Zwolnienie przedmiotowe z art. 82 ust. 3', nullable: Legal basis for VAT exemption selected for an invoice containing a line with the `zw` VAT rate.
      - `vatExemptionReasonDetailed` string, nullable: Optional detailed wording shown on the invoice below the selected VAT exemption legal basis.
      - `additionalParties` InvoiceAdditionalParty[]: Additional parties, including a separate recipient (Podmiot3). Each entry is a snapshot; contractor continues to identify the buyer.
        - `semanticRole` 'FACTOR' | 'RECIPIENT' | 'BRANCH' | 'ORIGINAL_ENTITY' | 'ADDITIONAL_BUYER' | 'ISSUER' | 'PAYEE' | 'JST_ISSUER' | 'JST_RECIPIENT' | 'VAT_GROUP_ISSUER' | 'VAT_GROUP_RECIPIENT' | 'EMPLOYEE' | 'OTHER': Role of this additional party (Podmiot3). Use RECIPIENT for a separate invoice recipient. JST_RECIPIENT has distinct KSeF semantics; do not select it solely because the recipient is a school.
        - `internalId` string, nullable: Optional five-digit suffix, preserving leading zeros. KSeF export requires a Polish 10-digit NIP and Polish country and emits IDWew as NIP-internalId, for example 5260250274-00123.
        - `contractorType` 'COMPANY' | 'PRIVATE_PERSON'
        - `contractorRegion` 'POLAND' | 'EU' | 'OUTSIDE_OF_EU'
        - `contractorName` string
        - `taxIdentificationNumber` string
        - `city` string
        - `street` string
        - `houseNumber` string
        - `flatNumber` string
        - `postCode` string
        - `email` string
        - `phoneNumber` string
        - `areaNumber` string
        - `roleOther` string: Description of the role when semanticRole is OTHER; exported as OpisRoli with RolaInna=1.
        - `extraInfo` string
        - `country` string
        - `tinCountry` string
        - `defaultCurrency` string
        - `partyOrder` integer: Optional display order; defaults to the zero-based position in additionalParties.
        - `sharePercent` number: Optional share percentage for the additional party.
    - `defaults` object

## Other responses

- `400`: Bad Request
- `401`: KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.
- `403`: Gateway authorization failure. Invalid keys or companies without OpenAPI access may return {"message":"Forbidden"}.
- `404`: NOT_FOUND. Generic for missing, permanently deleted or other-company invoices; "Invoice has been deleted" only for a soft-deleted invoice owned by the key company.

## Changes

- **2026-10-12** `45544bcb4e8a`: 2 breaking, 8 info
  - the response property `data/invoice/invoicePosition/items/gtu` became nullable for the status `200`
  - the response property `data/relatedInvoices/items/invoicePosition/items/gtu` became nullable for the status `200`
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - …6 more
- **2026-09-17** `901474a58f63`: 1 info
  - added the optional property `validationErrors` to the response with the `400` status
- **2026-09-14** `f1d82ac65775`: 6 info
  - added the optional property `data/invoice/additionalParties` to the response with the `200` status
  - added the optional property `data/invoice/vatExemptionReason` to the response with the `200` status
  - added the optional property `data/invoice/vatExemptionReasonDetailed` to the response with the `200` status
  - added the optional property `data/relatedInvoices/items/additionalParties` to the response with the `200` status
  - …2 more
- **2026-02-09** `39a4dd6ca527`: 6 info
  - added the optional property `data/invoice/ksef` to the response with the `200` status
  - added the optional property `data/invoice/offlineMode` to the response with the `200` status
  - added the optional property `data/invoice/offlineModeReason` to the response with the `200` status
  - added the optional property `data/relatedInvoices/items/ksef` to the response with the `200` status
  - …2 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/altera-co/apis/altera-api/changes/sales/invoice/get.md)

---

[API](https://skmtc.dev/altera-co/apis/altera-api.md) - [All operations](https://skmtc.dev/altera-co/apis/altera-api/llms.txt) - [OpenAPI document](https://skmtc.dev/altera-co/apis/altera-api/revisions/45544bcb4e8a?raw)