Sign in

v1

latestOpenAPI 3.0.02026-07-2455104.8 MB
ProformaInvoice

🔒 List proforma invoices V3

This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.

This endpoint requires the following scopes: proformaInvoice:read.

Paginated list of proforma invoices.

get/api/v3/proformaInvoices

Query parameters

key'id' | 'documentNumber' | 'documentDate' | 'writeProtection' | 'address.id' | 'project.id' | 'tags' | 'tags.id' | 'language' | 'bodyIntroduction' | 'bodyOutroduction' | 'project.abbreviation' | 'internalDesignation' | 'vatId' | 'deliveryTerms' | 'internalComment' | 'isDocumentSent' | 'editor.id' | 'createdAt' | 'updatedAt' | 'documentAddress.name' | 'documentAddress.title' | 'documentAddress.contactPerson' | 'documentAddress.department' | 'documentAddress.subDepartment' | 'documentAddress.addressSupplement' | 'documentAddress.street' | 'documentAddress.zipCode' | 'documentAddress.city' | 'documentAddress.state' | 'documentAddress.country' | 'documentAddress.gln' | 'documentAddress.email' | 'documentAddress.phone' | 'documentAddress.fax' | 'financials.paymentMethod.id' | 'financials.tax.disableTaxNotice' | 'financials.tax.taxRates.standard' | 'financials.tax.taxRates.reduced' | 'financials.tax.taxation' | 'totals.net.amount' | 'totals.net.currency' | 'financials.paymentTerms.paymentTargetDays' | 'financials.paymentTerms.paymentTargetDiscount' | 'financials.paymentTerms.paymentTargetDiscountDays' | 'sales.id' | 'salesOrder.id' | 'lineItems.product.id' | 'lineItems.number' | 'status'
op'equals' | 'notEquals' | 'in' | 'notIn' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'lessThan' | 'lessThanOrEquals' | 'greaterThan' | 'greaterThanOrEquals' | 'isNull' | 'isNotNull'

operator

The filter parameter is used to filter the results of the given endpoint.

Supported filter operators by key:

id: equals, notEquals, in, notIn

documentNumber: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentDate: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

writeProtection: equals, notEquals

address.id: equals, notEquals, in, notIn

project.id: equals, notEquals, in, notIn

tags: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

tags.id: equals, notEquals, in, notIn

language: equals, notEquals, in, notIn

bodyIntroduction: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

bodyOutroduction: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

project.abbreviation: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

internalDesignation: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

vatId: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

deliveryTerms: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

internalComment: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

isDocumentSent: equals, notEquals

editor.id: equals, notEquals, in, notIn

createdAt: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals, isNull, isNotNull

updatedAt: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals, isNull, isNotNull

documentAddress.name: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.title: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.contactPerson: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.department: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.subDepartment: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.addressSupplement: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.street: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.zipCode: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.city: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.state: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.country: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.gln: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.email: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.phone: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

documentAddress.fax: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

financials.paymentMethod.id: equals, notEquals, in, notIn

financials.tax.disableTaxNotice: equals, notEquals

financials.tax.taxRates.standard: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

financials.tax.taxRates.reduced: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

financials.tax.taxation: equals, notEquals, in, notIn

totals.net.amount: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

totals.net.currency: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

financials.paymentTerms.paymentTargetDays: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

financials.paymentTerms.paymentTargetDiscount: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

financials.paymentTerms.paymentTargetDiscountDays: equals, notEquals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals

sales.id: equals, notEquals, in, notIn

salesOrder.id: equals, notEquals, in, notIn

lineItems.product.id: equals, notEquals, in, notIn

lineItems.number: equals, notEquals, in, notIn, contains, notContains, startsWith, endsWith

status: equals, notEquals, in, notIn

sortstring[]

Sort via id, -id, documentNumber, -documentNumber, documentDate, -documentDate, customerNumber, -customerNumber, documentAddress.country, -documentAddress.country, project.id, -project.id, createdAt, -createdAt, updatedAt and -updatedAt. Default sort is id

searchstring

Full-text-style search across predefined columns.

includestring[]
perPageinteger
Example:15

Number of items per page. Default: 15, Max: 1000

pageinteger
Example:1

Page number. Only used with simple and table pagination.

cursorstring
Example:eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

The cursor to use for the paginated call. Only used with cursor pagination. Not compatible with page parameter

Headers

x-pagination'simple' | 'table' | 'cursor'
Example:simple

Controls the pagination format. Available types: simple, table, cursor. Defaults to 'simple' if not specified.

Response

Paginated list of proforma invoices.

OR
OR

Example response

{
  "data": [
    {
      "id": "1",
      "documentNumber": "I-12343",
      "documentDate": "2023-10-01",
      "customerNumber": "CUST-54321",
      "address": {
        "id": "42",
        "createdAt": "2025-03-15T09:27:00+01:00",
        "updatedAt": "2025-10-20T14:45:12+01:00"
      },
      "project": {
        "id": "54",
        "name": "Standard Project",
        "abbreviation": "STANDARD"
      },
      "tags": [
        {
          "id": "4",
          "title": "important"
        }
      ],
      "documentAddress": {
        "name": "John",
        "type": "mr",
        "title": "Ms.",
        "contactPerson": "Laura Schneider",
        "department": "Research & Development",
        "subDepartment": "CAI Lab",
        "addressSupplement": "Gebäude B, 4. Etage",
        "street": "Fuggerstraße 11",
        "zipCode": "86150",
        "city": "Augsburg",
        "state": "BY",
        "country": "DE",
        "salutation": "Sehr geehrte Damen und Herren",
        "gln": "1234567890123",
        "email": "alice@example.com",
        "phone": "+1-234-567-8900",
        "fax": "+1-234-567-8901",
        "mobile": "+1-234-567-8902"
      },
      "internalDesignation": "FB-3860-L",
      "language": "de",
      "bodyIntroduction": "Dear customer, we are pleased to send you the following invoice.",
      "bodyOutroduction": "Thank you for your business.",
      "vatId": "DE123456789",
      "deliveryTerms": "DDP",
      "internalComment": "This is an internal comment.",
      "editor": {
        "id": "4"
      },
      "activity": [
        {
          "message": "Invoice released",
          "causer": "John Doe",
          "causedAt": "2023-01-01T00:00:00Z"
        }
      ],
      "customFields": [
        {
          "key": "customer_category",
          "value": "Premium",
          "label": "Customer Category"
        },
        {
          "key": "priority_level",
          "value": "High",
          "label": "Priority Level"
        }
      ],
      "updatedAt": "2023-10-01T12:00:00Z",
      "createdAt": "2023-10-01T12:00:00Z",
      "financials": {
        "paymentMethod": {
          "id": "1"
        },
        "paymentTerms": {
          "paymentTargetDays": 30,
          "paymentTargetDiscount": 2.5,
          "paymentTargetDiscountDays": 10
        },
        "tax": {
          "taxation": "domestic",
          "taxRates": {
            "standard": 19,
            "reduced": 7
          }
        },
        "currency": "EUR",
        "exchangeRate": 1.0875
      },
      "totals": {
        "net": {
          "amount": "13.37",
          "currency": "EUR"
        },
        "gross": {
          "amount": "13.37",
          "currency": "EUR"
        },
        "contributionMargin": 42
      },
      "salesOrder": {
        "id": "13"
      },
      "customerOrderNumber": "PO-12345",
      "deliveryDate": "2023-10-15",
      "deviatingShipToAddress": {
        "name": "John",
        "type": "mr",
        "title": "Ms.",
        "contactPerson": "Laura Schneider",
        "department": "Research & Development",
        "subDepartment": "CAI Lab",
        "addressSupplement": "Gebäude B, 4. Etage",
        "street": "Fuggerstraße 11",
        "zipCode": "86150",
        "city": "Augsburg",
        "state": "BY",
        "country": "DE",
        "salutation": "Sehr geehrte Damen und Herren",
        "gln": "1234567890123",
        "email": "alice@example.com",
        "phone": "+1-234-567-8900",
        "fax": "+1-234-567-8901",
        "mobile": "+1-234-567-8902"
      },
      "deviatingCustomsToAddress": {
        "name": "John",
        "type": "mr",
        "title": "Ms.",
        "contactPerson": "Laura Schneider",
        "department": "Research & Development",
        "subDepartment": "CAI Lab",
        "addressSupplement": "Gebäude B, 4. Etage",
        "street": "Fuggerstraße 11",
        "zipCode": "86150",
        "city": "Augsburg",
        "state": "BY",
        "country": "DE",
        "salutation": "Sehr geehrte Damen und Herren",
        "gln": "1234567890123",
        "email": "alice@example.com",
        "phone": "+1-234-567-8900",
        "fax": "+1-234-567-8901",
        "mobile": "+1-234-567-8902"
      },
      "customsInformation": "Goods shipped from Germany. Please contact us for any questions regarding customs clearance.",
      "addCustomsInformation": true,
      "lineItems": [
        {
          "type": "product",
          "id": "1",
          "number": "2462-SK-D",
          "name": "Strawberry Jam",
          "description": "Delicious strawberry jam made from fresh strawberries.",
          "quantity": 2,
          "product": {
            "createdAt": "2025-03-15T09:27:00+01:00",
            "updatedAt": "2025-10-20T14:45:12+01:00"
          },
          "customFields": [
            {
              "key": "customer_category",
              "value": "Premium",
              "label": "Customer Category"
            },
            {
              "key": "priority_level",
              "value": "High",
              "label": "Priority Level"
            }
          ],
          "unit": "kg",
          "packagingUnit": "box",
          "internalComment": "This is an internal comment.",
          "customerProductNumber": "CUS-10077",
          "order": 5,
          "updatedAt": "2023-10-01T12:00:00Z",
          "createdAt": "2023-10-01T12:00:00Z",
          "salesOrderLineItem": {
            "id": "1"
          },
          "deliveredQuantity": 2,
          "taxRate": "standard",
          "effectiveTaxRate": 19,
          "price": {
            "net": {
              "amount": "13.37",
              "currency": "EUR"
            },
            "gross": {
              "amount": "13.37",
              "currency": "EUR"
            }
          },
          "discount": 10,
          "taxLegalNotice": "Tax exempt according to §19 UStG"
        }
      ],
      "effectiveAddresses": {
        "soldTo": {
          "name": "John",
          "type": "mr",
          "title": "Ms.",
          "contactPerson": "Laura Schneider",
          "department": "Research & Development",
          "subDepartment": "CAI Lab",
          "addressSupplement": "Gebäude B, 4. Etage",
          "street": "Fuggerstraße 11",
          "zipCode": "86150",
          "city": "Augsburg",
          "state": "BY",
          "country": "DE",
          "salutation": "Sehr geehrte Damen und Herren",
          "gln": "1234567890123",
          "email": "alice@example.com",
          "phone": "+1-234-567-8900",
          "fax": "+1-234-567-8901",
          "mobile": "+1-234-567-8902"
        },
        "shipTo": {
          "name": "John",
          "type": "mr",
          "title": "Ms.",
          "contactPerson": "Laura Schneider",
          "department": "Research & Development",
          "subDepartment": "CAI Lab",
          "addressSupplement": "Gebäude B, 4. Etage",
          "street": "Fuggerstraße 11",
          "zipCode": "86150",
          "city": "Augsburg",
          "state": "BY",
          "country": "DE",
          "salutation": "Sehr geehrte Damen und Herren",
          "gln": "1234567890123",
          "email": "alice@example.com",
          "phone": "+1-234-567-8900",
          "fax": "+1-234-567-8901",
          "mobile": "+1-234-567-8902"
        },
        "customsTo": {
          "name": "John",
          "type": "mr",
          "title": "Ms.",
          "contactPerson": "Laura Schneider",
          "department": "Research & Development",
          "subDepartment": "CAI Lab",
          "addressSupplement": "Gebäude B, 4. Etage",
          "street": "Fuggerstraße 11",
          "zipCode": "86150",
          "city": "Augsburg",
          "state": "BY",
          "country": "DE",
          "salutation": "Sehr geehrte Damen und Herren",
          "gln": "1234567890123",
          "email": "alice@example.com",
          "phone": "+1-234-567-8900",
          "fax": "+1-234-567-8901",
          "mobile": "+1-234-567-8902"
        }
      }
    }
  ],
  "meta": {
    "currentPage": 1,
    "from": 1,
    "path": "https://api.example.com/items",
    "perPage": 15,
    "to": 15
  },
  "links": {
    "first": "https://api.example.com/items?page=1",
    "next": "https://api.example.com/items?page=17"
  }
}