billware API | Documentation / Use cases

Use cases

This is how the methods work together: complete flows from practice, every call in the order you need it, with the values to keep from the answer. The examples are the same as on the method pages, you can replay them in Postman.

Note

Every answer has response, data and message. Always check response: a refused call comes with HTTP 200 and response: false, the message tells why. The identifiers (*_ident) in data are what your system stores.

Shop order: from the customer to the sent invoice

The most common flow: a shop or an ERP creates the customer and the order for every purchase and lets billware create and send the invoice once the goods are out. Three calls.

Step 1: customer.create

Create the customer and keep customer_ident from the answer. If you created the customer before, use the stored identifier; customer.exists tells whether it is still valid. Country codes in lower case, e.g. de.

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"customer_type":"billware","is_business_client":0,"bill_title":"Mister","bill_firstname":"Max","bill_lastname":"Mustermann","bill_street":"Musterstraße 12","bill_zipcode":"12345","bill_city":"Musterstadt","bill_country":"de","bill_phone":"+49 123 4567890","bill_email":"max.mustermann@example.com","divergent_delivery_address":1,"delivery_title":"Mister","delivery_firstname":"Max","delivery_lastname":"Mustermann","delivery_street":"Lieferweg 5","delivery_zipcode":"54321","delivery_city":"Lieferstadt","delivery_country":"de","delivery_phone":"+49 987 6543210","account_iban":"DE89370400440532013000","account_bic":"COBADEFFXXX","account_bank":"Commerzbank","account_paypal":"max.paypal@example.com","user_note":"Kunde möchte Rechnung nur per E-Mail erhalten","public_authority_id":""}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: customer.create" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'customer_type' => 'billware',
    'is_business_client' => 0,
    'bill_title' => 'Mister',
    'bill_firstname' => 'Max',
    'bill_lastname' => 'Mustermann',
    'bill_street' => 'Musterstraße 12',
    'bill_zipcode' => '12345',
    'bill_city' => 'Musterstadt',
    'bill_country' => 'de',
    'bill_phone' => '+49 123 4567890',
    'bill_email' => 'max.mustermann@example.com',
    'divergent_delivery_address' => 1,
    'delivery_title' => 'Mister',
    'delivery_firstname' => 'Max',
    'delivery_lastname' => 'Mustermann',
    'delivery_street' => 'Lieferweg 5',
    'delivery_zipcode' => '54321',
    'delivery_city' => 'Lieferstadt',
    'delivery_country' => 'de',
    'delivery_phone' => '+49 987 6543210',
    'account_iban' => 'DE89370400440532013000',
    'account_bic' => 'COBADEFFXXX',
    'account_bank' => 'Commerzbank',
    'account_paypal' => 'max.paypal@example.com',
    'user_note' => 'Kunde möchte Rechnung nur per E-Mail erhalten',
    'public_authority_id' => '',
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: customer.create',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "customer_type": "billware",
    "is_business_client": 0,
    "bill_title": "Mister",
    "bill_firstname": "Max",
    "bill_lastname": "Mustermann",
    "bill_street": "Musterstraße 12",
    "bill_zipcode": "12345",
    "bill_city": "Musterstadt",
    "bill_country": "de",
    "bill_phone": "+49 123 4567890",
    "bill_email": "max.mustermann@example.com",
    "divergent_delivery_address": 1,
    "delivery_title": "Mister",
    "delivery_firstname": "Max",
    "delivery_lastname": "Mustermann",
    "delivery_street": "Lieferweg 5",
    "delivery_zipcode": "54321",
    "delivery_city": "Lieferstadt",
    "delivery_country": "de",
    "delivery_phone": "+49 987 6543210",
    "account_iban": "DE89370400440532013000",
    "account_bic": "COBADEFFXXX",
    "account_bank": "Commerzbank",
    "account_paypal": "max.paypal@example.com",
    "user_note": "Kunde möchte Rechnung nur per E-Mail erhalten",
    "public_authority_id": ""
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'customer.create',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "customer_type": "billware",
    "is_business_client": 0,
    "bill_title": "Mister",
    "bill_firstname": "Max",
    "bill_lastname": "Mustermann",
    "bill_street": "Musterstraße 12",
    "bill_zipcode": "12345",
    "bill_city": "Musterstadt",
    "bill_country": "de",
    "bill_phone": "+49 123 4567890",
    "bill_email": "max.mustermann@example.com",
    "divergent_delivery_address": 1,
    "delivery_title": "Mister",
    "delivery_firstname": "Max",
    "delivery_lastname": "Mustermann",
    "delivery_street": "Lieferweg 5",
    "delivery_zipcode": "54321",
    "delivery_city": "Lieferstadt",
    "delivery_country": "de",
    "delivery_phone": "+49 987 6543210",
    "account_iban": "DE89370400440532013000",
    "account_bic": "COBADEFFXXX",
    "account_bank": "Commerzbank",
    "account_paypal": "max.paypal@example.com",
    "user_note": "Kunde möchte Rechnung nur per E-Mail erhalten",
    "public_authority_id": "",
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "customer.create",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    customer_type = "billware",
    is_business_client = 0,
    bill_title = "Mister",
    bill_firstname = "Max",
    bill_lastname = "Mustermann",
    bill_street = "Musterstraße 12",
    bill_zipcode = "12345",
    bill_city = "Musterstadt",
    bill_country = "de",
    bill_phone = "+49 123 4567890",
    bill_email = "max.mustermann@example.com",
    divergent_delivery_address = 1,
    delivery_title = "Mister",
    delivery_firstname = "Max",
    delivery_lastname = "Mustermann",
    delivery_street = "Lieferweg 5",
    delivery_zipcode = "54321",
    delivery_city = "Lieferstadt",
    delivery_country = "de",
    delivery_phone = "+49 987 6543210",
    account_iban = "DE89370400440532013000",
    account_bic = "COBADEFFXXX",
    account_bank = "Commerzbank",
    account_paypal = "max.paypal@example.com",
    user_note = "Kunde möchte Rechnung nur per E-Mail erhalten",
    public_authority_id = ""
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "customer.create");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Step 2: order.create

Create the order with the customer identifier and the positions. Prices are net prices per unit, quantities are numbers. Keep order_ident. With customer_reference the order number of your shop appears on the invoice.

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"customer_ident":"46yq1898qmohrz57","order_date":"2025-07-16 10:00:00","due_date":"2025-07-30 00:00:00","is_paid":0,"invoice_number":null,"is_quotation":0,"small_entrepreneur":0,"reverse_charge":0,"intra_community":0,"term_of_credit":14,"user_note":"Bitte schnell liefern – Kaninchenstall wird dringend benötigt!","customer_reference":"PO-2025-4711","discount":{"title":"Sonderrabatt","calculation_type":0,"price_type":1,"value":10},"payment":{"name":"Vorkasse","calculation_type":1,"price_type":1,"value":0,"cashback_active":0,"cashback":0,"cashback_days":0},"shipping":{"name":"DHL Paket","tracking":"1234567890","calculation_type":1,"price_type":1,"value":5.99},"articles":[{"article_title":"Kaninchenstall XL","article_purchase_price":75,"article_price":129.99,"article_quantity":1,"article_country":"de","article_tax_rate":19,"article_subtitle":"Wetterfest mit Auslauf","article_position":1,"article_unit":"unit_ppu","article_ean":"4012345678901","article_nr":"KAN-XL-2025"}]}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.create" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'customer_ident' => '46yq1898qmohrz57',
    'order_date' => '2025-07-16 10:00:00',
    'due_date' => '2025-07-30 00:00:00',
    'is_paid' => 0,
    'invoice_number' => null,
    'is_quotation' => 0,
    'small_entrepreneur' => 0,
    'reverse_charge' => 0,
    'intra_community' => 0,
    'term_of_credit' => 14,
    'user_note' => 'Bitte schnell liefern – Kaninchenstall wird dringend benötigt!',
    'customer_reference' => 'PO-2025-4711',
    'discount' => [
        'title' => 'Sonderrabatt',
        'calculation_type' => 0,
        'price_type' => 1,
        'value' => 10,
    ],
    'payment' => [
        'name' => 'Vorkasse',
        'calculation_type' => 1,
        'price_type' => 1,
        'value' => 0,
        'cashback_active' => 0,
        'cashback' => 0,
        'cashback_days' => 0,
    ],
    'shipping' => [
        'name' => 'DHL Paket',
        'tracking' => '1234567890',
        'calculation_type' => 1,
        'price_type' => 1,
        'value' => 5.99,
    ],
    'articles' => [
        [
            'article_title' => 'Kaninchenstall XL',
            'article_purchase_price' => 75,
            'article_price' => 129.99,
            'article_quantity' => 1,
            'article_country' => 'de',
            'article_tax_rate' => 19,
            'article_subtitle' => 'Wetterfest mit Auslauf',
            'article_position' => 1,
            'article_unit' => 'unit_ppu',
            'article_ean' => '4012345678901',
            'article_nr' => 'KAN-XL-2025',
        ],
    ],
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.create',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "customer_ident": "46yq1898qmohrz57",
    "order_date": "2025-07-16 10:00:00",
    "due_date": "2025-07-30 00:00:00",
    "is_paid": 0,
    "invoice_number": null,
    "is_quotation": 0,
    "small_entrepreneur": 0,
    "reverse_charge": 0,
    "intra_community": 0,
    "term_of_credit": 14,
    "user_note": "Bitte schnell liefern – Kaninchenstall wird dringend benötigt!",
    "customer_reference": "PO-2025-4711",
    "discount": {
        "title": "Sonderrabatt",
        "calculation_type": 0,
        "price_type": 1,
        "value": 10
    },
    "payment": {
        "name": "Vorkasse",
        "calculation_type": 1,
        "price_type": 1,
        "value": 0,
        "cashback_active": 0,
        "cashback": 0,
        "cashback_days": 0
    },
    "shipping": {
        "name": "DHL Paket",
        "tracking": "1234567890",
        "calculation_type": 1,
        "price_type": 1,
        "value": 5.99
    },
    "articles": [
        {
            "article_title": "Kaninchenstall XL",
            "article_purchase_price": 75,
            "article_price": 129.99,
            "article_quantity": 1,
            "article_country": "de",
            "article_tax_rate": 19,
            "article_subtitle": "Wetterfest mit Auslauf",
            "article_position": 1,
            "article_unit": "unit_ppu",
            "article_ean": "4012345678901",
            "article_nr": "KAN-XL-2025"
        }
    ]
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.create',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "customer_ident": "46yq1898qmohrz57",
    "order_date": "2025-07-16 10:00:00",
    "due_date": "2025-07-30 00:00:00",
    "is_paid": 0,
    "invoice_number": None,
    "is_quotation": 0,
    "small_entrepreneur": 0,
    "reverse_charge": 0,
    "intra_community": 0,
    "term_of_credit": 14,
    "user_note": "Bitte schnell liefern – Kaninchenstall wird dringend benötigt!",
    "customer_reference": "PO-2025-4711",
    "discount": {
        "title": "Sonderrabatt",
        "calculation_type": 0,
        "price_type": 1,
        "value": 10,
    },
    "payment": {
        "name": "Vorkasse",
        "calculation_type": 1,
        "price_type": 1,
        "value": 0,
        "cashback_active": 0,
        "cashback": 0,
        "cashback_days": 0,
    },
    "shipping": {
        "name": "DHL Paket",
        "tracking": "1234567890",
        "calculation_type": 1,
        "price_type": 1,
        "value": 5.99,
    },
    "articles": [
        {
            "article_title": "Kaninchenstall XL",
            "article_purchase_price": 75,
            "article_price": 129.99,
            "article_quantity": 1,
            "article_country": "de",
            "article_tax_rate": 19,
            "article_subtitle": "Wetterfest mit Auslauf",
            "article_position": 1,
            "article_unit": "unit_ppu",
            "article_ean": "4012345678901",
            "article_nr": "KAN-XL-2025",
        },
    ],
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.create",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    customer_ident = "46yq1898qmohrz57",
    order_date = "2025-07-16 10:00:00",
    due_date = "2025-07-30 00:00:00",
    is_paid = 0,
    invoice_number = (string)null,
    is_quotation = 0,
    small_entrepreneur = 0,
    reverse_charge = 0,
    intra_community = 0,
    term_of_credit = 14,
    user_note = "Bitte schnell liefern – Kaninchenstall wird dringend benötigt!",
    customer_reference = "PO-2025-4711",
    discount = new
    {
        title = "Sonderrabatt",
        calculation_type = 0,
        price_type = 1,
        value = 10
    },
    payment = new
    {
        name = "Vorkasse",
        calculation_type = 1,
        price_type = 1,
        value = 0,
        cashback_active = 0,
        cashback = 0,
        cashback_days = 0
    },
    shipping = new
    {
        name = "DHL Paket",
        tracking = "1234567890",
        calculation_type = 1,
        price_type = 1,
        value = 5.99
    },
    articles = new[]
    {
        new
        {
            article_title = "Kaninchenstall XL",
            article_purchase_price = 75,
            article_price = 129.99,
            article_quantity = 1,
            article_country = "de",
            article_tax_rate = 19,
            article_subtitle = "Wetterfest mit Auslauf",
            article_position = 1,
            article_unit = "unit_ppu",
            article_ean = "4012345678901",
            article_nr = "KAN-XL-2025"
        }
    }
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.create");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Step 3: order.sendDocument

Once the goods are shipped, let billware create the invoice and send it to the billing email address of the order. One call: the invoice number is drawn, the PDF is built with your layout and sent with your mail template.

order.sendDocument (invoice)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"order_ident":"aswm5o5i2v5hwlbp","type":"invoice"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.sendDocument" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'order_ident' => 'aswm5o5i2v5hwlbp',
    'type' => 'invoice',
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.sendDocument',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "invoice"
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.sendDocument',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "invoice",
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.sendDocument",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    order_ident = "aswm5o5i2v5hwlbp",
    type = "invoice"
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.sendDocument");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

The answer carries document_nr, the invoice number, and under file the link to the PDF in case your shop wants to store the invoice itself. A second call sends nothing twice, it is refused with the time of the first sending. To only create the invoice and send it yourself, use order.createDocument instead of order.sendDocument.

Payment first, then the invoice

With prepayment or pickup the invoice should only exist once the money is there. Book the payment with order.createPayment and set_paid set to 1; the order counts as paid and the invoice shows the payment. Then order.sendDocument as above.

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"order_ident":"aswm5o5i2v5hwlbp","amount":144.61,"fee":0,"payment_name":"payment_paypal","date_paid":"2025-07-16 12:30:00","external_ident":"TRANS123456","set_paid":1}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.createPayment" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'order_ident' => 'aswm5o5i2v5hwlbp',
    'amount' => 144.61,
    'fee' => 0,
    'payment_name' => 'payment_paypal',
    'date_paid' => '2025-07-16 12:30:00',
    'external_ident' => 'TRANS123456',
    'set_paid' => 1,
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.createPayment',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "order_ident": "aswm5o5i2v5hwlbp",
    "amount": 144.61,
    "fee": 0,
    "payment_name": "payment_paypal",
    "date_paid": "2025-07-16 12:30:00",
    "external_ident": "TRANS123456",
    "set_paid": 1
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.createPayment',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "order_ident": "aswm5o5i2v5hwlbp",
    "amount": 144.61,
    "fee": 0,
    "payment_name": "payment_paypal",
    "date_paid": "2025-07-16 12:30:00",
    "external_ident": "TRANS123456",
    "set_paid": 1,
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.createPayment",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    order_ident = "aswm5o5i2v5hwlbp",
    amount = 144.61,
    fee = 0,
    payment_name = "payment_paypal",
    date_paid = "2025-07-16 12:30:00",
    external_ident = "TRANS123456",
    set_paid = 1
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.createPayment");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

A payment arriving after the invoice is booked the same way. The open amount is in order.read under booked_payments.open_amount.

Delivery note and partial delivery

A delivery note for the whole order comes with type delivery_note, once per order. When the goods leave in several parcels, create a partial delivery note per shipment with partial_delivery_note and the positions of that shipment; every call is a new document with a running number. Both can be mailed with order.sendDocument as well.

order.createDocument (partial delivery note)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"order_ident":"aswm5o5i2v5hwlbp","type":"partial_delivery_note","date_delivery_note":"2025-07-18 09:00:00","articles":[{"article_title":"Kaninchenstall XL","article_quantity":1}]}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.createDocument" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'order_ident' => 'aswm5o5i2v5hwlbp',
    'type' => 'partial_delivery_note',
    'date_delivery_note' => '2025-07-18 09:00:00',
    'articles' => [
        [
            'article_title' => 'Kaninchenstall XL',
            'article_quantity' => 1,
        ],
    ],
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.createDocument',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "partial_delivery_note",
    "date_delivery_note": "2025-07-18 09:00:00",
    "articles": [
        {
            "article_title": "Kaninchenstall XL",
            "article_quantity": 1
        }
    ]
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.createDocument',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "partial_delivery_note",
    "date_delivery_note": "2025-07-18 09:00:00",
    "articles": [
        {
            "article_title": "Kaninchenstall XL",
            "article_quantity": 1,
        },
    ],
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.createDocument",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    order_ident = "aswm5o5i2v5hwlbp",
    type = "partial_delivery_note",
    date_delivery_note = "2025-07-18 09:00:00",
    articles = new[]
    {
        new
        {
            article_title = "Kaninchenstall XL",
            article_quantity = 1
        }
    }
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.createDocument");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Cancellation: create and send the reversal invoice

When an order is cancelled after the invoice, reversal_invoice creates the reversal invoice with the invoice number and the suffix -S and sets the order to cancelled. An existing invoice is required. With order.sendDocument it goes straight to the customer.

order.sendDocument (reversal invoice)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"order_ident":"aswm5o5i2v5hwlbp","type":"reversal_invoice"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.sendDocument" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'order_ident' => 'aswm5o5i2v5hwlbp',
    'type' => 'reversal_invoice',
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.sendDocument',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "reversal_invoice"
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.sendDocument',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "reversal_invoice",
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.sendDocument",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    order_ident = "aswm5o5i2v5hwlbp",
    type = "reversal_invoice"
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.sendDocument");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

A cancelled order gets no new invoice. If the same customer orders again, create a new order.

Partial return: credit note with positions

When part of the goods comes back, credit_note creates the credit note. Without articles the whole order is credited; for a partial return give the positions taken back, the quantity negative, price and tax rate as on the invoice. The number is the invoice number with the suffix -K, an order has one credit note.

order.createDocument (credit note for one position)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"order_ident":"aswm5o5i2v5hwlbp","type":"credit_note","date_credit_note":"2025-07-20 10:00:00","articles":[{"article_title":"Kaninchenstall XL","article_quantity":-1,"article_price":129.99,"article_tax_rate":19,"article_unit":"unit_ppu","article_nr":"KAN-XL-2025"}]}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.createDocument" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'order_ident' => 'aswm5o5i2v5hwlbp',
    'type' => 'credit_note',
    'date_credit_note' => '2025-07-20 10:00:00',
    'articles' => [
        [
            'article_title' => 'Kaninchenstall XL',
            'article_quantity' => -1,
            'article_price' => 129.99,
            'article_tax_rate' => 19,
            'article_unit' => 'unit_ppu',
            'article_nr' => 'KAN-XL-2025',
        ],
    ],
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.createDocument',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "credit_note",
    "date_credit_note": "2025-07-20 10:00:00",
    "articles": [
        {
            "article_title": "Kaninchenstall XL",
            "article_quantity": -1,
            "article_price": 129.99,
            "article_tax_rate": 19,
            "article_unit": "unit_ppu",
            "article_nr": "KAN-XL-2025"
        }
    ]
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.createDocument',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "credit_note",
    "date_credit_note": "2025-07-20 10:00:00",
    "articles": [
        {
            "article_title": "Kaninchenstall XL",
            "article_quantity": -1,
            "article_price": 129.99,
            "article_tax_rate": 19,
            "article_unit": "unit_ppu",
            "article_nr": "KAN-XL-2025",
        },
    ],
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.createDocument",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    order_ident = "aswm5o5i2v5hwlbp",
    type = "credit_note",
    date_credit_note = "2025-07-20 10:00:00",
    articles = new[]
    {
        new
        {
            article_title = "Kaninchenstall XL",
            article_quantity = -1,
            article_price = 129.99,
            article_tax_rate = 19,
            article_unit = "unit_ppu",
            article_nr = "KAN-XL-2025"
        }
    }
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.createDocument");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Book the refund to the customer with order.createPayment and a negative amount.

Reminders in three levels

When an invoice stays open, order.sendDocument with reminder_1 creates and sends the first reminder, later reminder_2 and reminder_3. The reminder fees come from your settings. The levels keep their order, and a paid order is not reminded: book payments with order.createPayment, then billware refuses the reminder by itself.

order.sendDocument (first reminder)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"order_ident":"aswm5o5i2v5hwlbp","type":"reminder_1"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: order.sendDocument" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

<?php

// Get your API credentials from your billware customer area
$apiAppId  = 'your-app-id';
$apiSecret = 'your-api-secret';

$payload = json_encode([
    'order_ident' => 'aswm5o5i2v5hwlbp',
    'type' => 'reminder_1',
]);

// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://www.billware.de/api/v1',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
        'X-Bw-Method: order.sendDocument',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

print_r(json_decode($response, true));

import crypto from 'node:crypto';

// Get your API credentials from your billware customer area
const apiAppId  = 'your-app-id';
const apiSecret = 'your-api-secret';

const payload = JSON.stringify({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "reminder_1"
});

// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

const response = await fetch('https://www.billware.de/api/v1', {
    method: 'POST',
    headers: {
        'X-Bw-Hmac': `${apiAppId}:${hmac}`,
        'X-Bw-Method': 'order.sendDocument',
        'Content-Type': 'application/json'
    },
    body: payload
});

console.log(await response.json());

import base64
import hashlib
import hmac
import json

import requests

# Get your API credentials from your billware customer area
api_appid  = "your-app-id"
api_secret = "your-api-secret"

payload = json.dumps({
    "order_ident": "aswm5o5i2v5hwlbp",
    "type": "reminder_1",
})

# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://www.billware.de/api/v1",
    data=payload,
    headers={
        "X-Bw-Hmac": f"{api_appid}:{signature}",
        "X-Bw-Method": "order.sendDocument",
        "Content-Type": "application/json",
    },
)

print(response.json())

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API credentials from your billware customer area
const string apiAppId  = "your-app-id";
const string apiSecret = "your-api-secret";

var payload = JsonSerializer.Serialize(new
{
    order_ident = "aswm5o5i2v5hwlbp",
    type = "reminder_1"
});

// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
    Content = new StringContent(payload, Encoding.UTF8, "application/json")
};

request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "order.sendDocument");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Which orders are open, order.list tells with date_type date_invoice; open orders have an empty date_paid.

Pitfalls

Country codes in lower case (de, at). Upper case is stored in lower case, but your data stays clean when you send it right away.
Retries are safe: order.createDocument returns the existing document, order.sendDocument refuses the second sending. Only order.create creates a new order with every call, so keep the identifier before you try again.
You no longer need order.createInvoiceNr: the invoice number is drawn when the invoice is created. Use it only to assign a number of your own.
The mail goes to bill_email of the order. Without the address the document is created but not sent; the message says so.
The call limit counts every call, refused ones too. For many orders order.list is cheaper than many single order.read.
Send date and time as YYYY-MM-DD HH:MM:SS in the time zone of your account.