invoices

Create /invoices

Create an invoice. Required: contact (client UUID), date, currency (currency name), and items (at least one line). Optional: due date, sale agent, notes, addresses, organization, is_reverse_vat, vat_adaptation_articles (picklist value UUIDs from finance/vat_adaptation_article), and manual numbering via document_prefix + document_number (skips auto numbering and uses OTHER_PREFIX). Returns record with the detail projection.

POST

/invoices

Create /invoices

curl --request POST \
  --url https://default.hannacrm.app/api/v4/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "adminnote": "<string>",
  "billing_city": "<string>",
  "billing_country": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "billing_state": "<string>",
  "billing_street": "<string>",
  "billing_zip": "<string>",
  "clientnote": "<string>",
  "contact": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_person": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "<string>",
  "custom_fields": [
    {
      "slug": "<string>",
      "value": "<any>"
    }
  ],
  "custom_recurring": 123,
  "date": "<string>",
  "document_number": "<string>",
  "document_prefix": "<string>",
  "due_date": "<string>",
  "is_reverse_vat": "<string>",
  "items": [
    {
      "code": "<string>",
      "description": "<string>",
      "item": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "item_code": "<string>",
      "long_description": "<string>",
      "product_discount": 123,
      "qty": 123,
      "rate": 123,
      "unit": "<string>",
      "vat_percent": 123,
      "warehouse": "<string>"
    }
  ],
  "organization": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recurring": "<string>",
  "recurring_ends_on": "<string>",
  "recurring_type": "<string>",
  "sale_agent": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shipping_city": "<string>",
  "shipping_country": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shipping_state": "<string>",
  "shipping_street": "<string>",
  "shipping_zip": "<string>",
  "status": 123,
  "terms": "<string>",
  "vat_adaptation_articles": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{
  "record": {
    "adjustment": "<string>",
    "adminnote": "<string>",
    "amount_due": "<string>",
    "billing_address": {
      "city": "<string>",
      "country": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zip": "<string>"
    },
    "client": [
      {}
    ],
    "clientnote": "<string>",
    "contact": [
      {}
    ],
    "contact_person": [
      {}
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": {
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "currency": {
      "name": "<string>",
      "symbol": "<string>"
    },
    "custom_fields": [
      {
        "slug": "<string>",
        "value": "<any>"
      }
    ],
    "custom_recurring": "<string>",
    "date": "<string>",
    "discount_percent": "<string>",
    "discount_total": "<string>",
    "discount_type": "<string>",
    "document_full_number": "<string>",
    "document_number": "<string>",
    "document_prefix": "<string>",
    "due_date": "<string>",
    "is_reverse_vat": "<string>",
    "items": [
      {}
    ],
    "organization": [
      {}
    ],
    "organization_name": "<string>",
    "projects": [
      {}
    ],
    "recurring": "<string>",
    "recurring_ends_on": "<string>",
    "recurring_type": "<string>",
    "sale_agent": [
      {}
    ],
    "shipping_address": {
      "city": "<string>",
      "country": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zip": "<string>"
    },
    "status": "<string>",
    "subtotal": "<string>",
    "terms": "<string>",
    "total": "<string>",
    "total_tax": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "updated_by": {
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },

Authorizations

Authorizationstringheaderrequired

API key (Bearer token) created in Setup → API & MCP.

Body

adminnotestring

Internal admin note.

billing_citystring

Billing city.

billing_countrystring

Billing country UUID.

billing_statestring

Billing state/region.

billing_streetstring

Billing street address.

billing_zipstring

Billing ZIP/postal code.

clientnotestring

Note visible to client.

contactstringrequired

Client UUID.

contact_personstring

Contact person UUID.

currencystringrequired

Currency name (e.g. EUR).

custom_fieldsobject[]

Custom field values by slug.

Show child attributes

custom_recurringinteger

Custom recurring interval value.

datestringrequired

Invoice date (Y-m-d).

document_numberstring

Custom document number suffix. Required when document_prefix is provided.

document_prefixstring

Custom document number prefix. When provided, auto numbering is skipped and the invoice is stored under OTHER_PREFIX with a manual full number built from document_prefix and document_number.

due_datestring

Due date (Y-m-d).

is_reverse_vatstring

Apply reverse VAT taxation. When true, invoice total equals subtotal (excl. VAT).

itemsobject[]required

Invoice line items. At least one object is required.

Show child attributes

organizationstring

Organization UUID.

recurringstring

Whether the invoice is recurring.

recurring_ends_onstring

Recurring end date (Y-m-d).

recurring_typestring

Recurring interval type.

sale_agentstring

Sale agent staff UUID.

shipping_citystring

Shipping city.

shipping_countrystring

Shipping country UUID.

shipping_statestring

Shipping state/region.

shipping_streetstring

Shipping street address.

shipping_zipstring

Shipping ZIP/postal code.

statusinteger

Invoice status code (1–6).

termsstring

Terms and conditions.

vat_adaptation_articlesstring[]

VAT adaptation article picklist value UUIDs (finance/vat_adaptation_article). Discover values via GET /api/v4/picklists. Pass [] to clear.

Response

Success

recordobject

Fields enabled for this documentation instance (projection enabled: feature, option, subdomain, closures) plus account-level form field visibility. Role- and user-level field overrides are not applied here, so an API key whose staff user has such overrides may receive fewer fields. A disabled field is omitted from the response object entirely; a present key with a null value means the record simply has no value.

Show child attributes

Still need help? Ask the team