Create invoice

Creates a new draft invoice for the specified company.

POST /api/v1/invoices

Headers

Request body

Collect object

When provided, creates an immediate payment record on the invoice.

Invoice line object

e-Factura BT fields

These optional fields are used for advanced e-Factura (UBL) compliance:

UBL extensions (document-level)

The ublExtensions object supports UBL XML elements that don't have dedicated invoice fields. All sub-fields are optional. Unknown keys are silently stripped.

UBL extensions (line-level)

Each line item can include a ublExtensions object:

Idempotency

Network failures, timeouts, and 5xx errors can leave a client unsure whether the invoice was actually created. Naive retry logic produces duplicate drafts. Storno offers two protections:

1. Explicit idempotency key (recommended)

Include idempotencyKey in the request body. The same key sent in a future request returns the original invoice instead of creating a new one.

The key must be:

• Stable per logical operation. Same Stripe payment intent, same shopping-cart checkout, same external order ID → same key, every retry.
• Unique within your namespace. Prefix with your service name to avoid collisions: stripe:pi_3TNpEhHy..., paddle:txn_01H..., myapp:order_42.
• Up to 255 characters. Use the underlying transaction ID and you'll be safe.

{
  "clientId": "...",
  "currency": "USD",
  "lines": [...],
  "idempotencyKey": "stripe:pi_3TNpEhHyDIBD6PSZ1ZnXYN4I"
}

The idempotency_key column has a unique index — you cannot accidentally have two invoices with the same key.

2. Fuzzy fallback (when no key is provided)

If your client doesn't send an idempotencyKey and a draft for the same (company, client, currency, total) was created in the last hour, that existing draft is returned instead of creating a new one. This catches retry storms from clients that don't yet support idempotency keys.

The fuzzy fallback only matches DRAFT invoices and only within a 60-minute window. It will not interfere with legitimate "create two similar drafts back-to-back" workflows once an hour has passed, and it never affects already-issued invoices.

Best practice

Always send an idempotencyKey — it's the safest, most explicit, and survives the 60-minute fuzzy window. Use the underlying business identifier (Stripe payment intent ID, your order ID) prefixed with your service name.

Common invoice type codes

• 380 - Commercial invoice (default)
• 381 - Credit note
• 384 - Corrected invoice
• 389 - Self-billed invoice
• 751 - Invoice information for accounting purposes

Request

curl -X POST https://api.storno.ro/api/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Company: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "issueDate": "2024-02-15",
    "dueDate": "2024-03-15",
    "currency": "RON",
    "notes": "Payment terms: 30 days net",
    "paymentTerms": "Net 30",
    "idempotencyKey": "myapp:order_42",
    "lines": [
      {
        "description": "Web Development Services",
        "quantity": 10,
        "unitPrice": 100.00,
        "unitOfMeasure": "hours",
        "vatIncluded": false
      }
    ]
  }'

const response = await fetch('https://api.storno.ro/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Company': '550e8400-e29b-41d4-a716-446655440000',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientId: 'a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d',
    issueDate: '2024-02-15',
    dueDate: '2024-03-15',
    currency: 'RON',
    notes: 'Payment terms: 30 days net',
    paymentTerms: 'Net 30',
    // Same key on every retry of this logical operation — see Idempotency section
    idempotencyKey: 'myapp:order_42',
    lines: [
      {
        description: 'Web Development Services',
        quantity: 10,
        unitPrice: 100.00,
        unitOfMeasure: 'hours',
        vatIncluded: false
      }
    ]
  })
});

const data = await response.json();
// data.invoice — the created invoice
// data.validation — UBL validation results

Response

Returns the created invoice object along with UBL validation results, with status 201 Created.

{
  "invoice": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "number": "DRAFT-a1b2c3d4",
    "status": "draft",
    "direction": "outgoing",
    "currency": "RON",
    "exchangeRate": 1.0,
    "issueDate": "2024-02-15",
    "dueDate": "2024-03-15",
    "subtotal": 1000.00,
    "vatTotal": 190.00,
    "total": 1190.00,
    "amountPaid": 0.00,
    "balance": 1190.00,
    "notes": "Payment terms: 30 days net",
    "paymentTerms": "Net 30",
    "client": {
      "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Corporation SRL",
      "cif": "RO98765432"
    },
    "lines": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "description": "Web Development Services",
        "quantity": 10.0,
        "unitPrice": 100.00,
        "unitOfMeasure": "hours",
        "vatRate": 19.0,
        "vatAmount": 190.00,
        "subtotal": 1000.00,
        "total": 1190.00
      }
    ],
    "createdAt": "2024-02-15T08:30:00Z",
    "updatedAt": "2024-02-15T08:30:00Z"
  },
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "schematronAvailable": true
  }
}

Error codes