Update an invoice

Updates an invoice

curl --request PUT \
  --url https://api.tilta.io/v1/invoices/{external_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "buyer_external_id": "<string>",
  "invoiced_at": 1582896122,
  "due_at": 1582896122,
  "amount": {
    "net": 2,
    "gross": 2,
    "tax": 1
  },
  "billing_address": {
    "postcode": "12345",
    "city": "Berlin",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "contact_external_id": "<string>",
  "delivery_address": {
    "postcode": "12345",
    "city": "Berlin",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "custom_data": {}
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    buyer_external_id: '<string>',
    invoiced_at: 1582896122,
    due_at: 1582896122,
    amount: {net: 2, gross: 2, tax: 1},
    billing_address: {
      postcode: '12345',
      city: 'Berlin',
      street: 'Example Street',
      house: '42b',
      additional: 'c/o Testimonial'
    },
    contact_external_id: '<string>',
    delivery_address: {
      postcode: '12345',
      city: 'Berlin',
      street: 'Example Street',
      house: '42b',
      additional: 'c/o Testimonial'
    },
    custom_data: {}
  })
};

fetch('https://api.tilta.io/v1/invoices/{external_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.tilta.io/v1/invoices/{external_id}"

payload = {
    "buyer_external_id": "<string>",
    "invoiced_at": 1582896122,
    "due_at": 1582896122,
    "amount": {
        "net": 2,
        "gross": 2,
        "tax": 1
    },
    "billing_address": {
        "postcode": "12345",
        "city": "Berlin",
        "street": "Example Street",
        "house": "42b",
        "additional": "c/o Testimonial"
    },
    "contact_external_id": "<string>",
    "delivery_address": {
        "postcode": "12345",
        "city": "Berlin",
        "street": "Example Street",
        "house": "42b",
        "additional": "c/o Testimonial"
    },
    "custom_data": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tilta.io/v1/invoices/{external_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'buyer_external_id' => '<string>',
    'invoiced_at' => 1582896122,
    'due_at' => 1582896122,
    'amount' => [
        'net' => 2,
        'gross' => 2,
        'tax' => 1
    ],
    'billing_address' => [
        'postcode' => '12345',
        'city' => 'Berlin',
        'street' => 'Example Street',
        'house' => '42b',
        'additional' => 'c/o Testimonial'
    ],
    'contact_external_id' => '<string>',
    'delivery_address' => [
        'postcode' => '12345',
        'city' => 'Berlin',
        'street' => 'Example Street',
        'house' => '42b',
        'additional' => 'c/o Testimonial'
    ],
    'custom_data' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "external_id": "<string>",
  "buyer_external_id": "<string>",
  "merchant_external_id": "<string>",
  "created_at": 1582896122,
  "updated_at": 1582896122,
  "due_at": 1582896122,
  "status": "OPEN",
  "days_past_due": 123,
  "payment_method": "CASH",
  "invoice_number": "<string>",
  "invoiced_at": 1582896122,
  "amount": {
    "net": 2,
    "gross": 2,
    "currency": "EUR",
    "tax": 1
  },
  "contact": {
    "external_id": "<string>",
    "buyer_external_id": "<string>",
    "assign_to_all_invoices": true,
    "created_at": 1582896122,
    "updated_at": 1582896122,
    "salutation": "MR",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "+491711010101",
    "address": {
      "postcode": "12345",
      "city": "Berlin",
      "country": "AF",
      "street": "Example Street",
      "house": "42b",
      "additional": "c/o Testimonial"
    }
  },
  "paid_at": 123,
  "buyer": {
    "legal_name": "<string>"
  },
  "services": [
    {
      "external_id": "<string>",
      "invoice_external_id": "<string>",
      "service_type": "FINANCING",
      "status": "IN_REVIEW",
      "created_at": 123,
      "updated_at": 123,
      "requirements": [
        {
          "code": "INVOICE_INELIGIBLE",
          "description": "<string>"
        }
      ],
      "advance": {
        "value": 123
      },
      "fee": {
        "gross": 123,
        "net": 123,
        "tax": 123
      }
    }
  ],
  "credit_note_summary": {
    "count": 2,
    "amount": {
      "gross": 1000,
      "net": 800,
      "tax": 200,
      "currency": "EUR"
    },
    "original_invoice_amount": {
      "gross": 5000,
      "net": 4000,
      "tax": 1000,
      "currency": "EUR"
    },
    "has_active_mandate": true,
    "financing_status": "IN_REVIEW"
  },
  "order_external_ids": [],
  "line_items": [
    {
      "name": "<string>",
      "category": "<string>",
      "price": 123,
      "currency": "EUR",
      "quantity": 2,
      "description": "<string>"
    }
  ],
  "billing_address": {
    "postcode": "12345",
    "city": "Berlin",
    "country": "AF",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "delivery_address": {
    "postcode": "12345",
    "city": "Berlin",
    "country": "AF",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "custom_data": {}
}

{
  "code": "BAD_REQUEST",
  "error": "Request validation failed. 1 issue found.",
  "issues": [
    {
      "code": "INVALID_TYPE",
      "path": "body.registered_at",
      "message": "Invalid type"
    }
  ]
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "No Entity found",
  "code": "NOT_FOUND"
}

PUT

invoices

{external_id}

Updates an invoice

curl --request PUT \
  --url https://api.tilta.io/v1/invoices/{external_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "buyer_external_id": "<string>",
  "invoiced_at": 1582896122,
  "due_at": 1582896122,
  "amount": {
    "net": 2,
    "gross": 2,
    "tax": 1
  },
  "billing_address": {
    "postcode": "12345",
    "city": "Berlin",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "contact_external_id": "<string>",
  "delivery_address": {
    "postcode": "12345",
    "city": "Berlin",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "custom_data": {}
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    buyer_external_id: '<string>',
    invoiced_at: 1582896122,
    due_at: 1582896122,
    amount: {net: 2, gross: 2, tax: 1},
    billing_address: {
      postcode: '12345',
      city: 'Berlin',
      street: 'Example Street',
      house: '42b',
      additional: 'c/o Testimonial'
    },
    contact_external_id: '<string>',
    delivery_address: {
      postcode: '12345',
      city: 'Berlin',
      street: 'Example Street',
      house: '42b',
      additional: 'c/o Testimonial'
    },
    custom_data: {}
  })
};

fetch('https://api.tilta.io/v1/invoices/{external_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.tilta.io/v1/invoices/{external_id}"

payload = {
    "buyer_external_id": "<string>",
    "invoiced_at": 1582896122,
    "due_at": 1582896122,
    "amount": {
        "net": 2,
        "gross": 2,
        "tax": 1
    },
    "billing_address": {
        "postcode": "12345",
        "city": "Berlin",
        "street": "Example Street",
        "house": "42b",
        "additional": "c/o Testimonial"
    },
    "contact_external_id": "<string>",
    "delivery_address": {
        "postcode": "12345",
        "city": "Berlin",
        "street": "Example Street",
        "house": "42b",
        "additional": "c/o Testimonial"
    },
    "custom_data": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tilta.io/v1/invoices/{external_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'buyer_external_id' => '<string>',
    'invoiced_at' => 1582896122,
    'due_at' => 1582896122,
    'amount' => [
        'net' => 2,
        'gross' => 2,
        'tax' => 1
    ],
    'billing_address' => [
        'postcode' => '12345',
        'city' => 'Berlin',
        'street' => 'Example Street',
        'house' => '42b',
        'additional' => 'c/o Testimonial'
    ],
    'contact_external_id' => '<string>',
    'delivery_address' => [
        'postcode' => '12345',
        'city' => 'Berlin',
        'street' => 'Example Street',
        'house' => '42b',
        'additional' => 'c/o Testimonial'
    ],
    'custom_data' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "external_id": "<string>",
  "buyer_external_id": "<string>",
  "merchant_external_id": "<string>",
  "created_at": 1582896122,
  "updated_at": 1582896122,
  "due_at": 1582896122,
  "status": "OPEN",
  "days_past_due": 123,
  "payment_method": "CASH",
  "invoice_number": "<string>",
  "invoiced_at": 1582896122,
  "amount": {
    "net": 2,
    "gross": 2,
    "currency": "EUR",
    "tax": 1
  },
  "contact": {
    "external_id": "<string>",
    "buyer_external_id": "<string>",
    "assign_to_all_invoices": true,
    "created_at": 1582896122,
    "updated_at": 1582896122,
    "salutation": "MR",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "+491711010101",
    "address": {
      "postcode": "12345",
      "city": "Berlin",
      "country": "AF",
      "street": "Example Street",
      "house": "42b",
      "additional": "c/o Testimonial"
    }
  },
  "paid_at": 123,
  "buyer": {
    "legal_name": "<string>"
  },
  "services": [
    {
      "external_id": "<string>",
      "invoice_external_id": "<string>",
      "service_type": "FINANCING",
      "status": "IN_REVIEW",
      "created_at": 123,
      "updated_at": 123,
      "requirements": [
        {
          "code": "INVOICE_INELIGIBLE",
          "description": "<string>"
        }
      ],
      "advance": {
        "value": 123
      },
      "fee": {
        "gross": 123,
        "net": 123,
        "tax": 123
      }
    }
  ],
  "credit_note_summary": {
    "count": 2,
    "amount": {
      "gross": 1000,
      "net": 800,
      "tax": 200,
      "currency": "EUR"
    },
    "original_invoice_amount": {
      "gross": 5000,
      "net": 4000,
      "tax": 1000,
      "currency": "EUR"
    },
    "has_active_mandate": true,
    "financing_status": "IN_REVIEW"
  },
  "order_external_ids": [],
  "line_items": [
    {
      "name": "<string>",
      "category": "<string>",
      "price": 123,
      "currency": "EUR",
      "quantity": 2,
      "description": "<string>"
    }
  ],
  "billing_address": {
    "postcode": "12345",
    "city": "Berlin",
    "country": "AF",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "delivery_address": {
    "postcode": "12345",
    "city": "Berlin",
    "country": "AF",
    "street": "Example Street",
    "house": "42b",
    "additional": "c/o Testimonial"
  },
  "custom_data": {}
}

{
  "code": "BAD_REQUEST",
  "error": "Request validation failed. 1 issue found.",
  "issues": [
    {
      "code": "INVALID_TYPE",
      "path": "body.registered_at",
      "message": "Invalid type"
    }
  ]
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "No Entity found",
  "code": "NOT_FOUND"
}

You can update the editable fields on an invoice after creation, as long as no Tilta service is active on it. This is useful for correcting metadata errors – such as an incorrect invoice number or issuance date – before financing becomes active. Like all PUT operations, this request replaces the editable portion of the invoice with the values you provide, so include every field you want to retain.

This endpoint uses PUT semantics for the editable fields. Omitting an editable field from your request body may clear its value. To make safe partial updates, retrieve the invoice first and include all desired field values in your PUT payload.

The invoice amount, currency, buyer_external_id, merchant_external_id, and order_external_ids are immutable after creation. To correct these values, you must refund the invoice and create a new one.

Authorizations

Authorization

string

header

required

Your Tilta API key, sent as Bearer <key>.

Path Parameters

external_id

string

required

Unique identifier of an invoice.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

Body

application/json

buyer_external_id

string

required

Unique identifier of a buyer.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

invoiced_at

number

required

Invoice creation date (unix time in seconds).

Example:

1582896122

due_at

number

required

Invoice due date (unix time in seconds).

Example:

1582896122

amount

object

required

Show child attributes

payment_method

enum<string>

required

The code for the payment method.

Available options:

CASH,

CARD,

TRANSFER,

DEBIT

billing_address

object

required

Billing address.

Show child attributes

contact_external_id

string | null

required

External ID of an existing buyer contact to associate with this invoice. Must belong to the same buyer. Send null to unlink.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

delivery_address

object | null

required

Delivery address. Send null to remove it.

Show child attributes

custom_data

object | null

Free-form metadata for storing integration-specific data alongside this invoice.

Show child attributes

Response

The invoice has been successfully updated.

external_id

string

required

Unique identifier of an invoice.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

buyer_external_id

string

required

Unique identifier of a buyer.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

merchant_external_id

string

required

Unique identifier of a merchant.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

created_at

number

required

Timestamp indicating when the invoice was created (unix time in seconds).

Example:

1582896122

updated_at

number

required

Timestamp indicating the last time the invoice was updated (unix time in seconds).

Example:

1582896122

due_at

number

required

Invoice due date (unix time in seconds).

Example:

1582896122

status

enum<string>

required

The current status of the invoice.

Available options:

OPEN,

DUE,

CLOSED,

CANCELLED

days_past_due

integer | null

required

Days past due. Only available for invoices with status DUE.

payment_method

enum<string>

required

Invoice payment method.

Available options:

CASH,

CARD,

TRANSFER,

DEBIT

invoice_number

string

required

Invoice number or reference.

invoiced_at

number

required

Invoice creation date (unix time in seconds).

Example:

1582896122

amount

object

required

Show child attributes

contact

object | null

The buyer contact associated with this invoice (if any).

Show child attributes

paid_at

number

Timestamp indicating when the invoice was marked as paid (unix time in seconds).

buyer

object

Show child attributes

services

object[]

Invoice services with their current status. Returned only when expand includes services. Ordered oldest first; a service type may appear more than once after a resubmission.

Show child attributes

credit_note_summary

object

Summary of all Credit Notes associated with this invoice.

Show child attributes

Example:

{
  "count": 2,
  "amount": {
    "gross": 1000,
    "net": 800,
    "tax": 200,
    "currency": "EUR"
  },
  "original_invoice_amount": {
    "gross": 5000,
    "net": 4000,
    "tax": 1000,
    "currency": "EUR"
  },
  "has_active_mandate": true,
  "financing_status": "IN_REVIEW"
}

order_external_ids

string[]

IDs of related orders.

Maximum string length: 100

Pattern: ^[a-zA-Z0-9-_]+$

line_items

object[]

Order line items.

Show child attributes

billing_address

object

Billing address. If it is not provided, this will be filled with the buyer's business address.

Show child attributes

delivery_address

object | null

Delivery address. If it is not provided, this will be filled with the buyer's default delivery address when set.

Show child attributes

custom_data

object | null

Free-form metadata for storing integration-specific data alongside this invoice.

Show child attributes

Buyers

Credit Facilities

Orders

Invoices

Merchants

Contacts & Persons

Webhooks

Platform & Utilities

Update an invoice

Authorizations

Path Parameters

Body

Response