Create an invoice draft

curl --request POST \
  --url https://api.melso.ai/v1/companies/{company_id}/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "irpf_rate": "15",
  "lines": [
    {
      "description": "Diseño de identidad visual",
      "quantity": "1",
      "unit_price": "1200.00",
      "vat_rate": "21",
      "product_kind": "services"
    }
  ]
}
'

import requests

url = "https://api.melso.ai/v1/companies/{company_id}/invoices"

payload = {
    "customer_id": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f",
    "issue_date": "2026-10-15",
    "due_date": "2026-11-14",
    "irpf_rate": "15",
    "lines": [
        {
            "description": "Diseño de identidad visual",
            "quantity": "1",
            "unit_price": "1200.00",
            "vat_rate": "21",
            "product_kind": "services"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer_id: '3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f',
    issue_date: '2026-10-15',
    due_date: '2026-11-14',
    irpf_rate: '15',
    lines: [
      {
        description: 'Diseño de identidad visual',
        quantity: '1',
        unit_price: '1200.00',
        vat_rate: '21',
        product_kind: 'services'
      }
    ]
  })
};

fetch('https://api.melso.ai/v1/companies/{company_id}/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": "<string>",
  "type": "standard",
  "status": "draft",
  "issue_date": "2023-12-25",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lines": [
    {
      "description": "<string>",
      "quantity": "<string>",
      "unit_price": "<string>",
      "vat_rate": "<string>",
      "product_kind": "goods",
      "amount": "121.00"
    }
  ],
  "subtotal": "121.00",
  "vat_amount": "121.00",
  "irpf_amount": "121.00",
  "total": "121.00",
  "currency": "EUR",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "series": "<string>",
  "number": 123,
  "due_date": "2023-12-25",
  "customer_name": "<string>",
  "customer_tax_id": "<string>",
  "irpf_rate": "<string>",
  "tax_label": "IVA",
  "notes": "<string>",
  "fiscal_network": "verifactu",
  "verifactu_status": "pending",
  "pdf_ready": true,
  "payment_link": "<string>",
  "payment_link_status": "pending",
  "email_delivery_status": "pending",
  "email_delivery_error": "<string>",
  "sent_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "corrects_invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": "lines[0].vat_rate must be 21, 10, 4 or 0",
  "code": "invalid_invoice",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "invalid token",
  "code": "unauthorized",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "Review and approve in the authenticated web application",
  "code": "person_required",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "invoice not found",
  "code": "not_found",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "The tax return changed or is not ready for approval",
  "code": "version_conflict",
  "request_id": "req_01JAB3K9X2"
}

POST

companies

{company_id}

invoices

Create an invoice draft

curl --request POST \
  --url https://api.melso.ai/v1/companies/{company_id}/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "irpf_rate": "15",
  "lines": [
    {
      "description": "Diseño de identidad visual",
      "quantity": "1",
      "unit_price": "1200.00",
      "vat_rate": "21",
      "product_kind": "services"
    }
  ]
}
'

import requests

url = "https://api.melso.ai/v1/companies/{company_id}/invoices"

payload = {
    "customer_id": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f",
    "issue_date": "2026-10-15",
    "due_date": "2026-11-14",
    "irpf_rate": "15",
    "lines": [
        {
            "description": "Diseño de identidad visual",
            "quantity": "1",
            "unit_price": "1200.00",
            "vat_rate": "21",
            "product_kind": "services"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer_id: '3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f',
    issue_date: '2026-10-15',
    due_date: '2026-11-14',
    irpf_rate: '15',
    lines: [
      {
        description: 'Diseño de identidad visual',
        quantity: '1',
        unit_price: '1200.00',
        vat_rate: '21',
        product_kind: 'services'
      }
    ]
  })
};

fetch('https://api.melso.ai/v1/companies/{company_id}/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": "<string>",
  "type": "standard",
  "status": "draft",
  "issue_date": "2023-12-25",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lines": [
    {
      "description": "<string>",
      "quantity": "<string>",
      "unit_price": "<string>",
      "vat_rate": "<string>",
      "product_kind": "goods",
      "amount": "121.00"
    }
  ],
  "subtotal": "121.00",
  "vat_amount": "121.00",
  "irpf_amount": "121.00",
  "total": "121.00",
  "currency": "EUR",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "series": "<string>",
  "number": 123,
  "due_date": "2023-12-25",
  "customer_name": "<string>",
  "customer_tax_id": "<string>",
  "irpf_rate": "<string>",
  "tax_label": "IVA",
  "notes": "<string>",
  "fiscal_network": "verifactu",
  "verifactu_status": "pending",
  "pdf_ready": true,
  "payment_link": "<string>",
  "payment_link_status": "pending",
  "email_delivery_status": "pending",
  "email_delivery_error": "<string>",
  "sent_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "corrects_invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": "lines[0].vat_rate must be 21, 10, 4 or 0",
  "code": "invalid_invoice",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "invalid token",
  "code": "unauthorized",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "Review and approve in the authenticated web application",
  "code": "person_required",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "invoice not found",
  "code": "not_found",
  "request_id": "req_01JAB3K9X2"
}

{
  "error": "The tax return changed or is not ready for approval",
  "code": "version_conflict",
  "request_id": "req_01JAB3K9X2"
}

Live capability. Melso runs this in production today. Partner keys reach it once your partner account is enabled. See Availability.

A draft has no series or number and is not registered anywhere until a person issues it. Use Create an invoice approval link to get the page where the owner issues it.

Authorizations

Authorization

string

header

required

Your partner secret key, mk_live_… for real companies or mk_test_… for test companies. Keep it on your servers. See Authentication.

Headers

Idempotency-Key

string

A unique key, such as a UUID, that makes a retried create safe. Reusing a key with a different body is refused.

Maximum string length: 255

Path Parameters

company_id

string<uuid>

required

The company's ID. Every company-scoped call works in exactly this company.

Body

application/json

customer_id

string<uuid>

required

issue_date

string<date>

required

lines

object[]

required

Required array length: 1 - 200 elements

Show child attributes

type

enum<string>

default:standard

Available options:

standard,

proforma

due_date

string<date>

On or after issue_date.

irpf_rate

enum<string>

default:0

IRPF withholding for an autónomo professional invoicing a business. A company always uses 0.

Available options:

0,

7,

15

notes

string

Maximum string length: 4000

Response

The draft, with status draft and its calculated totals.

string<uuid>

required

version

string

required

A fingerprint of the invoice's fiscal content. Issuing requires the exact version the person reviewed.

type

enum<string>

required

Available options:

standard,

proforma,

corrective

status

enum<string>

required

draft until a person issues it. issued once numbered; sent once emailed; paid once marked paid.

Available options:

draft,

issued,

sent,

paid

issue_date

string<date>

required

customer_id

string<uuid>

required

lines

object[]

required

Show child attributes

subtotal

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

vat_amount

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

irpf_amount

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

total

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

currency

string

required

Allowed value: "EUR"

created_at

string<date-time>

required

updated_at

string<date-time>

required

series

string | null

Set at issue. The issue year, such as 2026; R-2026 for a corrective.

number

integer | null

Set at issue, the next in the series.

due_date

string<date> | null

customer_name

string

The customer's name when the invoice was drafted.

customer_tax_id

string

irpf_rate

string

A decimal number as a string, such as "21" or "0.5".

Pattern: ^-?[0-9]{1,10}(\.[0-9]{1,6})?$

tax_label

enum<string>

Available options:

IVA,

IGIC

notes

string

fiscal_network

enum<string>

Where the invoice is registered, from the company's tax territory.

Available options:

verifactu,

ticketbai

verifactu_status

enum<string>

The registration state with VERI*FACTU or TicketBAI.

Available options:

pending,

registered,

error

pdf_ready

boolean

payment_link

string<uri> | null

payment_link_status

enum<string>

Available options:

pending,

creating,

active,

inactive,

error,

unknown

email_delivery_status

enum<string>

Available options:

pending,

sending,

sent,

error,

unknown

email_delivery_error

string | null

sent_at

string<date-time> | null

paid_at

string<date-time> | null

corrects_invoice_id

string<uuid> | null

Get started

Solutions

Companies and access

Invoicing

Bookkeeping

Taxes

Payroll and Social Security

Create an invoice draft

Authorizations

Headers

Path Parameters

Body

Response