billware API | Documentation / Customers

Customers

customer.create

Create a new customer.

Data

Fields	Description	Accepted Types	Defaults To
external_ident	If the customer was imported from e.g. ebay, this is the unique identifier provided by the source	`String`	`""`
external_account_name	If the customer was imported from e.g. ebay, this is the name of the ebay account	`String`	`""`
customer_type	Indicates the source of the customer, e.g. "amazon"	`String`	`"billware"`
customer_nr	Customer Number, if empty or not set a customer number will be generated	`String`	`Generated Number`
is_business_client	Indicates if the customer is a business client	`0 No` `1 Yes`	`0`
bill_title	Title of the customer	`-1 Company` `0 Mister` `1 Miss` `2 Diverse` `3 No title` `4 Family` `5 Couple` `6 Doctor` `7 Professor`	`-1`
bill_firstname	Firstname	`String`	`""`
bill_lastname	Lastname	`String`	`""`
bill_company	Company name	`String`	`""`
bill_vat_nr	VAT number of the customer	`String`	`""`
bill_street	Street	`String`	`""`
bill_street2	Addition to the address	`String`	`""`
bill_zipcode	Zipcode	`String`	`""`
bill_city	City	`String`	`""`
bill_country	Country code (ISO 3166 ALPHA-2)	`String`	`""`
bill_phone	Phone number	`String`	`""`
bill_phone_mobile	Mobile phone number	`String`	`""`
bill_email	E-Mail address	`String`	`""`
divergent_delivery_address	Indicates if a delivery address should be created for this customer	`0 No` `1 Yes`	`0`
delivery_title	Delivery Address: Title of the customer	`-1 Company` `0 Mister` `1 Miss` `2 Diverse` `3 No title` `4 Family` `5 Couple` `6 Doctor` `7 Professor`	`-1`
delivery_firstname	Delivery Address: Firstname	`String`	`""`
delivery_lastname	Delivery Address: Lastname	`String`	`""`
delivery_company	Delivery Address: Company name	`String`	`""`
delivery_street	Delivery Address: Street	`String`	`""`
delivery_street2	Delivery Address: Addition to the address	`String`	`""`
delivery_zipcode	Delivery Address: Zipcode	`String`	`""`
delivery_city	Delivery Address: City	`String`	`""`
delivery_country	Delivery Address: Country code (ISO 3166 ALPHA-2)	`String`	`"de"`
delivery_phone	Delivery Address: Phone number	`String`	`""`
delivery_phone_mobile	Delivery Address: Mobile phone number	`String`	`""`
account_bank	Name of the bank	`String`	`""`
account_bic	BIC of the bank	`String`	`""`
account_iban	IBAN of the customer's bank account	`String`	`""`
account_paypal	PayPal account of the customer	`String`	`""`
term_of_credit	The term of credit granted in days	`Integer`	The default term of credit defined in your billware configuration
user_note	Optional internal note about this customer	`String`	`""`

Code Examples

# 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":"[email protected]","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":"[email protected]","user_note":"Kunde möchte Rechnung nur per E-Mail erhalten"}'

# 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' => '[email protected]',
    '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' => '[email protected]',
    'user_note' => 'Kunde möchte Rechnung nur per E-Mail erhalten',
]);

// 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": "[email protected]",
    "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": "[email protected]",
    "user_note": "Kunde möchte Rechnung nur per E-Mail erhalten"
});

// 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": "[email protected]",
    "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": "[email protected]",
    "user_note": "Kunde möchte Rechnung nur per E-Mail erhalten",
})

# 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 = "[email protected]",
    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 = "[email protected]",
    user_note = "Kunde möchte Rechnung nur per E-Mail erhalten"
});

// 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());

Return Values

Fields	Description
customer_ident	Identifier of the created customer
address_ident	Identifier of the created delivery address. If divergent_delivery_address is set to `0`, the returned value will be `NULL`

Example Responses

	// SUCCESS creating a customer with a delivery address
{
	"response":true,
	"data":{
		"customer_ident":"30818cqJ36X624SC",
		"address_ident":"61636lu6Et7324W8"
	},
	"method":"customer.create",
	"message":"customer created"
}

customer.read

Get the details of a customer.

Data

Fields	Description	Accepted Types
customer_ident Required	Identifier of the customer	`String`

Code Examples

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57"}'

# 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.read" \
  -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',
]);

// 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.read',
        '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"
});

// 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.read',
        '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",
})

# 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.read",
        "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"
});

// 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.read");

var response = await client.SendAsync(request);

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

Return Values

Fields	Description	Type
customer_ident	Identifier of the customer	`String`
external_ident	If the customer was imported from e.g. ebay, this is the unique identifier provided by the source	`String`
external_account_name	If the customer was imported from e.g. ebay, this is the name of the ebay account	`String`
external_username	If the customer was imported from e.g. ebay, this is the username of the customer	`String`
date_created	Date and time when the customer was created	`Date as String`
date_created_user	Date when the customer was created in user format, e.g. "19.10.2018"	`Date as String`
date_updated	Date and time when the customer was last updated	`Date as String`
date_updated_user	Date when the customer was updated in user format, e.g. "19.10.2018"	`Date as String`
customer_type	Source of the customer, e.g. "amazon"	`String`
customer_nr	The customer number	`String`
is_business_client	Indicates if the customer is a business client	`0 No` `1 Yes`
bill_title	Title of the customer	`-1 Company` `0 Mister` `1 Miss` `2 Diverse` `3 No title` `4 Family` `5 Couple` `6 Doctor` `7 Professor`
bill_firstname	Firstname	`String`
bill_lastname	Lastname	`String`
bill_company	Company name	`String`
bill_vat_nr	VAT number	`String`
bill_street	Street	`String`
bill_street2	Addition to the address	`String`
bill_zipcode	Zipcode	`String`
bill_city	City	`String`
bill_country	Country code (ISO 3166 ALPHA-2)	`String`
bill_email	E-mail address	`String`
bill_phone	Phone number	`String`
bill_phone_mobile	Mobile phone number	`String`
account_bank	Name of the bank	`String`
account_bic	BIC of the bank	`String`
account_iban	IBAN of the customer's bank account	`String`
account_paypal	PayPal account of the customer	`String`
term_of_credit	The term of credit granted in days	`Integer`
user_note	Internal note about this customer	`String`
address_data	Array of customer addresses	`Array`
[KEYS]	Array Element holding address fields	`Array Key`
address_ident	Identifier of the address	`String`
customer_ident	Identifier of the customer this address belongs to	`String`
delivery_title	Title of the customer	`-1 Company` `0 Mister` `1 Miss` `2 Diverse` `3 No title` `4 Family` `5 Couple` `6 Doctor` `7 Professor`
delivery_firstname	Firstname	`String`
delivery_lastname	Lastname	`String`
delivery_company	Company name	`String`
delivery_company	Company name	`String`
delivery_street	Street	`String`
delivery_street2	Addition to the address	`String`
delivery_zipcode	Zipcode	`String`
delivery_city	City	`String`
delivery_country	Country code (ISO 3166 ALPHA-2)	`String`
delivery_phone	Phone number	`String`
delivery_phone_mobile	Mobile phone number	`String`

Example Responses

	// SUCCESS
{
	"response": true,
	"data":
	{
		"customer":
		{
			"customer_ident": "3081k634q51Cw12v",
			"date_created": "2018-10-29 12:52:36",
			"date_updated": "2018-10-29 12:52:36",
			"external_ident": "",
			"external_account_name": "",
			"external_username": "",
			"customer_nr": "K-0025",
			"customer_type": "billware",
			"is_business_client": "1",
			"bill_title": "-1",
			"bill_firstname": "Max",
			"bill_lastname": "Mustermann",
			"bill_company": "Musterfirma Ltd.",
			"bill_vat_nr": "GB999999999",
			"bill_street": "23 Queen Victoria Street",
			"bill_street2": "",
			"bill_zipcode": "EC4N 4TR",
			"bill_city": "London",
			"bill_country": "gb",
			"bill_phone": "+4402043321",
			"bill_phone_mobile": "",
			"bill_email": "[email protected]",
			"user_note": "",
			"account_number": "",
			"account_bank": "",
			"account_bank_code": "",
			"account_iban": "",
			"account_bic": "",
			"account_paypal": "[email protected]",
			"term_of_credit": "30",
			"date_created_user": "29.10.2018",
			"date_updated_user": "29.10.2018"
		},
		"address_data": [
		{
			"address_ident": "6Cl11E63987I9680",
			"customer_ident": "3081k634q51Cw12v",
			"date_created": "2018-10-31 14:43:15",
			"date_updated": "2018-10-31 14:43:15",
			"delivery_firstname": "Maria",
			"delivery_lastname": "Mustermann",
			"delivery_company": "",
			"delivery_street": "23 Queensway",
			"delivery_street2": "",
			"delivery_zipcode": "W2 4QJ",
			"delivery_city": "London",
			"delivery_country": "gb",
			"delivery_phone": "",
			"delivery_phone_mobile": "",
			"delivery_title": "1"
		}]
	},
	"method": "customer.read",
	"message": "customer and address data loaded"
}

customer.update

Update one or more attributes of a customer.

Data

Fields	Description	Accepted Types
customer_ident Required	Identifier of the customer	`String`
validate	Call will return without updating if the specified value already exists. Otherwise the customer will be updated. See example below.	`Field` Example: customer_nr
[Other Fields]	See customer.create

Write protected

Fields	Description
customer_ident	Internal identifier
external_ident	Internal identifier
external_account_name	Internal identifier
date_created_user	Calculated automatically, update date_created instead (UTC)
date_updated	Calculated automatically
date_updated_user	Calculated automatically
address_data	Use function address.create instead

Code Examples

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57","bill_firstname":"Moritz"}'

# 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.update" \
  -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',
    'bill_firstname' => 'Moritz',
]);

// 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.update',
        '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",
    "bill_firstname": "Moritz"
});

// 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.update',
        '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",
    "bill_firstname": "Moritz",
})

# 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.update",
        "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",
    bill_firstname = "Moritz"
});

// 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.update");

var response = await client.SendAsync(request);

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

Response Data

Fields	Description	Type
response	Indicating if the action was successful	`true` `false`
data	Array with response data	`Array`
customer_ident	The identifier of the updated customer	`String`
[fields]	All the updated and sanitized fields
method	customer.update	`String`
message	Additional information about the request	`String`

Example Responses

	// SUCCESS after updating the customer term of credit
{
	"response":true,
	"data": {
		"customer_ident" : "30Wp80787u99z2qv",
		"term_of_credit" : "20"
	},
	"method":"customer.update",
	"message":"customer updated"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"customer.update",
	"message":"customer not found"
}

customer.delete

Delete an existing customer.

Data

Fields	Description	Accepted Types
customer_ident Required	Identifier of the customer	`String`

Code Examples

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57"}'

# 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.delete" \
  -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',
]);

// 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.delete',
        '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"
});

// 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.delete',
        '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",
})

# 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.delete",
        "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"
});

// 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.delete");

var response = await client.SendAsync(request);

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

Example Responses

	// SUCCESS
{
	"response":true,
	"data":null,
	"method":"customer.delete",
	"message":"customer deleted"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"customer.delete",
	"message":"customer not found"
}

customer.exists

Check if a customer exists.

Data

Fields	Description	Accepted Types
customer_ident Required	Identifier of the customer	`String`

Code Examples

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57"}'

# 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.exists" \
  -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',
]);

// 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.exists',
        '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"
});

// 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.exists',
        '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",
})

# 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.exists",
        "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"
});

// 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.exists");

var response = await client.SendAsync(request);

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

Example Responses

	// SUCCESS
{
	"response":true,
	"data": {
		"customer_ident" : "30Wp80787u99z2qv"
	},
	"method":"customer.exists",
	"message":"customer does exist"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"customer.exists",
	"message":"customer does not exist"
}

address.create

Create a new delivery address for a customer.

Data

Fields	Description	Accepted Types	Defaults To
customer_ident Required	Identifier of the customer	`String`
delivery_title	Title of the customer	`-1 Company` `0 Mister` `1 Miss` `2 Diverse` `3 No title` `4 Family` `5 Couple` `6 Doctor` `7 Professor`	`-1`
delivery_firstname	Firstname	`String`	`""`
delivery_lastname	Lastname	`String`	`""`
delivery_company	Company name	`String`	`""`
delivery_street	Street	`String`	`""`
delivery_street2	Addition to the address	`String`	`""`
delivery_zipcode	Zipcode	`String`	`""`
delivery_city	City	`String`	`""`
delivery_country	Country code (ISO 3166 ALPHA-2)	`String`	`"de"`
delivery_phone	Phone number	`String`	`""`
delivery_phone_mobile	Mobile phone number	`String`	`""`

Code Examples

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57","delivery_title":0,"delivery_firstname":"Max","delivery_lastname":"Mustermann","delivery_company":"Muster GmbH","delivery_street":"Lieferweg 5","delivery_street2":"Etage 3","delivery_zipcode":"54321","delivery_city":"Lieferstadt","delivery_country":"DE","delivery_phone":"+49 987 6543210","delivery_phone_mobile":"+49 171 1234567"}'

# 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: address.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',
    'delivery_title' => 0,
    'delivery_firstname' => 'Max',
    'delivery_lastname' => 'Mustermann',
    'delivery_company' => 'Muster GmbH',
    'delivery_street' => 'Lieferweg 5',
    'delivery_street2' => 'Etage 3',
    'delivery_zipcode' => '54321',
    'delivery_city' => 'Lieferstadt',
    'delivery_country' => 'DE',
    'delivery_phone' => '+49 987 6543210',
    'delivery_phone_mobile' => '+49 171 1234567',
]);

// 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: address.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",
    "delivery_title": 0,
    "delivery_firstname": "Max",
    "delivery_lastname": "Mustermann",
    "delivery_company": "Muster GmbH",
    "delivery_street": "Lieferweg 5",
    "delivery_street2": "Etage 3",
    "delivery_zipcode": "54321",
    "delivery_city": "Lieferstadt",
    "delivery_country": "DE",
    "delivery_phone": "+49 987 6543210",
    "delivery_phone_mobile": "+49 171 1234567"
});

// 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': 'address.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",
    "delivery_title": 0,
    "delivery_firstname": "Max",
    "delivery_lastname": "Mustermann",
    "delivery_company": "Muster GmbH",
    "delivery_street": "Lieferweg 5",
    "delivery_street2": "Etage 3",
    "delivery_zipcode": "54321",
    "delivery_city": "Lieferstadt",
    "delivery_country": "DE",
    "delivery_phone": "+49 987 6543210",
    "delivery_phone_mobile": "+49 171 1234567",
})

# 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": "address.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",
    delivery_title = 0,
    delivery_firstname = "Max",
    delivery_lastname = "Mustermann",
    delivery_company = "Muster GmbH",
    delivery_street = "Lieferweg 5",
    delivery_street2 = "Etage 3",
    delivery_zipcode = "54321",
    delivery_city = "Lieferstadt",
    delivery_country = "DE",
    delivery_phone = "+49 987 6543210",
    delivery_phone_mobile = "+49 171 1234567"
});

// 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", "address.create");

var response = await client.SendAsync(request);

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

Return Values

Fields	Description
address_ident	Identifier of the created address
customer_ident	Identifier of the customer who owns this address

Example Responses

	// SUCCESS
{
	"response":true,
	"data":{
		"customer_ident":"30818cqJ36X624SC",
		"address_ident":"61636lu6Et7324W8"
	},
	"method":"address.create",
	"message":"address created"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"address.create",
	"message":"customer_ident not set"
}

address.exists

Check if a delivery address exists.

Data

Fields	Description	Accepted Types
address_ident Required	Identifier of the delivery address	`String`

Code Examples

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

PAYLOAD='{"address_ident":"61636lu6Et7324W8"}'

# 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: address.exists" \
  -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([
    'address_ident' => '61636lu6Et7324W8',
]);

// 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: address.exists',
        '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({
    "address_ident": "61636lu6Et7324W8"
});

// 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': 'address.exists',
        '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({
    "address_ident": "61636lu6Et7324W8",
})

# 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": "address.exists",
        "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
{
    address_ident = "61636lu6Et7324W8"
});

// 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", "address.exists");

var response = await client.SendAsync(request);

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

Example Responses

// SUCCESS
{
    "response": true,
    "data": {
        "address_ident": "61636lu6Et7324W8"
    },
    "method": "address.exists",
    "message": "address does exist"
}

// ERROR – the request itself was fine, the address is unknown
{
    "response": false,
    "data": {
        "address_ident": "61636lu6Et7324W8"
    },
    "method": "address.exists",
    "message": "address does not exist"
}