> **Description:** Comprehensive guide to the Sales API, covering authentication, endpoints, and integration steps for accounting partners.

# Sales API guide

This guide is for **accounting partners** using [accounting keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md#accounting-keys). It covers how to authenticate with and call the Sales API to retrieve order lines, VAT, and sales context for VM-number (also called *Vippsnummer*) and mPOS payments.

## Description

The Sales API exposes order-centric entries, where each entry represents **one financial transaction on an order** (capture or refund) enriched with sales context.

Each entry:

* Includes a stable order identifier (`reference`)
  * Same field name as `reference` in the Report API
* Includes a **transaction identifier** (`pspReference`)
  * Same field name as `pspReference` in the Report API
* Includes **sales amounts** (gross, net, VAT) in minor units **when available**
* Includes order lines, VAT, and categories
* Does **not** expose payment state or settlement correctness

## Integration steps

For a step-by-step walkthrough of authentication, discovering ledger IDs, and calling the Sales API endpoints, see the [Quick start guide](https://developer.vippsmobilepay.com/docs/APIs/sales-api/quick-start.md).

## Endpoints

| Endpoint | Description |
| -------- | ----------- |
| [Get ledgers](#get-ledgers) | (Report API) Returns the ledgers you have access to. |
| [Get sales report by feed](#get-sales-report-by-feed) | Continuous stream of sales data for a ledger |
| [Get sales events for a ledger on a specific date](#get-sales-events-for-a-ledger-on-a-specific-date) | Sales data for a specific date |
| [Get sales events by merchant reference](#get-sales-events-by-merchant-reference) | All captures and returns for a specific reference |
| [Get sales events by PSP reference](#get-sales-events-by-psp-reference) | A specific capture or return by PSP reference |

### Get ledgers

Partners use the Report API to discover which ledger IDs they have access to:

[`GET:/settlement/v1/ledgers`](https://developer.vippsmobilepay.com/redocusaurus/report-swagger-id.yaml)

### Get sales report by feed

Provides a continuous stream of sales data.

[`GET:/sales/report/v1/ledgers/{ledgerId}`](https://developer.vippsmobilepay.com/redocusaurus/sales-swagger-id.yaml)

Query parameters:

* **cursor**
  Example: `cursor=2ScAAAAAAAA=`
  * If not provided, the response starts from the first sale on the given `ledgerId`.
  * Each response includes a `cursor` indicating where the stream stopped.
  * Partners must persist the cursor and include it in subsequent requests to continue from the last checkpoint.

* **pageSize**
  Example: `pageSize=100`
  * Limits the number of rows returned per request (default: 100, max: 1000).
  * Used to control payload size and processing volume.
  * Partners may request fewer rows than the default by specifying `pageSize`.

Example request:

```bash
curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}?pageSize=100" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
```

### Get sales events for a ledger on a specific date

Returns sales data for a specific date.

[`GET:/sales/report/v1/ledgers/{ledgerId}/dates/{ledgerDate}`](https://developer.vippsmobilepay.com/redocusaurus/sales-swagger-id.yaml)

If the number of sales exceeds the response limit:

* The response includes:
  * `cursor`
  * `hasMore = true`
* Partners must repeat the request for the same date including the `cursor` to retrieve remaining records.

Query parameters:

* **cursor**
  Example: `cursor=2ScAAAAAAAA=`
  * If not provided, the response starts from the first sale on the given `ledgerId`.
  * Each response includes a checkpoint cursor.
  * Partners must store and reuse the cursor to continue retrieving remaining records.

* **pageSize**
  Example: `pageSize=100`
  * Limits the number of rows returned per request (default: 100, max: 1000).
  * Partners can request a smaller page size if desired.

Example request:

```bash
curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}/dates/2026-05-01" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
```

### Get sales events by merchant reference

Returns all captures and returns related to a specific reference.

[`GET:/sales/report/v1/ledgers/{ledgerId}/references/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/sales-swagger-id.yaml)

Example request:

```bash
curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}/references/{reference}" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
```

### Get sales events by PSP reference

Returns a specific capture or return using the PSP reference.

[`GET:/sales/report/v1/ledgers/{ledgerId}/psp-references/{pspReference}`](https://developer.vippsmobilepay.com/redocusaurus/sales-swagger-id.yaml)

Example request:

```bash
curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}/psp-references/{pspReference}" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
```

#### External payload shape

```json
{
  "items": [
      {
        "entryType": "capture",
        "time": "2026-01-19T12:45:00Z",
        "pspReference": "35054310398",
        "reference": "12494299492",
        "currency": "NOK",
        "paymentType": "CARD",
        "classification": {
            "solution": "MPOS",
            "salesCategory": null
          },
        "amounts": {
            "gross": 25000,
            "net": 20000,
            "vat": 5000
          },
        "lines": [
          {
            "lineId": "121772",
            "name": "Product A",
            "quantity": 2,
            "unitPriceGross": 12500,
            "unitPriceNet": 10000,
            "discountTotal": 0,
            "lineTotalGross": 25000,
            "lineTotalNet": 20000,
            "vatRate": 2500,
            "vatAmount": 5000,
            "category": "GOODS"
          }
        ],
        "customer": null,
        "completeness": {
            "hasLineItems": true,
            "hasVatBreakdown": true,
            "hasCustomerIdentity": false
          }
        }
  ],
  "cursor": "8gsAAAAAAAA=",
  "hasMore": true
}
```

##### Field semantics

**Identifiers**

* `reference`
  * Identifies the order / sale
  * Same field name as `reference` in the Report API (equals `orderId` in the ePayment API)
  * Stable across captures, refunds, and fees
* `pspReference`
  * Identifies one financial transaction
  * Same field name as `pspReference` in the Report API
  * Unique per capture or refund. `null` for payment methods without a PSP (e.g. cash)

**paymentType**

`CARD` | `CASH` | `WALLET`

**Amounts**

All monetary values are in minor units (e.g. øre for NOK).
"Gross" means including VAT. "Net" means excluding VAT.

**Line Items**

* `unitPriceGross` -- Gross unit price before discount (including VAT)
* `unitPriceNet` -- Net unit price before discount (excluding VAT)
* `discountTotal` -- Total discount for this line
* `lineTotalGross` -- Final gross line price after discount (including VAT)
* `lineTotalNet` -- Final net line price after discount (excluding VAT)
* `vatRate` -- VAT rate in basis points (e.g. 2500 = 25%)
* `vatAmount` -- VAT amount for this line

**Invariants**

* `unitPriceGross * quantity - discountTotal = lineTotalGross`
* `sum(lines[].lineTotalGross) = amounts.gross`
* `sum(lines[].vatAmount) = amounts.vat`

**Completeness Flags**

Completeness flags allow consumers to distinguish "not provided or not available" from "empty but known".

The `customer` field is reserved for future use and is always `null`.

**Report API mapping**

| Sales API field | Report API field | Meaning                    |
|-----------------|------------------|----------------------------|
| `reference`     | `reference`      | Identifies the order       |
| `pspReference`  | `pspReference`   | Identifies the transaction |

Accounting partners are expected to:

1. Fetch sales entries from the Sales API
2. Fetch transactions (funds + fees) from the Report API
3. Join on `reference` (order-level) or `pspReference` (transaction-level)

**Classification**

Each entry may include a `classification` object with the following fields:

* `solution` -- Identifies the Vipps MobilePay solution used for the sale:
  * `VARIABLE_AMOUNT` -- Open-amount VM-number payment. No order lines; sales category available when provided.
  * `SHOPPING_BASKET` -- VM-number Shopping Basket payment. Order lines, item names, quantities, and VAT per line when the merchant has added that data.
  * `MPOS` -- mPOS / Kassa sale (card, cash, or wallet at terminal).
* `salesCategory` -- Merchant-defined category for the sale (nullable). Primarily relevant for `VARIABLE_AMOUNT` payments where line items are absent.

**Shopping Basket VAT**

VAT data in `SHOPPING_BASKET` entries depends on what the merchant has entered. VAT is not mandatory for every line item, so integrations must handle missing or partial VAT data.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).