Sign in

v1

latestOpenAPI 3.0.02026-07-2455104.8 MB
Invoice

🔒 Create invoice 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: invoice:create.

Create a new invoice.

post/api/v3/invoices

Request body

documentDatestring date

Date of the document. Current date is used when omitted.

languagestring

Language of the document in an ISO-639-1 format.

internalDesignationstring

Internal designation, might be displayed in the letterhead

bodyIntroductionstring

Introduction text for the body of the document

bodyOutroductionstring

Outroduction text for the body of the document

vatIdstring

VAT ID of the business partner

deliveryTermsstring

Delivery terms for the document

internalCommentstring

Internal comment for the document

costCenterstring

Cost center for the document

dunningSetManuallyboolean

Indicates whether dunning values are manually set.

masterReferenceNumberstring

Master reference number for the invoice.

customerOrderNumberstring

Customer order number / reference.

deliveryDatestring date

Delivery date of the order the invoice is associated with.

useAlternativeDocumentTitleboolean

Indicates if the alternative document title should be used.

deviatingDebtorAccountNumberstring

Deviating debtor account number for accounting purposes.

documentNumberstring

Custom document number to assign to the invoice. By default, the document number is generated by Xentral when the invoice is released. Providing this field overrides that default: the supplied number is used and the invoice is created as released immediately (no separate actions/release call needed). Intended for use cases where the document number originates from an external system (e.g. Amazon VCS mirroring invoices from Amazon's own number range). The number must be unique across all invoices.

Example request

{
  "address": {
    "id": "13"
  },
  "project": {
    "id": "13"
  },
  "documentDate": "2025-07-15",
  "language": "en",
  "tags": [
    {
      "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",
  "bodyIntroduction": "Dear Sir or Madam,",
  "bodyOutroduction": "With kind regards,",
  "vatId": "DE123456789",
  "deliveryTerms": "Lieferung frei Haus",
  "internalComment": "This is an internal comment.",
  "editor": {
    "id": "6"
  },
  "costCenter": "CC-1234",
  "financials": {
    "tax": {
      "taxation": "domestic"
    },
    "currency": "EUR",
    "exchangeRate": 1.0875
  },
  "sales": {
    "id": "5"
  },
  "dunningSettings": {
    "level": "reminder1",
    "date": "2025-08-15",
    "comment": "Customer has paid partially."
  },
  "dunningManualSettings": {
    "paymentStatus": "paid",
    "paidAt": "2024-01-20",
    "actualAmount": {
      "amount": "13.37",
      "currency": "EUR"
    },
    "discountGiven": {
      "amount": "13.37",
      "currency": "EUR"
    }
  },
  "masterReferenceNumber": "MRN-123456",
  "customerOrderNumber": "PO-2024-12345",
  "deliveryDate": "2025-01-15",
  "deviatingDebtorAccountNumber": "10001",
  "lineItems": [
    {
      "product": {
        "id": "13"
      },
      "name": "Product X",
      "description": "Description of Product X",
      "countryOfOrigin": "DE",
      "hsCode": "0101.21",
      "deliveryDate": "2025-07-20",
      "internalComment": "This is an internal note.",
      "customerProductNumber": "CUS-10077",
      "unit": "pcs",
      "discount": 5,
      "price": {
        "net": {
          "amount": 99.99,
          "currency": "EUR"
        }
      },
      "taxLegalNotice": "Tax exempt according to §19 UStG"
    }
  ],
  "documentNumber": "AMZ-INV-DE-2025-1234567890",
  "salesOrder": {
    "id": "13"
  }
}

Response

Create a new invoice.

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"
    },
    "deliveryNote": {
      "id": "13"
    },
    "sales": {
      "id": "1"
    },
    "status": "cancelled",
    "customerOrderNumber": "PO-12345",
    "deliveryDate": "2023-10-15",
    "deviatingDebtorAccountNumber": "4001-12345",
    "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",
        "taxRate": "standard",
        "effectiveTaxRate": 19,
        "price": {
          "net": {
            "amount": "13.37",
            "currency": "EUR"
          },
          "gross": {
            "amount": "13.37",
            "currency": "EUR"
          }
        },
        "discount": 10,
        "itemRevenue": {
          "net": {
            "amount": "13.37",
            "currency": "EUR"
          },
          "gross": {
            "amount": "13.37",
            "currency": "EUR"
          }
        },
        "lineItemRevenue": {
          "net": {
            "amount": "13.37",
            "currency": "EUR"
          },
          "gross": {
            "amount": "13.37",
            "currency": "EUR"
          }
        },
        "purchasePrice": {
          "net": {
            "amount": "13.37",
            "currency": "EUR"
          }
        },
        "contributionMargin": 0.25,
        "taxLegalNotice": "Tax exempt according to §19 UStG",
        "salesOrderLineItem": {
          "id": "1"
        }
      }
    ],
    "masterReferenceNumber": "24DE1234567890ABCD",
    "effectiveAddresses": {
      "billTo": {
        "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"
      }
    },
    "paymentStatus": "paid",
    "dunningSettings": {
      "level": "reminder1",
      "date": "2024-01-15",
      "comment": "Customer promised payment next week."
    },
    "dunningManualSettings": {
      "paidAt": "2024-01-15",
      "actualAmount": {
        "amount": "13.37",
        "currency": "EUR"
      },
      "discountGiven": {
        "amount": "13.37",
        "currency": "EUR"
      },
      "difference": {
        "amount": "13.37",
        "currency": "EUR"
      }
    },
    "costCenter": "CC-123"
  }
}