Invoices API

The Invoices API gives access to the sales documents of orders and projects: invoices, receipts and credit notes. Omnium creates these documents in order and return workflow steps, and external systems such as an ERP can add their own. Use the API to show a customer the receipts of an order in your webshop, to search documents, and to download a document as a PDF.

All endpoints are available at:

https://api.omnium.no/api/Invoices

The endpoints require an API user with read access to orders. Uploading a new invoice file with AddInvoice requires admin access to orders.

Endpoints

Paging

The list endpoints (/api/Invoices, /Orders/{orderId} and /Customers/{customerId}) take the query parameters page (default 1), pageSize (default 20, maximum 1000) and isPaid. The product of page and pageSize must stay below 20000. isPaid=false returns only documents with an outstanding amount above 0. isPaid=true returns only documents with an outstanding amount of 0 or less, receipts included. Invoices from the Create Invoice step have no outstanding amount set, so isPaid=true returns them too. Leave isPaid out to get all documents.

Search takes page and take in the request body. Both are required and must be greater than 0.

Invoices, receipts and credit notes

The same invoice model holds three kinds of documents:

Receipts

A receipt documents one shipment of an order. An order with several shipments has one receipt per shipment, so get all of them with GET /api/Invoices/Orders/{orderId}, or one with a search on shipmentId. On a receipt:

• shipmentId is the shipment it documents and orderId is the order
• lineItems are the delivered lines of the shipment, with the delivered quantity
• payments are the payments that paid the shipment, and together they equal amount
• amountOutstanding is 0, and invoiceDueDate is the same as invoiceDate
• kid is empty
• deliveryDate is the date the shipment was completed, or the issue date when the shipment has no completed date
• origin is Omnium

Credit notes

A credit note from a return lists the receipts that hold the returned lines in creditedInvoiceIds. The credit note PDF prints them as the documents it credits.

Invoice model

Get the receipts of an order

GET /api/Invoices/Orders/1004812 HTTP/1.1
Host: api.omnium.no
Authorization: Bearer YOUR_API_KEY

{
  "totalHits": 1,
  "result": [
    {
      "id": "K-10235",
      "invoiceNumber": "K-10235",
      "invoiceType": "Receipt",
      "invoiceDate": "2026-10-24T09:14:02Z",
      "invoiceDueDate": "2026-10-24T09:14:02Z",
      "deliveryDate": "2026-10-24T09:00:00Z",
      "orderId": "1004812",
      "shipmentId": "2",
      "customerId": "C123456",
      "customerName": "Kari Nordmann",
      "amount": 1298.0,
      "amountExcludingTax": 1038.4,
      "amountOutstanding": 0.0,
      "currency": "NOK",
      "isCreditNote": false,
      "origin": "Omnium",
      "storeId": "oslo-sentrum",
      "marketId": "NOR",
      "lineItems": [
        {
          "code": "JKT-FJORD-M",
          "displayName": "Regnjakke Fjord",
          "quantity": 1,
          "extendedPrice": 1199.0,
          "taxRate": 25.0
        }
      ],
      "payments": [
        {
          "paymentMethodName": "Klarna",
          "transactionType": "Capture",
          "amount": 1098.0
        },
        {
          "paymentMethodName": "GiftCard",
          "transactionType": "Sale",
          "amount": 200.0
        }
      ]
    }
  ]
}

Search invoices

Send the filters in the request body. Every filter you set must match.

This request finds the receipt of shipment 2 on order 1004812:

POST /api/Invoices/Search HTTP/1.1
Host: api.omnium.no
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
 
{
  "page": 1,
  "take": 10,
  "orderId": "1004812",
  "shipmentId": "2",
  "invoiceTypes": ["Receipt"]
}

Download a document as a PDF

GET /api/Invoices/GetAsPdf/{invoiceId} returns the document as application/pdf. A document that an ERP connector provides can come from that system. Omnium renders the documents it creates itself:

• A receipt has the title RECEIPT in the market language and a paid line that names the payment methods, such as Paid with Klarna, instead of the due date, KID and bank account. It also shows the delivery date, the shipment, the payments, the VAT rate of each line and the VAT per rate.
• A credit note shows the receipts it credits.

These documents use the standard layout unless the market has an invoice template.

Add or update an invoice

PUT /api/Invoices/UpdateInvoice takes an invoice in the model above. Without an id, Omnium adds a new invoice and takes the ID from the invoice number series of the invoice's market or tenant, or a GUID when no series is configured. With an id, the request replaces the stored invoice with that ID. The request fails with 400 Bad Request when customerId, orderId, projectId or storeId refers to something that does not exist, when marketId is not one of the tenant's markets, or when customerEmail is not a valid email address. The upload endpoints take the file content as the request body, with the file name in the fileName query parameter.

For the full interactive API reference, see the swagger documentation.