Generate invoice

POST

/invoices/generate

Accepts normalized invoice JSON, creates a stored invoice record, and queues
background generation plus validation by default.

Clients can explicitly request synchronous behavior with the header
Prefer: respond-sync.

Request validation failures use Laravel's standard 422 response shape.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Synchronous generation succeeded without blocking validation findings

Body

🟢202

🟠401

🟠402

🟠422

🟠429

🔴500

Request Example

Shell

JavaScript

Java

Swift

cURL

Valid minimal invoice payloadZUGFeRD payload with remote logo branding

curl --location --request POST 'https://api.xinvoice.net/v1/invoices/generate' \
--header 'Prefer;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "document_format": "xrechnung_ubl",
    "invoice_number": "RE-2026-001",
    "issue_date": "2026-04-07T00:00:00.000Z",
    "due_date": "2026-04-21T00:00:00.000Z",
    "delivery_date": "2026-04-07T00:00:00.000Z",
    "buyer_reference": "04011000-12345-03",
    "invoice_note": "Projektphase April 2026",
    "order_reference": "PO-2026-001",
    "payment_means_code": "58",
    "payment_terms_note": "Zahlbar bis 2026-04-21 ohne Abzug.",
    "currency": "EUR",
    "invoice_type_code": "380",
    "seller": {
        "name": "Muster GmbH",
        "vat_id": "DE123456789",
        "street": "Musterstr. 1",
        "postal_code": "12345",
        "city": "Berlin",
        "country_code": "DE",
        "email": "seller@example.com",
        "contact_name": "Max Muster",
        "contact_email": "seller@example.com",
        "phone": "+49 30 1234567",
        "iban": "DE75512108001245126199"
    },
    "buyer": {
        "name": "Kunde GmbH",
        "street": "Hauptstr. 5",
        "postal_code": "54321",
        "city": "Hamburg",
        "country_code": "DE",
        "email": "buyer@example.com"
    },
    "items": [
        {
            "name": "Webentwicklung",
            "description": "Implementierung und Review",
            "quantity": 10,
            "unit_code": "HUR",
            "price": 100,
            "tax_rate": 19
        }
    ]
}'

Response Example

201 - Explicit synchronous success

{
    "status": "generated",
    "invoice_id": "6c590ad5-e8c8-4f43-9c58-62fbbe993c15",
    "invoice_number": "RE-2026-001",
    "processing_mode": "sync",
    "document_format": "xrechnung_ubl",
    "document_profile": "EN16931",
    "validation": {
        "valid": true,
        "errors": []
    },
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\" xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\" xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">\n <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</cbc:CustomizationID>\n <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>\n <cbc:ID>RE-2026-001</cbc:ID>\n <cbc:IssueDate>2026-04-07</cbc:IssueDate>\n <cbc:DueDate>2026-04-21</cbc:DueDate>\n <cbc:BuyerReference>04011000-12345-03</cbc:BuyerReference>\n</Invoice>\n",
    "queued_at": "2026-04-07T19:59:58+00:00",
    "started_at": "2026-04-07T19:59:59+00:00",
    "finished_at": "2026-04-07T20:00:00+00:00",
    "processing_error": null
}

Modified at 2026-04-20 18:39:27

Check runtime readiness for invoice validation

Validate invoice JSON, raw XML, or raw ZUGFeRD PDF