Skip to content

Lösungen

Freelancer & Selbstständige Rechnungen und Belege ohne Shop eBay Verkäufe automatisch abrechnen Shopify Bestellungen direkt aus dem Shop WooCommerce WordPress-Shop anbinden

Suppliers

With these methods you maintain the suppliers of your account and their documents, for example contracts and price lists. You link a supplier to an expense by supplier_ident, see Expenses.

Note

The methods need the extension Suppliers. If it is not active for your account, each of them answers with 403. What cannot be stored the way you send it is refused with the reason: nothing is cut or dropped silently. Lengths count the stored form: billware stores text the way the customer area does, there & takes five characters, < and > four each, " and ' six each.

supplier.create

Create a new supplier.

Data

Fields Description Accepted Types Defaults To
bill_company Company name, 128 characters at most. String ""
bill_firstname First name, 64 characters at most. String ""
bill_lastname Last name, 64 characters at most. String ""
bill_email E-mail address, 256 characters at most. It has to be a valid address. String ""
bill_title Title -1 Company 0 Mister 1 Miss 2 Diverse 3 No title 4 Family 5 Couple 6 Doctor 7 Professor 3
supplier_nr Supplier number, 32 characters at most. It may exist only once in the account. Without it billware assigns the next number of your number range. String Generated Number
supplier_type Source of the supplier, 32 characters at most, e.g. the name of your system. String "billware"
external_ident Ident of the supplier in your system, 512 characters at most. You can filter by it in supplier.list. String ""
bill_vat_nr VAT number, 32 characters at most. String ""
bill_street Street and number, 128 characters at most. String ""
bill_street2 Addition to the address, 64 characters at most. String ""
bill_zipcode Zip code, 64 characters at most. String ""
bill_city City, 128 characters at most. String ""
bill_country Country code (ISO 3166 ALPHA-2), e.g. de. Upper case is stored in lower case. String The default country of your account
bill_phone Phone number, 64 characters at most. String ""
bill_phone_mobile Mobile phone number, 64 characters at most. String ""
account_bank Name of the bank, 128 characters at most. String ""
account_iban IBAN, 32 characters at most. String ""
account_bic BIC, 16 characters at most. String ""
account_paypal PayPal address of the supplier, 64 characters at most. It has to be a valid e-mail address. String ""
user_note Note, 1024 characters at most. String ""

One of the fields bill_company, bill_lastname or bill_email is required: a supplier needs something it can be told apart by.

Code Examples

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

PAYLOAD='{"bill_company":"Papier & Druck KG","bill_firstname":"Jörg","bill_lastname":"Becker","bill_title":-1,"bill_vat_nr":"DE123456789","bill_street":"Hauptstraße 5","bill_zipcode":"50667","bill_city":"Köln","bill_country":"de","bill_phone":"+49 221 123456","bill_email":"einkauf@papier-druck.example","account_bank":"Sparkasse KölnBonn","account_iban":"DE89370400440532013000","account_bic":"COBADEFFXXX","supplier_nr":"L-7001","external_ident":"ERP-4711","user_note":"Zahlungsziel 30 Tage"}'

# 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: supplier.create" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Return Values

The answer holds the created supplier with the same structure as supplier.read.

Example Responses


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "supplier_nr": "L-7001",
        "supplier_type": "billware",
        "external_ident": "ERP-4711",
        "bill_title": -1,
        "bill_firstname": "Jörg",
        "bill_lastname": "Becker",
        "bill_company": "Papier & Druck KG",
        "bill_vat_nr": "DE123456789",
        "bill_street": "Hauptstraße 5",
        "bill_street2": "",
        "bill_zipcode": "50667",
        "bill_city": "Köln",
        "bill_country": "de",
        "bill_phone": "+49 221 123456",
        "bill_phone_mobile": "",
        "bill_email": "einkauf@papier-druck.example",
        "account_bank": "Sparkasse KölnBonn",
        "account_iban": "DE89370400440532013000",
        "account_bic": "COBADEFFXXX",
        "account_paypal": "",
        "user_note": "Zahlungsziel 30 Tage",
        "date_created": "2026-11-16 10:30:09",
        "date_updated": "2026-11-16 10:30:09",
        "files": []
    },
    "message": "supplier created"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "A supplier needs bill_company, bill_lastname or bill_email"
}

supplier.read

Get a supplier with its documents.

Data

Fields Description Accepted Types
supplier_ident Required Ident of the supplier String

Code Examples

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

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054"}'

# 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: supplier.read" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Return Values

Fields Description
supplier_ident Ident of the supplier
supplier_nr Supplier number
supplier_type Source of the supplier
external_ident Ident of the supplier in your system
bill_title Title as a number, the values are listed at supplier.create
bill_*
account_*
user_note
Name, address, contact, bank details and note as you sent them
date_created
date_updated
Time of creation and of the last change in server time (UTC). A supplier you send again unchanged does not count as changed.
files The documents of the supplier, the oldest first, each as in the answer of supplier.fileUpload. The receipts of its expenses are not part of them, they belong to the expenses.

Example Responses


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "supplier_nr": "L-7001",
        "supplier_type": "billware",
        "external_ident": "ERP-4711",
        "bill_title": -1,
        "bill_firstname": "Jörg",
        "bill_lastname": "Becker",
        "bill_company": "Papier & Druck KG",
        "bill_vat_nr": "DE123456789",
        "bill_street": "Hauptstraße 5",
        "bill_street2": "",
        "bill_zipcode": "50667",
        "bill_city": "Köln",
        "bill_country": "de",
        "bill_phone": "+49 221 123456",
        "bill_phone_mobile": "",
        "bill_email": "einkauf@papier-druck.example",
        "account_bank": "Sparkasse KölnBonn",
        "account_iban": "DE89370400440532013000",
        "account_bic": "COBADEFFXXX",
        "account_paypal": "",
        "user_note": "Zahlungsziel 30 Tage",
        "date_created": "2026-11-16 10:30:09",
        "date_updated": "2026-11-16 10:30:09",
        "files": [
            {
                "href": "https://www.billware.de/file?t=...",
                "file_ident": "l51gvi7q0su56l44",
                "controller": "supplier",
                "parent_ident": "ckt8w78bfmj54054",
                "file_name": "file_43a37bf8fa591e73a5d091b47a7c5b1f87b52c40.pdf",
                "file_user_name": "Rahmenvertrag 2026.pdf",
                "file_type": "user",
                "file_extension": "pdf",
                "reference_nr": "L-7001",
                "date_updated": "2026-11-16 10:30:10",
                "date_updated_user": "16.11.2026"
            }
        ]
    },
    "message": "Read supplier with ident: ckt8w78bfmj54054"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Supplier not found"
}

supplier.list

Get multiple suppliers as a list.

Data

Fields Description Accepted Types Defaults To
date_type The date the period refers to and the list is sorted by, the newest first. "date_created" "date_updated" "date_created"
start_date Start of the period. Format: Y-m-d H:i:s (e.g. "2026-10-01 00:00:00"), compared with the stored times in server time (UTC). With date_type date_updated this gives you everything that has changed since a point in time. A new or deleted document does not change the supplier here. String
end_date End of the period, in the same format as start_date. String
supplier_nr Only the supplier with this number. String
supplier_type Only suppliers of this source. String
external_ident Only the supplier with this ident of your system. String
bill_email Only suppliers with this e-mail address. String
bill_company Only suppliers with exactly this company name. String
bill_vat_nr Only suppliers with this VAT number. String
bill_country Only suppliers of this country, as country code. String
page Page of the list. Without it the first page is returned. Integer 1
limit Number of entries per page, from 1 to 100. Integer 25

Every field is optional and they can be combined, a supplier then has to match every filter. Without any the list holds all suppliers of your account.

Code Examples

supplier.list

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

PAYLOAD='{"page":1,"limit":50}'

# 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: supplier.list" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

supplier.list (changed since)

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

PAYLOAD='{"date_type":"date_updated","start_date":"2026-11-01 00:00:00"}'

# 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: supplier.list" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Return Values

The suppliers array contains entries with the same structure as the answer of supplier.read.

Pagination

The response includes metadata to support pagination:

Use page to walk through the pages and limit to set how many entries a page holds. A page holds 100 entries at most, there is no limit in total: through the pages up to total_pages you reach every entry.

Example Responses


// SUCCESS
{
    "response": true,
    "data": {
        "page": 1,
        "limit": 25,
        "total": 12,
        "total_pages": 1,
        "suppliers": [
            {
                "supplier_ident": "ckt8w78bfmj54054",
                "supplier_nr": "L-7001",
                "bill_company": "Papier & Druck KG",
                ...
            },
            ...
        ]
    },
    "message": "Supplier list retrieved successfully"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Invalid date_type. Allowed: date_created, date_updated"
}

supplier.update

Update one or more fields of a supplier.

Data

Fields Description Accepted Types
supplier_ident Required Ident of the supplier String

Plus every field of supplier.create you want to change. Only fields you send change, an empty text empties the field. Number, title and country cannot be emptied.

Code Examples

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

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","bill_city":"Bonn","bill_zipcode":"53111"}'

# 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: supplier.update" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Return Values

The answer holds the supplier as it is now, with the same structure as supplier.read.

Example Responses


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "bill_city": "Bonn",
        ...
    },
    "message": "supplier updated"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "supplier_nr is taken already"
}

supplier.put

Create or update a supplier, in one call. This way you sync the suppliers of your system without storing their idents.

billware looks for the supplier in this order:

  1. by supplier_ident if you send it. If it does not exist, the call answers with an error and creates nothing.
  2. otherwise by bill_email,
  3. otherwise by bill_company.

A supplier that is found is changed as with supplier.update, otherwise a new one is created as with supplier.create. An empty text finds nobody. If several suppliers share the e-mail address or company, the one created first is changed.

Code Examples

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

PAYLOAD='{"bill_email":"einkauf@papier-druck.example","bill_company":"Papier & Druck KG","bill_phone":"+49 221 654321"}'

# 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: supplier.put" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Example Responses


// SUCCESS, the supplier was found
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "bill_email": "einkauf@papier-druck.example",
        "bill_phone": "+49 221 654321",
        ...
    },
    "message": "supplier updated"
}

// SUCCESS, the supplier was new
{
    "response": true,
    "data": {
        "supplier_ident": "9v6c1x0p4w7m2k8d",
        ...
    },
    "message": "supplier created"
}

supplier.delete

Delete a supplier with its documents. Its expenses stay, they have no supplier afterwards.

Data

Fields Description Accepted Types
supplier_ident Required Ident of the supplier String

Code Examples

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

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054"}'

# 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: supplier.delete" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Example Responses


// SUCCESS
{
    "response": true,
    "data": null,
    "message": "supplier deleted"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Supplier not found"
}

supplier.fileUpload

Store a document for a supplier.

Data

Fields Description Accepted Types Defaults To
supplier_ident Required Ident of the supplier String
file_base64 The content of the file, Base64 encoded. Either file_base64 or file_url, not both. String
file_url A link billware fetches the file from. https only, and only addresses that are publicly reachable. String
file_name Name of the file. Without it the document is called like the supplier number, e.g. L-7001.pdf. String The supplier number

Code Examples

supplier.fileUpload (Base64)

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

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","file_base64":"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyA+PgplbmRvYmoKdHJhaWxlcgo8PCAvUm9vdCAxIDAgUiA+PgolJUVPRgo=","file_name":"Rahmenvertrag 2026.pdf"}'

# 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: supplier.fileUpload" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

supplier.fileUpload (link)

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

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","file_url":"https://www.example.com/vertraege/rahmenvertrag-2026.pdf"}'

# 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: supplier.fileUpload" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Return Values

Fields Description
href Link to download the file. It works without a login, so pass it on to authorised people only.
file_ident Ident of the file
parent_ident Ident of the record the file belongs to
file_user_name The file name as you sent it
file_name The name billware stores the file under
file_extension Ending of the file, e.g. pdf
reference_nr Number of the record the file belongs to, as it was at the upload
date_updated Time of the upload in server time (UTC)

Example Responses


// SUCCESS
{
    "response": true,
    "data": {
        "href": "https://www.billware.de/file?t=...",
        "file_ident": "l51gvi7q0su56l44",
        "controller": "supplier",
        "parent_ident": "ckt8w78bfmj54054",
        "file_name": "file_43a37bf8fa591e73a5d091b47a7c5b1f87b52c40.pdf",
        "file_user_name": "Rahmenvertrag 2026.pdf",
        "file_type": "user",
        "file_extension": "pdf",
        "reference_nr": "L-7001",
        "date_updated": "2026-11-16 10:30:10",
        "date_updated_user": "16.11.2026"
    },
    "message": "File uploaded"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Only PDF, XML, JPG, PNG, GIF, TXT, DOC, DOCX, RTF and XLSX files are accepted"
}

supplier.fileDelete

Delete a document of a supplier.

Data

Fields Description Accepted Types
supplier_ident Required Ident of the supplier String
file_ident Required Ident of the document, from the answer of supplier.fileUpload or from files of the supplier. String

Code Examples

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

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","file_ident":"l51gvi7q0su56l44"}'

# 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: supplier.fileDelete" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Return Values

The answer holds the supplier as it is now, with the same structure as supplier.read.

Example Responses


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "files": [],
        ...
    },
    "message": "File deleted"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "File not found"
}