Create an invoice
curl --request POST \
--url https://api.tilta.io/v1/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"external_id": "<string>",
"buyer_external_id": "<string>",
"invoice_number": "<string>",
"invoiced_at": 1582896122,
"due_at": 1582896122,
"amount": {
"net": 2,
"gross": 2,
"tax": 1
},
"merchant_external_id": "<string>",
"contact_external_id": "<string>",
"order_external_ids": [],
"line_items": [
{
"name": "<string>",
"category": "<string>",
"price": 123,
"quantity": 2,
"description": "<string>"
}
],
"delivery_address": {
"postcode": "12345",
"city": "Berlin",
"street": "Example Street",
"house": "42b",
"additional": "c/o Testimonial"
},
"custom_data": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: '<string>',
buyer_external_id: '<string>',
invoice_number: '<string>',
invoiced_at: 1582896122,
due_at: 1582896122,
amount: {net: 2, gross: 2, tax: 1},
merchant_external_id: '<string>',
contact_external_id: '<string>',
order_external_ids: [],
line_items: [
{
name: '<string>',
category: '<string>',
price: 123,
quantity: 2,
description: '<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', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.tilta.io/v1/invoices"
payload = {
"external_id": "<string>",
"buyer_external_id": "<string>",
"invoice_number": "<string>",
"invoiced_at": 1582896122,
"due_at": 1582896122,
"amount": {
"net": 2,
"gross": 2,
"tax": 1
},
"merchant_external_id": "<string>",
"contact_external_id": "<string>",
"order_external_ids": [],
"line_items": [
{
"name": "<string>",
"category": "<string>",
"price": 123,
"quantity": 2,
"description": "<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.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tilta.io/v1/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'buyer_external_id' => '<string>',
'invoice_number' => '<string>',
'invoiced_at' => 1582896122,
'due_at' => 1582896122,
'amount' => [
'net' => 2,
'gross' => 2,
'tax' => 1
],
'merchant_external_id' => '<string>',
'contact_external_id' => '<string>',
'order_external_ids' => [
],
'line_items' => [
[
'name' => '<string>',
'category' => '<string>',
'price' => 123,
'quantity' => 2,
'description' => '<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"
}Invoices
Create an invoice
Create an invoice to capture financing for one or more confirmed orders. Triggers the merchant payout and starts the buyer’s repayment clock.
POST
/
v1
/
invoices
Create an invoice
curl --request POST \
--url https://api.tilta.io/v1/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"external_id": "<string>",
"buyer_external_id": "<string>",
"invoice_number": "<string>",
"invoiced_at": 1582896122,
"due_at": 1582896122,
"amount": {
"net": 2,
"gross": 2,
"tax": 1
},
"merchant_external_id": "<string>",
"contact_external_id": "<string>",
"order_external_ids": [],
"line_items": [
{
"name": "<string>",
"category": "<string>",
"price": 123,
"quantity": 2,
"description": "<string>"
}
],
"delivery_address": {
"postcode": "12345",
"city": "Berlin",
"street": "Example Street",
"house": "42b",
"additional": "c/o Testimonial"
},
"custom_data": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: '<string>',
buyer_external_id: '<string>',
invoice_number: '<string>',
invoiced_at: 1582896122,
due_at: 1582896122,
amount: {net: 2, gross: 2, tax: 1},
merchant_external_id: '<string>',
contact_external_id: '<string>',
order_external_ids: [],
line_items: [
{
name: '<string>',
category: '<string>',
price: 123,
quantity: 2,
description: '<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', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.tilta.io/v1/invoices"
payload = {
"external_id": "<string>",
"buyer_external_id": "<string>",
"invoice_number": "<string>",
"invoiced_at": 1582896122,
"due_at": 1582896122,
"amount": {
"net": 2,
"gross": 2,
"tax": 1
},
"merchant_external_id": "<string>",
"contact_external_id": "<string>",
"order_external_ids": [],
"line_items": [
{
"name": "<string>",
"category": "<string>",
"price": 123,
"quantity": 2,
"description": "<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.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tilta.io/v1/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'buyer_external_id' => '<string>',
'invoice_number' => '<string>',
'invoiced_at' => 1582896122,
'due_at' => 1582896122,
'amount' => [
'net' => 2,
'gross' => 2,
'tax' => 1
],
'merchant_external_id' => '<string>',
'contact_external_id' => '<string>',
'order_external_ids' => [
],
'line_items' => [
[
'name' => '<string>',
'category' => '<string>',
'price' => 123,
'quantity' => 2,
'description' => '<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"
}Creating an invoice is the legally effective step that activates financing – it transforms authorized orders into a funded obligation. When you create an invoice, Tilta captures the financing amount, schedules the merchant payout, and begins the buyer’s repayment period based on the selected payment term. An invoice can consolidate multiple orders into a single financing event, and a single order can also be split across multiple invoices (for example, for partial shipments). The invoice is approved synchronously – a successful response means the financing is active.
invoice creation is not reversible through a standard update – to correct a captured invoice you must issue a
refund. Verify amounts and order associations before submitting.
Authorizations
Your Tilta API key, sent as Bearer <key>.
Body
application/json
Unique identifier of an invoice.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$Unique identifier of a buyer.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$The code for the payment method.
Available options:
CASH, CARD, TRANSFER, DEBIT Invoice number or reference.
Invoice creation date (unix time in seconds).
Example:
1582896122
Invoice due date (unix time in seconds).
Example:
1582896122
Show child attributes
Show child attributes
Unique identifier of a merchant. Optional only for Single-merchant platforms.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$External ID of an existing buyer contact to associate with this invoice. The contact must belong to the same buyer. When set, this contact will receive communication for this specific invoice in addition to any contacts subscribed to all invoices of the buyer.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$IDs of related orders.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$Order line items.
Show child attributes
Show child attributes
Billing address. If it is not provided, this will be filled with the buyer's business address.
Show child attributes
Show child attributes
Delivery address. If it is not provided, this will be filled with the buyer's default delivery address when set.
Show child attributes
Show child attributes
Free-form metadata for storing integration-specific data alongside this invoice.
Show child attributes
Show child attributes
Response
An invoice has been successfully created.
Unique identifier of an invoice.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$Unique identifier of a buyer.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$Unique identifier of a merchant.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$Timestamp indicating when the invoice was created (unix time in seconds).
Example:
1582896122
Timestamp indicating the last time the invoice was updated (unix time in seconds).
Example:
1582896122
Invoice due date (unix time in seconds).
Example:
1582896122
The current status of the invoice.
Available options:
OPEN, DUE, CLOSED, CANCELLED Days past due. Only available for invoices with status DUE.
Invoice payment method.
Available options:
CASH, CARD, TRANSFER, DEBIT Invoice number or reference.
Invoice creation date (unix time in seconds).
Example:
1582896122
Show child attributes
Show child attributes
The buyer contact associated with this invoice (if any).
Show child attributes
Show child attributes
Timestamp indicating when the invoice was marked as paid (unix time in seconds).
Show child attributes
Show child attributes
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
Show child attributes
Summary of all Credit Notes associated with this invoice.
Show child attributes
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"
}
IDs of related orders.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$Order line items.
Show child attributes
Show child attributes
Billing address. If it is not provided, this will be filled with the buyer's business address.
Show child attributes
Show child attributes
Delivery address. If it is not provided, this will be filled with the buyer's default delivery address when set.
Show child attributes
Show child attributes
Free-form metadata for storing integration-specific data alongside this invoice.
Show child attributes
Show child attributes