NAV
shell php ruby python

Introduction

Welcome to the Bilendo API! You can use our API to access Bilendo API endpoints.

Environments

Development and Test

You can register a new Developer account at s01.bilendo.de

The API-Endpoints for this environment all start with https://s01.bilendo.de

Production

The API-Endpoints for this environment all start with https://www.bilendo.de

If you want to use our API in production mode, you can contact us at developer@bilendo.de

Authentication

Request

curl -X "GET" "https://s01.bilendo.de/" \
    -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
    response = requests.get(
        url="https://s01.bilendo.de/",
        headers={
            "Authorization": "Token token=YOUR-API-TOKEN",
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Bilendo uses API tokens to allow access to the API. You can get your API-Token in your Bilendo-Account under your account settings.

Once you have your token, you must include it with Bilendo API requests as the HTTP headers.

Header name Header value
Authorization Token token=YOUR-API-TOKEN

Note that all API requests are made over SSL (HTTPS).

Customers

Customer Object

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "100001",
  "additional_number": "200002",
  "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
  "name": "Company Inc.",
  "phone": "0123456789",
  "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
  "dunning_stop": false,
  "dunning_stop_date": null,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": [
    {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "phone": "0123456789",
      "gender": 1,
      "salutation": 0,
      "email": "john@doe.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    }
  ]
}
Attribute Type Description
id string Bilendo id of the ustomer
Example: cus-00000000-0000-0000-0000-000000000000
external_id string your id of the customer
customer_number string optional customer number
additional_number string optional additional customer number
bilendo_url string the url of the customer in the bilendo frontend
name string name of the customer
phone string phone number of the customer
address string customer’s full address starting with the customer name. Lines separated by \n
dunning_stop boolean prevents reminders
dunning_stop_date date the dunning_stop ends on this date
shipping_mode string shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
unknown
We default to the company shipping mode settings if empty.
customer_group_id string the customer’s group id
note string optional note
created_at datetime datetime of creation
updated_at datetime datetime of last update
contacts array all contacts for this customer

Create new Customer

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/customers" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=Example Inc." \
  -d "phone=0123456789" \
  -d "external_id=<your-customer-id>" \
  -d "address_line1=Example Inc." \
  -d "address_line2=John Smith" \
  -d "address_line3=Some Street 1" \
  -d "address_line4=Backyard" \
  -d "zip=13245" \
  -d "city=City" \
  -d "country_code=DE" \
  -d "customer_number=1000123" \
  -d "additional_number=2000456" \
  -d "note=Lorem Ipsum" \
  -d "customer_group_id=<customer-group-id>" \
  -d "dunning_stop=false" \
  -d "shipping_mode=email" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "name"                     => "Example Inc.",
  "phone"                    => "0123456789",
  "address_line1"            => "Example Inc.",
  "address_line2"            => "John Smith",
  "address_line3"            => "Some Street 1",
  "address_line4"            => "Backyard",
  "zip"                      => "13245",
  "city"                     => "City",
  "country_code"             => "DE",
  "note"                     => "Lorem Ipsum",
  "dunning_stop"             => "false",
  "customer_number"          => "1000123",
  "additional_number"        => "2000456",
  "external_id"              => "<your-customer-id>",
  "shipping_mode"            => "email",
  "customer_group_id"        => "<customer-group-id>"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name"                     => "Example Inc.",
    "phone"                    => "0123456789",
    "address_line1"            => "Example Inc.",
    "address_line2"            => "John Smith",
    "address_line3"            => "Some Street 1",
    "address_line4"            => "Backyard",
    "zip"                      => "13245",
    "city"                     => "City",
    "country_code"             => "DE",
    "note"                     => "Lorem Ipsum",
    "dunning_stop"             => "false",
    "customer_number"          => "1000123",
    "additional_number"        => "2000456",
    "external_id"              => "<your-customer-id>",
    "shipping_mode"            => "email",
    "customer_group_id"        => "<customer-group-id>"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
    url = "https://s01.bilendo.de/api/v1/customers",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    },
    data = {
      "name":                     "Example Inc.",
      "phone":                    "0123456789",
      "address_line1":            "Example Inc.",
      "address_line2":            "John Smith",
      "address_line3":            "Some Street 1",
      "address_line4":            "Backyard",
      "zip":                      "13245",
      "city":                     "City",
      "country_code":             "DE",
      "note":                     "Lorem Ipsum",
      "dunning_stop":             "false",
      "customer_number":          "1000123",
      "additional_number":        "2000456",
      "external_id":              "<your-customer-id>",
      "shipping_mode":            "email",
      "customer_group_id":        "<customer-group-id>"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "1000123",
  "additional_number": "2000456",
  "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
  "name": "Example Inc.",
  "phone": "0123456789",
  "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "dunning_stop": false,
  "shipping_mode": "email",
  "note": "Lorem Ipsum",
  "customer_group_id": "<customer-group-id>",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": []
}
Parameter type Description
name mandatory name of the customer
phone optional phone number of the customer
address_line1 mandatory customer’s address line 1 (customer name)
address_line2 optional customer’s address line 2 (contact name)
address_line3 mandatory customer’s address line 3 (street and house number)
address_line4 optional customer’s address line 4 (additional address)
zip mandatory customer’s zip code
city mandatory customer’s city
country_code mandatory customer’s country isocode
customer_number optional customer number
additional_number optional additional customer number
external_id optional your customer id
dunning_stop optional prevents reminders
dunning_stop_date optional the dunning_stop ends on this date
customer_group_id optional customer’s group id
dunning_stop optional prevents automatic reminders
shipping_mode optional shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
unknown
We default to the company shipping mode settings if empty.
note optional note

API Endpoint

POST https://s01.bilendo.de/api/v1/customers

Update existing Customer

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/customers/<customer-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=New Companyname Inc." \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/<customer-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "name" => "New Companyname Inc."
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/<customer-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "New Companyname Inc."
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/customers/<customer-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "New Companyname Inc."
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "1000123",
  "additional_number": "2000456",
  "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
  "name": "New Companyname Inc.",
  "phone": "0123456789",
  "address": "New Companyname Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "dunning_stop": false,
  "dunning_stop_date": null,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": []
}

API Endpoint

PATCH https://s01.bilendo.de/api/v1/customers/<customer-id>

Get All Customers

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customers" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customers",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customers":[
    {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Example Inc.",
      "phone": "0123456789",
      "customer_number": "100001",
      "additional_number": "2000001",
      "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
      "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "shipping_mode": "email",
      "customer_group_id": "<customer-group-id>",
      "note": "Lorem Ipsum",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00",
      "contacts": [
        {
          "id": "<contact-id>",
          "external_id": "<your-contact-id>",
          "name": "John Smith",
          "gender": 1,
          "salutation": 0,
          "email": "john@doe.de",
          "created_at": "2016-01-18T13:53:06+01:00",
          "updated_at": "2016-01-18T13:53:06+01:00"
        }
      ]
    }, {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Example Inc. 2",
      "phone": "0987456321",
      "customer_number": "100002",
      "additional_number": "200002",
      "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
      "address": "Example Inc. 2\nSome Street 2\n54321 City\nDeutschland",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "shipping_mode": "email",
      "customer_group_id": "<customer-group-id>",
      "note": "Lorem Ipsum",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00",
      "contacts": [
        {
          "id": "<contact-id>",
          "external_id": "<your-contact-id>",
          "name": "John",
          "gender": 1,
          "salutation": 0,
          "email": "john@bilendo.de",
          "created_at": "2016-01-18T13:53:06+01:00",
          "updated_at": "2016-01-18T13:53:06+01:00"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 2
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/customers

Get a specific Customer

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customers/<customer-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/<customer-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/<customer-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customers/<customer-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "100001",
  "additional_number": "200002",
  "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
  "name": "Example Inc.",
  "phone": "0123456789",
  "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "dunning_stop": false,
  "dunning_stop_date": null,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": [
    {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 0,
      "email": "john@doe.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    }
  ]
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customers/<customer-id>

Find a specific Customer

Use this endpoint to case-insensitive find a customer on bilendo by providing your own id.

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "100001",
  "additional_number": "200002",
  "bilendo_url": "https://www.bilendo.de/xxxxxxxx/customers/<customer-id>",
  "name": "Example Inc.",
  "phone": "0123456789",
  "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "dunning_stop": false,
  "dunning_stop_date": null,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": [
    {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 0,
      "email": "john@doe.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    }
  ]
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>

Write-off open invoices

Use this endpoint to write-off open invoices for a specific customer.

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/customers/<your-customer-id>/write_off_open_invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/<your-customer-id>/write_off_open_invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/<your-customer-id>/write_off_open_invoices')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/customers/<your-customer-id>/write_off_open_invoices",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

Action Response Code
write-off-open-invoices 202 (ACCEPTED)

Api Endpoint

PATCH https://s01.bilendo.de/api/v1/customers/<customer-id>/write_off_open_invoices

Revert written-off invoices

Use this endpoint to revert written-off invoices for a specific customer.

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/customers/<your-customer-id>/revert_write_off_open_invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/<your-customer-id>/revert_write_off_open_invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/<your-customer-id>/revert_write_off_open_invoices')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/customers/<your-customer-id>/revert_write_off_open_invoices",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

Action Response Code
revert-write-off-open-invoices 202 (ACCEPTED)

Api Endpoint

PATCH https://s01.bilendo.de/api/v1/customers/<customer-id>/revert_write_off_open_invoices

Contacts

Contact Object

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "John",
    "phone": "0123456789",
    "gender":1,
    "salutation":0,
    "salutation_text": "Sehr geehrter Herr John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}
Attribute Type Description
id string Bilendo id of the contact
Example: con-00000000-0000-0000-0000-000000000000
external_id string your id of the contact
name string name of the contact
phone string phone number of the contact
gender integer 0 = unknown
1 = male
2 = female
salutation integer 0 = formal
1 = informal
salutation text string 0 = “Sehr geehrter Herr #{name}”;
“Sehr geehrter Frau #{name}”;
“Sehr geehrte Damen und Herren” (if a name missing)
1 = “Hallo #{name}”
email string email
customer_id string the customer id
main_contact boolean true = main contact
false = not main contact

Create new Contact

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/contacts" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=John" \
  -d "phone=0123456789" \
  -d "external_id=<your-contact-id>" \
  -d "gender=1" \
  -d "salutation=1" \
  -d "customer_id=<customer-id>" \
  -d "customer[external_id]=<your-customer-id>" \
  -d "email=john@bilendo.de" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "name" => "John",
  "phone" => "0123456789",
  "external_id" => "<your-contact-id>",
  "gender" => "1",
  "salutation" => "1",
  "customer_id" => "<customer-id>",
  "customer[external_id]" => "<your-customer-id>",
  "email" => "john@bilendo.de"
];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'
begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "John",
    "phone" => "0123456789",
    "external_id" => "<your-contact-id>",
    "gender" => "1",
    "salutation" => "1",
    "customer_id" => "<customer-id>",
    "customer[external_id]" => "<your-customer-id>",
    "email" => "john@bilendo.de"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.post(
      url = "https://s01.bilendo.de/api/v1/contacts",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "John",
          "phone": "0123456789",
          "external_id": "<your-contact-id>",
          "gender": "1",
          "salutation": "1",
          "customer_id": "<customer-id>",
          "customer[external_id]": "<your-customer-id>",
          "email": "john@bilendo.de"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "John",
    "phone": "0123456789",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}
Parameter type Description
name mandatory name of the contact
phone optional phone number of the contact
gender mandatory 0 = unknown
1 = male
2 = female
external_id optional your contact id
salutation mandatory 0 = formal
1 = informal
email optional email
customer_id or
customer[external_id]
mandatory bilendo-customer-id
your-customer-id
main_contact optional true = make this contact a main contact, false = make this contact not a main contact

API Endpoint

POST https://s01.bilendo.de/api/v1/contacts

Update existing Contact

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/contacts/<contact-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=New name" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts/<contact-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "name" => "New name"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts/<contact-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "New name"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/contacts/<contact-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "New name"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "New name",
    "phone": "0123456789",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}

API Endpoint

PATCH https://s01.bilendo.de/api/v1/contacts/<contact-id>

Get a specific Contact

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/contacts/<contact-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts/<contact-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts/<contact-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/contacts/<contact-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "New name",
    "phone": "0123456789",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/contacts/<contact-id>

Find a specific Contact

Use this endpoint to case-insensitive find a contact on bilendo by providing your own id.

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN",
      },
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "New name",
    "phone": "0123456789",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>

Invoices

Invoice Object

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "ready_for_reminder2",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "additional_number": "300001",
    "currency": "EUR",
    "reminder_fees": "5.0",
    "distortion_fees": "40.0",
    "interest_fees": "10.0",
    "original_total": "606.9",
    "total": "661.9",
    "open_amount": "0.0",
    "order_date": "2014-04-16",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [
      {
        "id": "<payment-id>",
        "external_id": "<your-payment-id>",
        "currency": "EUR",
        "amount": "611.9",
        "purpose": "ReNr 400001",
        "name": "Company Inc.",
        "account_numer": "DE123456789101112",
        "bank_code": "DEUTDE1234",
        "bank_name": "Example Bank",
        "currency": "EUR",
        "payment_date": "2015-12-01",
        "note": "Lorem Ipsum",
        "source": "API",
        "inkasso_payment": "false",
        "created_at": "2016-04-04T14:53:10+02:00",
        "updated_at": "2016-04-04T14:53:10+02:00"
      }
    ],
    "reminders": [
      {
        "id": "<reminder-id>",
        "reminder_stage": 1,
        "reminder_date": "2014-05-25",
        "last_sent_at": "2014-05-25T14:53:10+02:00",
        "shipping_mode": "post",
        "currency": "EUR",
        "fees": "5.0",
        "distortion_fee": "40.0",
        "interest_fee": "10.0"
      }
    ]
  }
}
Attribute Type Description
id string Bilendo id of the invoice
Example: inv-00000000-0000-0000-0000-000000000000
external_id string your id of the invoice
invoice_status string see table below
invoice_number string invoice number
bilendo_url string the url of the invoice in the bilendo frontend
additional_number string any additional number or id (ex: order number)
currency string currency iso code
open_amount decimal open amount
total decimal gross value
original_total decimal gross value excluding reminder fees
reminder_fees decimal total value of reminder fees
distortion_fees decimal total value of distortion fees
interest_fees decimal total value of interest_fees
order_date date order or contract date
invoice_date date invoice date
due_date date due date
custom_fields json fields with custom names and values
time_for_payment integer difference between invoice_date and due_date
dunning_stop boolean prevents reminders
dunning_stop_date date the dunning_stop ends on this date
shipping_mode string shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
skip_shipping
manual_shipping (If the invoice is not shipped via Bilendo, eg: you print and ship it yourself)
unknown
We default to the customer shipping mode settings if empty.
customer hash the customer
contact hash the contact
reminders array all reminders
payments array all payments

Possible values for invoice_status

Value Description
archived invoice is archived
draft invoice is a draft
sent invoice was sent
due invoice is due
ready_for_reminder1 invoice is due and you should send a first reminder
reminder1_sent first reminder was sent
ready_for_reminder2 invoice is due and you should send a second reminder
reminder2_sent second reminder was sent
ready_for_reminder3 invoice is due and you should send a third reminder
reminder3_sent third reminder was sent
ready_for_dept_collection invoice is due and you should send it to dept collection
sent_to_dept_collection the invoice was sent to dept collection
written_off the invoice was written-off
paid invoice is paid
duplicate invoice is a duplicate

Create new Invoice

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "invoice=@invoice.pdf" \
  -F "invoice_attachment=@attachment.pdf" \
  -F "external_id=<your-invoice-id>" \
  -F "customer_id=<customer-id>" \
  -F "contact_id=<contact-id>" \
  -F "invoice_number=400001" \
  -F "additional_number=300001" \
  -F "currency=EUR" \
  -F "total=606.9" \
  -F "order_date=01.12.2015" \
  -F "invoice_date=01.12.2015" \
  -F "time_for_payment=14" \
  -F "due_date=15.12.2015" \
  -F "custom_fields={\"field1\":\"value1\",\"field2\":\"value2\"}"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://localhost:3000/api/v1/invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set secure upload
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, 1);

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Create body
$body = [
  "invoice"           => new CurlFile('invoice.pdf', 'application/pdf'),
  'invoice_attachment'=> new CurlFile('attachment.pdf'), 'application/pdf'),
  "external_id"       => "<your-invoice-id>",
  "customer_id"       => "<customerid>",
  "contact_id"        => "<contact-id>",
  "invoice_number"    => "400001",
  "additional_number" => "300001",
  "currency"          => "EUR",
  "total"             => 606.9,
  "order_date"        => "01.12.2015",
  "invoice_date"      => "01.12.2015",
  "time_for_payment"  => 14,
  "due_date"          => "15.12.2015",
  'custom_fields'     => '{"field1":"value1","field2":"value2"}'
  ];

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'
require 'net/http/post/multipart'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  body = {
    'invoice'           => UploadIO.new(File.new('invoice.pdf'), 'application/pdf'),
    'invoice_attachment'=> UploadIO.new(File.new('attachment.pdf'), 'application/pdf'),
    'external_id'       => '<your-invoice-id>',
    'customer_id'       => '<customerid>',
    'contact_id'        => '<contact-id>',
    'invoice_number'    => '400001',
    'additional_number' => '300001',
    'currency'          =>  'EUR',
    'total'             =>  606.9,
    'order_date'        => '01.12.2015',
    'invoice_date'      => '01.12.2015',
    'time_for_payment'  =>  14,
    'due_date'          => '15.12.2015',
    'custom_fields'     => '{\"field1\":\"value1\",\"field2\":\"value2\"}'
  }

  # Create Request
  req = Net::HTTP::Post::Multipart.new(uri, body)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests
try:
    response = requests.post(
        url = 'https://s01.bilendo.de/api/v1/invoices',
        headers = {
            'Authorization': 'Token token=YOUR-API-TOKEN'
        },
        files = {
            'invoice': open('invoice.pdf', 'rb'),
            'invoice_attachment': open('attachment.pdf', 'rb')
        },
        data = {
            'external_id':       '<your-invoice-id>',
            'customer_id':       '<customerid>',
            'contact_id':        '<contact-id>',
            'invoice_number':    '400001',
            'additional_number': '300001',
            'currency':          'EUR',
            'total':              606.9,
            'order_date':        '01.12.2015',
            'invoice_date':      '01.12.2015',
            'time_for_payment':   14,
            'due_date':          '15.12.2015',
            'custom_fields':     '{\"field1\":\"value1\",\"field2\":\"value2\"}'
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "606.9",
    "open_amount": "606.9",
    "reminder_fees": "0.0",
    "order_date": null,
    "invoice_date": "2015-12-01",
    "due_date": "2015-12-15",
    "time_for_payment": 14,
    "invoice_status": "draft",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "written_off_at": null,
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "0.0",
    "interest_fees": "0.0",
    "custom_fields": {
      "field1": "value1",
      "field2": "value2"
    },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":2,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [],
    "reminders": []
  }
}
Parameter Type Description
invoice mandatory PDF-File
external_id optional your invoice id
customer_id optional bilendo customer_id
contact_id optional bilendo contact_id
invoice_number optional invoice number
invoice_attachment optional invoice attachment must be PDF (this is not the invoice).
additional_number optional any additional number or id (ex: order number)
currency optional invoice currency iso code
total optional gross value
net optional net value (not used at the moment)
vat7 optional vat 7% value (not used at the moment)
vat19 optional vat 19% value (not used at the moment)
order_date optional order or contract date
invoice_date optional invoice date
due_date optional due date
custom_fields optional fields with custom names and values
time_for_payment optional difference between invoice_date and due_date
dunning_stop optional prevents reminders
dunning_stop_date optional the dunning_stop ends on this date
options[autoskip_shipping] optional true = automatically import invoice, overrides company settings
options[autosend] optional true = automatically send invoice, overrides company settings

API Endpoint

POST https://s01.bilendo.de/api/v1/invoices

Create new Invoice (Extended)

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "customer[name]=New Company Inc" \
  -F "customer[phone]=0123456789" \
  -d "customer[address_line1]=New Company Inc" \
  -d "customer[address_line2]=John Smith" \
  -d "customer[address_line3]=Some Street 2" \
  -d "customer[address_line4]=Backyard" \
  -d "customer[zip]=54321" \
  -d "customer[city]=City" \
  -d "customer[country_code]=DE" \
  -F "customer[customer_number]=123654" \
  -F "customer[additional_number]=435232" \
  -F "customer[external_id]=<your-customer-id>" \
  -F "customer[dunning_stop]=false" \
  -F "customer[shipping_mode]=email" \
  -F "customer[customer_group_id]=<customers-group-id>" \
  -F "customer[note]=Lorem Ipsum"\
  -F "contact[name]=John Smith" \
  -F "contact[phone]=0123456789" \
  -F "contact[gender]=1" \
  -F "contact[salutation]=1" \
  -F "contact[email]=smith@email.com" \
  -F "contact[external_id]=<your-contact-id>" \
  -F "customer_id=<customer-id>" \ # Do not provide when creating a new customer
  -F "contact_id=<contact-id>" \ # Do not provide when creating a new contact
  -F "invoice=@invoice.pdf" \
  -F "invoice_attachment=@attachment.pdf" \
  -F "external_id=<your-invoice-id>" \
  -F "invoice_number=400001" \
  -F "additional_number=300001" \
  -F "total=606.9" \
  -F "order_date=01.12.2015" \
  -F "invoice_date=01.12.2015" \
  -F "time_for_payment=14" \
  -F "due_date=15.12.2015" \
  -F "dunning_stop=false" \
  -F "currency=EUR" \
  -F "custom_fields={\"field1\":\"value1\",\"field2\":\"value2\"}"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set secure upload
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, 1);

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Token token=YOUR-API-TOKEN'
 ]
);
// Create body
$body = [
    'invoice'                            => new CurlFile('invoice.pdf', 'application/pdf'),
    'invoice_attachment'                 => new CurlFile('attachment.pdf', 'application/pdf'),
    'customer[name]'                     => 'New Company Inc.',
    'customer[phone]'                    => '0123456789',
    'customer[address_line1]'            => 'New Company Inc.',
    'customer[address_line2]'            => 'John Smith',
    'customer[address_line3]'            => 'Some Street 2',
    'customer[address_line4]'            => 'Backyard',
    'customer[zip]'                      => '54321',
    'customer[city]'                     => 'City',
    'customer[country_code]'             => 'DE',
    'customer[customer_number]'          => '123456',
    'customer[additional_number]'        => '435232',
    'customer[external_id]'              => '<your-customer-id>',
    'customer[dunning_stop]'             => 'false',
    'customer[shipping_mode]'            => 'email',
    'customer[customer_group_id]'        => '<customers-group-id>',
    'customer[note]'                     => 'Lorem Ipsun',
    'contact[name]'                      => 'John Smith',
    'contact[phone]'                     => '0123456789',
    'contact[gender]'                    => '1',
    'contact[salutation]'                => '1',
    'contact[email]'                     => 'smith@email.com',
    'contact[external_id]'               => '<your-contact-id>',
    'customer_id'                        => '<customer-id>',
    'contact_id'                         => '<contact-id>',
    'external_id'                        => '<your-invoice-id>',
    'invoice_number'                     => '400001',
    'additional_number'                  => '300001',
    'currency'                           => 'EUR',
    'total'                              => '606.9',
    'order_date'                         => '01.12.2015',
    'invoice_date'                       => '01.12.2015',
    'due_date'                           => '15.12.2015',
    'time_for_payment'                   => '14',
    'dunning_stop'                       => 'false',
    'custom_fields'                      => '{"field1":"value1","field2":"value2"}'
];

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>

require 'net/http'
require 'net/https'
require 'net/http/post/multipart'

begin
    uri = URI('https://s01.bilendo.de/api/v1/invoices')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    body = {
        'invoice'                            => UploadIO.new(File.new('invoice.pdf'), 'application/pdf'),
        'invoice_attachment'                 => UploadIO.new(File.new('attachment.pdf'), 'application/pdf'),
        'customer[name]'                     => 'New Company Inc.',
        'customer[phone]'                    => '0123456789',
        'customer[address_line1]'            => 'New Company Inc.',
        'customer[address_line2]'            => 'John Smith',
        'customer[address_line3]'            => 'Some Street 2',
        'customer[address_line4]'            => 'Backyard',
        'customer[zip]'                      => '54321',
        'customer[city]'                     => 'City',
        'customer[country_code]'             => 'DE',
        'customer[customer_number]'          => '123456',
        'customer[additional_number]'        => '435232',
        'customer[external_id]'              => '<your-customer-id>',
        'customer[dunning_stop]'             => 'false',
        'customer[shipping_mode]'            => 'email',
        'customer[customer_group_id]'        => '<customers-group-id>',
        'customer[note]'                     => 'Lorem Ipsum',
        'contact[name]'                      => 'John Smith',
        'contact[phone]'                     => '0123456789',
        'contact[gender]'                    => '1',
        'contact[salutation]'                => '1',
        'contact[email]'                     => 'smith@email.com',
        'contact[external_id]'               => '<your-contact-id>',
        'customer_id'                        => '<customer-id>',
        'contact_id'                         => '<contact-id>',
        'external_id'                        => '<your-invoice-number>',
        'invoice_number'                     => '400001',
        'additional_number'                  => '300001',
        'currency'                           => 'EUR',
        'total'                              => '606.9',
        'order_date'                         => '01.12.2015',
        'invoice_date'                       => '01.12.2015',
        'due_date'                           => '15.12.2015',
        'time_for_payment'                   => '14',
        'dunning_stop'                       => 'false',
        'custom_fields'                      => '{\"field1\":\"value1\",\"field2\":\"value2\"}'
    }

    # Create Request
    req = Net::HTTP::Post::Multipart.new(uri, body)
    # Add headers
    req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
end

import requests
try:
    response = requests.post(
        url = 'https://s01.bilendo.de/api/v1/invoices',
        headers = {
            'Authorization': 'Token token=YOUR-API-TOKEN'
        },
        files = {
            'invoice': open('invoice.pdf', 'rb')
        },
        data = {
            'customer[name]':                     'New Company Inc',
            'customer[phone]':                    '0123456789',
            'customer[address_line1]':            'New Company Inc',
            'customer[address_line2]':            'John Smith',
            'customer[address_line3]':            'Some Street 2',
            'customer[address_line4]':            'Backyard',
            'customer[zip]':                      '54321',
            'customer[city]':                     'City',
            'customer[country_code]':             'DE',
            'customer[customer_number]':          '123654',
            'customer[additional_number]':        '435232',
            'customer[external_id]':              '<your-customer-id>',
            'customer[dunning_stop]':             'false',
            'customer[shipping_mode]':            'email',
            'customer[customer_group_id]':        '<customers-group-id>',
            'customer[note]':                     'Lorem Ipsum',
            'contact[name]':                      'John Smith',
            'contact[phone]':                     '0123456789',
            'contact[gender]':                    '1',
            'contact[salutation]':                '1',
            'contact[email]':                     'smith@email.com',
            'contact[external_id]':               '<your-contact-id>',
            'customer_id':                        '<customer-id>',
            'contact_id':                         '<contact-id>',
            'external_id':                        '<your-invoice-id>',
            'invoice_number':                     '400001',
            'additional_number':                  '300001',
            'currency':                           'EUR',
            'total':                               606.9,
            'order_date':                         '01.12.2015',
            'invoice_date':                       '01.12.2015',
            'time_for_payment':                    14,
            'due_date':                           '15.12.2015',
            'dunning_stop':                       'false',
            'custom_fields':                      '{\"field1\":\"value1\",\"field2\":\"value2\"}'
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "606.9",
    "open_amount": "606.9",
    "reminder_fees": "0.0",
    "order_date": null,
    "invoice_date": "2015-12-01",
    "due_date": "2015-12-15",
    "time_for_payment": 14,
    "invoice_status": "draft",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "written_off_at": null,
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "0.0",
    "interest_fees": "0.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "New Company Inc",
      "customer_number": "123654",
      "address": "New Company Inc\nJohn Smith\nSome Street2\nBackyard\n54321 City\nDeutschland",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-07-22T17:32:18+02:00",
      "updated_at": "2016-07-22T17:32:18+02:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 1,
      "email": "smith@email.com",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [],
    "reminders": []
  }
}

The extended create allows the creation of an invoice, a customer and a contact with a single request.

Other possible options:


Parameter Type Description
invoice mandatory PDF-File
invoice_attachment optional invoice attachment must be PDF (this is not the invoice).
external_id optional your invoice id
invoice_number optional invoice number
additional_number optional any additional number or id (ex: order number)
currency optional invoice currency iso code
total optional gross value
net optional net value (not used at the moment)
vat7 optional vat 7% value (not used at the moment)
vat19 optional vat 19% value (not used at the moment)
custom_fields optional fields with custom names and values
order_date optional order or contract date
invoice_date optional invoice date
due_date optional due date
time_for_payment optional difference between invoice_date and due_date
dunning_stop optional prevents reminders
dunning_stop_date optional the dunning stop ends on this date
customer_id optional bilendo customer_id
contact_id optional bilendo contact_id
customer[name] optional name of the customer
customer[phone] optional phone number of the customer
customer[address_line1] mandatory customer’s address line 1 (customer name)
customer[address_line2] optional customer’s address line 2 (contact name)
customer[address_line3] mandatory customer’s address line 3 (street and house number)
customer[address_line4] optional customer’s address line 4 (additional address)
customer[zip] optional customer’s zip code
customer[city] optional customer’s city
customer[country_code] optional customer’s country isocode
customer[customer_number] optional customer number
customer[additional_number] optional additional customer number
customer[external_id] optional your id of the customer
customer[customer_group_id] optional customer’s group id
customer[note] optional optional note
customer[dunning_stop] optional prevents reminders
customer[dunning_stop_date] optional the dunning stop ends on this date
customer[shipping_mode] optional shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
unknown
We default to the customer shipping mode settings if emtpy.
contact[name] optional name of the contact
contact[phone] optional phone number of the contact
contact[email] optional contact email
contact[gender] optional 0 = unknown
1 = male
2 = female
contact[salutation] optional 0 = formal
1 = informal
contact[external_id]  optional your id of the contact
contact[main_contact]  optional true = main contact, false = not main contact
options[autoskip_shipping] optional true = automatically import invoice, overrides company settings
options[autosend] optional true = automatically send invoice, overrides company settings

API Endpoint

POST https://s01.bilendo.de/api/v1/invoices

Update existing Invoice

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "external_id=newexternalid" \
  -d "additional_number=newadditionalnumber" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "external_id" => "newexternalid",
  "additional_number" => "newadditionalnumber"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "external_id" => "newexternalid",
    "additional_number" => "newadditionalnumber"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "external_id": "newexternalid",
          "additional_number": "newadditionalnumber"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "newexternalid",
    "additional_number": "newadditionalnumber",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "606.9",
    "open_amount": "606.9",
    "reminder_fees": "0.0",
    "order_date": "2015-12-01",
    "invoice_date": "2015-12-01",
    "due_date": "2015-12-15",
    "time_for_payment": 14,
    "invoice_status": "draft",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "written_off_at": null,
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "0.0",
    "interest_fees": "0.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "New Company Inc",
      "customer_number": "123654",
      "address": "New Company Inc\nJohn Smith\nSome Street2\nBackyard\n54321 City\nDeutschland",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-07-22T17:32:18+02:00",
      "updated_at": "2016-07-22T17:32:18+02:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 1,
      "email": "smith@email.com",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [],
    "reminders": []
  }
}

You can only update the external_id and the additional_number for an invoice.

API Endpoint

PATCH https://s01.bilendo.de/api/v1/invoices/<invoice-id>

Get Invoices

Get All Invoices

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/invoices",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoices":[
    {
      "id": "<invoice-id1>",
      "...",
    }, {
      "id": "<invoice-id2>",
      "...",
    }, , {
      "id": "<invoice-id3>",
      "...",
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 3
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute Type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/invoices

Get filtered invoices

Filters

Paramaters Description
all_open all invoices that are not paid
open sent invoices that are not paid and not due
due due invoices without sent reminders
reminder1 invoices with first reminder sent
reminder2 invoices with second reminder sent
reminder3 invoices with third reminder sent
to_inkasso invoices sent to your debt collector
written_off written off invoices
paid all paid invoices
partially_paid all partially paid invoices
archived all archived invoices
dunning_stopped all invoices with dunning stop on the invoice or customer
dunning_not_stopped all invoices without dunning stop

API Endpoint

GET https://s01.bilendo.de/api/v1/invoices?filter=<filter-parameter>

Get a specific Invoice

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "661.9",
    "open_amount": "0.0",
    "reminder_fees": "5.0",
    "order_date": "2014-04-16",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "invoice_status": "ready_for_reminder2",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "written_off_at": null,
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "40.0",
    "interest_fees": "10.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [
      {
        "id": "<payment-id>",
        "external_id": "<your-payment-id>",
        "currency": "EUR",
        "amount": "611.9",
        "purpose": "ReNr 400001",
        "name": "Company Inc.",
        "account_numer": "DE123456789101112",
        "bank_code": "DEUTDE1234",
        "bank_name": "Example Bank",
        "payment_date": "2015-12-01",
        "note": "Lorem Ipsum",
        "source": "API",
        "inkasso_payment": "false",
        "created_at": "2016-04-04T14:53:10+02:00",
        "updated_at": "2016-04-04T14:53:10+02:00"
      }
    ],
    "reminders": [
      {
        "id": "<reminder-id>",
        "reminder_stage": 1,
        "reminder_date": "2014-05-25",
        "last_sent_at": "2014-05-25T14:53:10+02:00",
        "shipping_mode": "post",
        "currency": "EUR",
        "fees": "5.0",
        "distortion_fee": "40.0",
        "interest_fee": "10.0"
      }
    ]
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/invoices/<invoice-id>

Find a specific Invoice

Use this endpoint to case-insensitive find an invoice on bilendo by providing your own id or your invoice_number

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "661.9",
    "open_amount": "0.0",
    "reminder_fees": "5.0",
    "order_date": "2014-04-16",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "invoice_status": "ready_for_reminder2",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "40.0",
    "interest_fees": "10.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [
      {
        "id": "<payment-id>",
        "external_id": "<your-payment-id>",
        "currency": "EUR",
        "amount": "611.9",
        "purpose": "ReNr 400001",
        "name": "Company Inc.",
        "account_numer": "DE123456789101112",
        "bank_code": "DEUTDE1234",
        "bank_name": "Example Bank",
        "payment_date": "2015-12-01",
        "note": "Lorem Ipsum",
        "source": "API",
        "inkasso_payment": "false",
        "created_at": "2016-04-04T14:53:10+02:00",
        "updated_at": "2016-04-04T14:53:10+02:00"
      }
    ],
    "reminders": [
      {
        "id": "<reminder-id>",
        "reminder_stage": 1,
        "reminder_date": "2014-05-25",
        "last_sent_at": "2014-05-25T14:53:10+02:00",
        "shipping_mode": "post",
        "fees": "5.0",
        "distortion_fee": "40.0",
        "interest_fee": "10.0"
      }
    ]
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>

Write-off an Invoice

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>/write_off"
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>/write_off;

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>/write_off')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>/write_off",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response body

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",

    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "606.9",
    "open_amount": "0.0",
    "reminder_fees": "0.0",
    "order_date": "2014-04-16",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "invoice_status": "written_off",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "written_off_at": "2016-01-18T13:53:35+01:00",
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "0.0",
    "interest_fees": "0.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [],
    "reminders": []
  }
}
Action Response Code
write-off 200 (OK)

Api Endpoint

PATCH https://s01.bilendo.de/api/v1/invoices/<invoice-id>/write_off

Revert a written-off Invoice

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>/revert_write_off"
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>/revert_write_off');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>/revert_write_off')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>/revert_write_off",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response body

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",
    "invoice_status": "ready_for_reminder1",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "606.9",
    "open_amount": "0.0",
    "reminder_fees": "0.0",
    "order_date": "2014-04-16",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "written_off_at": null,
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "0.0",
    "interest_fees": "0.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [],
    "reminders": []
  }
}
Action Response Code
revert-write-off 200 (OK)

Api Endpoint

PATCH https://s01.bilendo.de/api/v1/invoices/<invoice-id>/revert_write_off

Delete or archive an Invoice

Request

curl -X "DELETE" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Delete.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.delete(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response body (invoice archived)

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "additional_number": "300001",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "currency": "EUR",
    "original_total": "606.9",
    "total": "606.9",
    "open_amount": "0.0",
    "reminder_fees": "0.0",
    "order_date": "2014-04-16",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "invoice_status": "archived",
    "dunning_stop": false,
    "dunning_stop_date": null,
    "source": "API",
    "shipping_mode": "email",
    "ignore_reminder_fees": false,
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "distortion_fees": "0.0",
    "interest_fees": "0.0",
    "custom_fields": { "field1": "value1", "field2": "value2" },
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [],
    "reminders": []
  }
}
Action Optional Parameter Condition Response Code
Delete delete_payment invoice_status IS draft OR duplicate 204 (No Content)
Archive note invoice_status IS NOT draft OR duplicate 200 (OK)
Attribute Type Value Type Description
note optional string
delete_payment optional boolean true = delete assigned payments, false = unlink assigned payments

Api Endpoint

DELETE https://s01.bilendo.de/api/v1/invoices/<invoice-id>

Payments

Payment Object

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "currency": "EUR",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": false,
    "source": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "currency": "EUR",
      "total": "606.9",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0",
      "reminder_fees": "0.0",
      "distortion_fees": "0.0",
      "interest_fees": "0.0"
    }
  }
}
Attribute Type Description
id string Bilendo id of the payment
Example: pay-00000000-0000-0000-0000-000000000000
external_id string your id of the payment
amount decimal amount of the payment
currency string currency iso code
payment_date date payment date
name string name
purpose string purpose
account_number string iban number
bank_code string bic code
bank_name string bank name
note string optional note
inkasso_payment boolean payment from your debt collector
source 1 string source of the payment
customer customer the customer
invoice invoice the invoice

Create new Payment

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/payments" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -F "customer_id=<customer-id>" \
  -F "invoice_id=<invoice-id>" \
  -F "customer[external_id]=<your-customer-id>" \
  -F "invoice[external_id]=<your-invoice-id>" \
  -F "external_id=<your-payment-id>" \
  -F "currency=EUR" \
  -F "amount=606.9" \
  -F "payment_date=2015-12-01" \
  -F "name=Company Inc" \
  -F "purpose=Payment Purpose" \
  -F "account_number=DE123456789" \
  -F "bank_code=BIC" \
  -F "bank_name=Example-Bank" \
  -F "note=Lorem Ipsum" \
  -F "inkasso_payment=true" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "customer_id" => "<customer-id>",
  "invoice_id" => "<invoice-id>",
  "customer[external_id]" => "<your-customer-id>",
  "invoice[external_id]" => "<your-invoice-id>",
  "external_id" => "<your-payment-id>",
  "currency" => "EUR",
  "amount" => "606.9",
  "payment_date" => "2015-12-01",
  "name" => "Company Inc",
  "purpose" => "Payment Purpose",
  "account_number" => "DE123456789",
  "bank_code" => "BIC",
  "bank_name" => "Example-Bank",
  "note" => "Lorem Ipsum",
  "inkasso_payment" => "true"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "customer_id" => "<customer-id>",
    "invoice_id" => "<invoice-id>",
    "customer[external_id]" => "<your-customer-id>",
    "invoice[external_id]" => "<your-invoice-id>",
    "external_id" => "<your-payment-id>",
    "currency" => "EUR",
    "amount" => "606.9",
    "payment_date" => "2015-12-01",
    "name" => "Company Inc",
    "purpose" => "Payment Purpose",
    "account_number" => "DE123456789",
    "bank_code" => "BIC",
    "bank_name" => "Example-Bank",
    "note" => "Lorem Ipsum",
    "inkasso_payment" => "true"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
    url = "https://s01.bilendo.de/api/v1/payments",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    },
    data = {
      "customer_id": "<customer-id>",
      "invoice_id": "<invoice-id>",
      "customer[external_id]": "<your-customer-id>",
      "invoice[external_id]": "<your-invoice-id>",
      "external_id": "<your-payment-id>",
      "currency": "EUR",
      "amount": "606.9",
      "payment_date": "2015-12-01",
      "name": "Company Inc",
      "purpose": "Payment Purpose",
      "account_number": "DE123456789",
      "bank_code": "BIC",
      "bank_name": "Example-Bank",
      "note": "Lorem Ipsum",
      "inkasso_payment": "true"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "currency": "EUR",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": "true",
    "source": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "currency": "EUR",
      "total": "606.9",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0",
      "reminder_fees": "0.0",
      "distortion_fees": "0.0",
      "interest_fees": "0.0"
    }
  }
}
Parameter type Description
currency optional payment currency iso code
amount mandatory the amount of the payment
external_id optional your payment id 1
payment_date mandatory payment date
name optional name
purpose optional purpose
account_number optional iban number
bank_code optional bic code
bank_name optional bank name
note optional a note
inkasso_payment optional the payment is from your debt collector
customer_id or
customer[external_id]
optional bilendo-customer-id
your-customer-id
invoice_id or
invoice[external_id]
optional bilendo-invoice-id
your-invoice-id

API Endpoint

POST https://s01.bilendo.de/api/v1/payments

Get Payments

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/payments" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/payments",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payments":[
    {
      "id": "<payment-id1>",
      ...
    }, {
      "id": "<payment-id2>",
      ...
    }, , {
      "id": "<payment-id3>",
      ...
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 3
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/payments

Get filtered payments

Filters

Paramaters Description
assigned all payments with assigned invoices
notassigned all payments without assigned invoices
candidate all payments with candidate invoices
inkasso all payments from your debt collection partner

API Endpoint

GET https://s01.bilendo.de/api/v1/payments?filter=<filter-parameter>

Get a specific Payment

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/payments/<payment-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments/<payment-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments/<payment-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/payments/<payment-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "currency": "EUR",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": true,
    "source": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "currency": "EUR",
      "total": "606.9",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0",
      "reminder_fees": "0.0",
      "distortion_fees": "0.0",
      "interest_fees": "0.0"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/payments/<payment-id>

Find a specific Payment

Use this endpoint to case-insensitive find a payment on bilendo by providing your own id.

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "currency": "EUR",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": true,
    "note": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "currency": "EUR",
      "total": "606.9",
      "dunning_stop": false,
      "dunning_stop_date": null,
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0",
      "reminder_fees": "0.0",
      "distortion_fees": "0.0",
      "interest_fees": "0.0"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>

Delete a specific Payment

Request

curl -X "DELETE" "https://s01.bilendo.de/api/v1/payments/<payment-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments/<payment-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments/<payment-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Delete.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.delete(
    url = "https://s01.bilendo.de/api/v1/payments/<payment-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

Action Response Code
delete 204 (No content)

Api Endpoint

DELETE https://s01.bilendo.de/api/v1/payments/<payment-id>

Customers Groups

Customers Group Object

{
  "customer_group": {
    "id": "<customers-group-id>",
    "external_id": "<your-customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": [
      {
        "id": "<customer-id>",
        "external_id": "<your-customer-id>",
        "name": "Company Inc.",
        "customer_number": "100001",
        "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
        "dunning_stop": false,
        "dunning_stop_date": null,
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      }
    ]
  }
}
Attribute Type Description
id string Bilendo id of the customers group
Example: grp-00000000-0000-0000-0000-000000000000
external_id string Your id for the customers group
active boolean active or inactive groups. If a group is inactive, its settings are ignored and we fallback to the company settings
name text customers group name
description text customers group description
customers array customers in the group

Get Customers Groups

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customer_groups" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customer_groups');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customer_groups')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/customer_groups",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customer_groups":[
    {
      "id": "<customer_groups-id1>",
      ...
    }, {
      "id": "<customer_groups-id2>",
      ...
    }, , {
      "id": "<customer_groups-id3>",
      ...
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 3
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/customer_groups

Get a specific Customers Group

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "external_id": "<your-customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": [
      {
        "id": "<customer-id>",
        "external_id": "<your-customer-id>",
        "name": "Company Inc.",
        "customer_number": "100001",
        "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
        "dunning_stop": false,
        "dunning_stop_date": null,
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      }
    ]
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>

Find a specific Customers Group

Use this endpoint to case-insensitive find a customer_group on bilendo by providing your own id.

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customer_groups/find/<your-customers-group-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customer_groups/find/<your-customers-group-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customer_groups/find/<your-customers-group-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customer_groups/find/<your-customers-group-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "external_id": "<your-customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00"
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customer_groups/find/<your-customers-group-id>

Add Customers

Request

curl -X "PUT" "http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add" \
     -H "Authorization: Token token=YOUR-API-TOKEN" \
     -d $'{ "customers": [
            "<customer-id1>",
            "<customer-id2>"
          ]}'
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token token=YOUR-API-TOKEN",
    "Content-Type: application/json; charset=utf-8",
  ]
);

// Create body
$json_array = [
    "customers" => [
      "<customer-id1>",
      "<customer-id2>"
    ]
];

$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'json'

def send_request
  uri = URI('http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  dict = {
            "customers" => [
              "<customer-id1>",
              "<customer-id2>"
            ]
         }
  body = JSON.dump(dict)

  # Create Request
  req =  Net::HTTP::Put.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Add headers
  req.add_field "Content-Type", "application/json; charset=utf-8"
  # Set body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests
import json

def send_request():
    try:
        response = requests.put(
            url="http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add",
            headers={
                "Authorization": "Token token=YOUR-API-TOKEN",
                "Content-Type": "application/json; charset=utf-8",
            },
            data=json.dumps({
                "customers": [
                  "<customer-id1>",
                  "<customer-id2>"
                ]
            })
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "external_id": "<your-customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": [
      {
        "id": "<customer-id1>",
        "external_id": "<your-customer-id1>",
        "name": "Company Inc.",
        "customer_number": "100001",
        "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
        "dunning_stop": false,
        "dunning_stop_date": null,
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      },
      {
        "id": "<customer-id2>",
        "external_id": "<your-customer-id2>",
        "name": "Company Inc. 2",
        "customer_number": "200001",
        "address": "Company Inc. 2\nSome Street 1\n12345 City\nCountry",
        "dunning_stop": false,
        "dunning_stop_date": null,
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      }
    ]
  }
}
Parameter type Description
customers mandatory customers array
customer_id optional bilendo-customer-id (customer to be added)

API Endpoint

PUT http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add

Remove Customers

Request

curl -X "PUT" "http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove" \
     -H "Authorization: Token token=YOUR-API-TOKEN" \
     -d $'{ "customers": [
            "<customer-id1>",
            "<customer-id2>"
          ]}'
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token token=YOUR-API-TOKEN",
    "Content-Type: application/json; charset=utf-8",
  ]
);

// Create body
$json_array = [
    "customers" => [
      "<customer-id1>",
      "<customer-id2>"
    ]
];

$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'json'

def send_request
  uri = URI('http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  dict = {
            "customers" => [
              "<customer-id1>",
              "<customer-id2>"
            ]
         }
  body = JSON.dump(dict)

  # Create Request
  req =  Net::HTTP::Put.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Add headers
  req.add_field "Content-Type", "application/json; charset=utf-8"
  # Set body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests
import json

def send_request():
    try:
        response = requests.put(
            url="http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove",
            headers={
                "Authorization": "Token token=YOUR-API-TOKEN",
                "Content-Type": "application/json; charset=utf-8",
            },
            data=json.dumps({
                "customers": [
                  "<customer-id1>",
                  "<customer-id2>"
                ]
            })
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "external_id": "<your-customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": []
  }
}
Parameter type Description
customers mandatory customers array
customer_id optional bilendo-customer-id (customer to be removed)

API Endpoint

PUT http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove

Custom Fields

Custom Fields Object

{
  "custom_field": {
    "id": "<custom_field-id>",
    "name": "field1",
    "description": "descript for field 1"
  }
}
Attribute Type Description
id string Bilendo id of the custom_field
Example: cuf-00000000-0000-0000-0000-000000000000
name string the name of your placeholder
description string the description of your placeholder

Create new Custom Field

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/custom_fields" \
     -H 'Authorization: Token token=YOUR-API-TOKEN' \
     -d "name=a name" \
     -d "description=a description"
  <?php

  // get cURL resource
  $ch = curl_init();

  // set url
  curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/custom_fields');

  // set method
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

  // return the transfer as a string
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  // set headers
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token token=YOUR-API-TOKEN",
    "Content-Type: application/x-www-form-urlencoded"
  ]);
  // Create body
  $body = [
    'name' => 'a name',
    'description' => 'a description'
  ];
  $body = http_build_query($body);

  // set body
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

  // Send the request & save response to $resp
  $resp = curl_exec($ch);

  if(!$resp) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
  } else {
    echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
    echo "\nResponse HTTP Body : " . $resp;
  }

  // Close request to clear up some resources
  curl_close($ch);

  ?>
require 'net/http'
require 'net/https'
begin
  uri = URI('https://s01.bilendo.de/api/v1/custom_fields')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "a name",
    "description" => "a description",
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
      url = "https://s01.bilendo.de/api/v1/custom_fields",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "a name",
          "description": "a description",
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "custom_field": {
    "id": "cuf-d6d36b49-b509-433c-9e0c-8f60123176c7",
    "name": "a_name",
    "description": "a description"
  }
}
Parameter Type Description
name mandatory name of the custom_field
description mandatory description of the custom_field

API Endpoint

POST https://s01.bilendo.de/api/v1/custom_fields

Update existing Customfield

  curl -X "PATCH" "http://localhost:3000/api/v1/custom_fields/<custom-field-id>" \
       -H 'Authorization: Token token=YOUR-API-TOKEN' \
       -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
       -d "name=new name"
  <?php

  // get cURL resource
  $ch = curl_init();

  // set url
  curl_setopt($ch, CURLOPT_URL, 'http://localhost:3000/api/v1/custom_fields/<custom-field-id>');

  // set method
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

  // return the transfer as a string
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  // set headers
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token token=YOUR-API-TOKEN"
  ]);
  // Create body
  $body = [
    "name" => "New name"
    ];
  $body = http_build_query($body);

  // Set body
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

  // Send the request & save response to $resp
  $resp = curl_exec($ch);

  if(!$resp) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
  } else {
    echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
    echo "\nResponse HTTP Body : " . $resp;
  }

  // Close request to clear up some resources
  curl_close($ch);
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/custom_fields/<custom-field-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "New name"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/custom_fields/<custom-field-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "New name"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

  {
    "custom_field": {
      "id": "cuf-d6d36b49-b509-433c-9e0c-8f60123176c7",
      "name": "new_name",
      "description": "a description"
    }
  }

PATCH https://s01.bilendo.de/api/v1/custom_fields/<custom_field-id>

Get all Custom Fields

  curl "http://localhost:3000/api/v1/custom_fields" \
       -H 'Authorization: Token token=YOUR-API-TOKEN'
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/custom_fields');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/custom_fields')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/custom_fields",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

  {
    "custom_fields": [
      {
        "id": "cuf-d6d36b49-b509-433c-9e0c-8f60123176c7",
        "name": "new_name",
        "description": "a description"
      },
      {
        "id": "cuf-f39de647-137f-42b7-bfd3-d0c4e98fe94c",
        "name": "a_name2",
        "description": "a description2"
      }
    ],
    "meta": {
      "current_page": 1,
      "next_page": null,
      "prev_page": null,
      "total_pages": 1,
      "per_page": 100,
      "total": 2
    }
  }

API Endpoint

GET https://s01.bilendo.de/api/v1/custom_fields

Delete Custom Field

  curl -X "DELETE" "http://localhost:3000/api/v1/custom_fields/<custom-field-id>" \
       -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/custom_fields/<customer-field-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/custom_fields/<customer-field-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Delete.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.delete(
      url = "https://s01.bilendo.de/api/v1/custom_fields/<customer-field-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

Action Response Code
delete 204 (No Content)

API Endpoint

DELETE https://s01.bilendo.de/api/v1/custom_fields/<custom_field-id>

Account

Data Reset

Request

curl -X "PUT" "https://s01.bilendo.de/api/v1/reset" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/reset');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/reset')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Put.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
    response = requests.put(
        url = "https://s01.bilendo.de/api/v1/reset",
        headers = {
            "Authorization": "Token token=YOUR-API-TOKEN"
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response (Status: 202)

{
  "message": "Your company data was is being reset. Go to 'api/v1/status' for live poll."
}

Resetting your company data means the following data will be destroyed:

Your company and user settings will remain unchanged.

Status code Message
202 Accepted – Your company data is being reset. Go to ‘api/v1/status’ for live poll.
403 Forbidden – You are not allowed to reset this company data

API Endpoint

PUT https://s01.bilendo.de/api/v1/reset

Data Status

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/status/" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/status');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/status')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
    response = requests.get(
        url = "https://s01.bilendo.de/api/v1/status",
        headers = {
            "Authorization": "Token token=YOUR-API-TOKEN"
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response

{
  "invoices":0,
  "reminders":0,
  "customers":0,
  "contacts":0,
  "payments":0
}

This endpoint allows you to view your current data count for all:

API Endpoint

GET https://s01.bilendo.de/api/v1/status

Current Costs

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/billing" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/billing');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/billing')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
    response = requests.get(
        url = "https://s01.bilendo.de/api/v1/billing",
        headers = {
            "Authorization": "Token token=YOUR-API-TOKEN"
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response (Status: 200)

// without plan upgrade
{  
   "current_stats":{  
      "period_start_date":"2016-09-01",
      "period_end_date":"2016-09-30",
      "selected_plan":"Automatic",
      "invoices_inclusive":250,
      "invoices_processed":0,
      "shippings_ntl_count":0,
      "shippings_intl_count":0,
      "shippings_email_count":0,
      "shippings_additional_count":0
   },
   "current_billing":[
      {  
         "period_start_date":"2016-09-01",
         "period_end_date":"2016-09-30",
         "selected_plan":"Automatic",
         "plan_total":"99.0",
         "shippings":{  
            "shipping_ntl_total":"0.0",
            "shipping_intl_total":"0.0",
            "shipping_additional_total":"0.0"
         }
      }
   ]
}
// with plan upgrade
{  
   "current_stats":{  
      "period_start_date":"2016-09-01",
      "period_end_date":"2016-09-30",
      "selected_plan":"Automatic",
      "invoices_inclusive":250,
      "invoices_processed":0,
      "shippings_ntl_count":0,
      "shippings_intl_count":0,
      "shippings_email_count":0,
      "shippings_additional_count":0
   },
   "current_billing":[  
      {  
         "period_start_date":"2016-09-01",
         "period_end_date":"2016-09-10",
         "selected_plan":"Basic",
         "plan_total":"9.67"
      },
      {  
         "period_start_date":"2016-09-11",
         "period_end_date":"2016-09-30",
         "selected_plan":"Automatic",
         "plan_total":"66.0",
         "shippings":{  
            "shipping_ntl_total":"0.0",
            "shipping_intl_total":"0.0",
            "shipping_additional_total":"0.0"
         }
      }
   ]
}

This endpoint allows you to view all relevant dates and amounts about your expences incurred in the current month:

Attribute type Description
current_stats object object containing all relevant dates and amounts about your expences incurred in the current month
current_billings array array containing objects with the current costs.
(If you upgrade your plan, there will be multiple entries.)

Current Stats

Attribute type Description
period_start_date date start date of your current billing period
period_end_date date end date of your current billing period
selected_plan string your currently selected plan
invoices_inclusive integer amount of inclusive invoices per period
invoices_processed integer amount of processed invoices per period
shippings_ntl_count integer amount of postal shippings (Germany) per period
shippings_intl_count integer amount of postal shippings (international) per period
shippings_email_count integer amout of email shippings per period
shippings_additional_count integer amount of additional invoices per period

Current Billings (per plan)

Attribute type Description
period_start_date date start date of your current billing period
period_end_date date end date of your current billing period
selected_plan string your selected plan
plan_total decimal total costs for your selected plan
shippings object object containing costs for shipping
shipping_ntl_total decimal costs for postal shipping (Germany)
shipping_intl_total decimal costs for postal shipping (international)
shipping_additional_total decimal costs for additional shippings

API Endpoint

GET https://s01.bilendo.de/api/v1/billing

Errors

HTTP Status

The Bilendo API uses the following HTTP error status codes:

Status code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API token is wrong
403 Forbidden – The server understood the request but refuses to authorize it
404 Not Found – The specified object could not be found
405 Method Not Allowed – You tried to access our API with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The object requested has been removed from our servers
412 Precondition Failed – The server does not meet one of the preconditions that the requester put on the request
418 I’m a teapot
422 Unprocessable Entity – The object is not valid
429 Too Many Requests – You’re requesting too many objects! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Bilendo Error Codes

Request

# Scenario: Creating a new customer with an existing name, customer_number and external _id

curl -X "POST" "https://s01.bilendo.de/api/v1/customers/" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "customer_number=<existing-customer-number>" \
  -F "external_id=<existing-external-id>" \
  -F "name=<existing-name>" \

Response

{
  "error": [
    {
      "name": {
        "title": "Es existiert bereits ein Kunde mit diesem Namen.",
        "code": 1001
      }
    },
    {
      "customer_number": {
        "title": "Es existiert bereits ein Kunde mit dieser Kundennummer.",
        "code": 1002
      }
    },
    {
      "external_id": {
        "title": "Es existiert bereits ein Kunde mit dieser externen ID.",
        "code": 1003
      }
    }
  ]
}

Error Code Object Meaning
1000 Customer The customer name cannot be blank
1001 Customer The provided customer name already exists
1002 Customer The customer number already exists
1003 Customer The provided customer external_id already exists
1004 Customer The provided customer cannot be found
1005 Customer The provided customers group cannot be found
2000 Contact The customer_id can’t be blank
2001 Contact The contact email already exists
2002 Contact The provided contact cannot be found
2003 Contact The provided contact external_id already exists
2004 Contact The provided email is invalid
3000 Invoice The invoice file was not provided or is invalid
3001 Invoice The provided invoice external_id already exists
3002 Invoice The invoice attachment file is invalid
4000 Payment The provided payment external_id already exists
4001 Payment The amount cannot be greater than the invoice amount
4002 Payment The amount cannot be equal or lower than zero
5000 Customer Group The customers groups module is not active
5001 Customer Group Customers not provided
5002 Customer Group Customers not found

Email dropbox

The email dropbox allows you to import invoices by sending an email to your Email-Dropbox address (eg: IMFjM4gAL5A24w@bilendo.com). Find this in your account settings

Attachments

All attached files with the format .pdf will be imported as invoices.

If you send additional PDF files together with your invoices (e.g. terms of service), please contact our support team at support@bilendo.de.

Restrict Senders

By default, anyone can send files to your Email-Dropbox address. However, this can be restricted to one or multiple senders.

To add or change your allowed senders, go to your Bilendo-Account under your account settings


Webhooks

Webhooks allow you to set a URL or E-Mail to which you receive a notification whenever a status code of an invoice changes. Find this in your account settings

Usage

In order to start using webhooks go to account settings. Here you can find a list of existing webhooks.

To update/delete or view details of the existing webhook click ‘Details’.

To add a new webhook click 'WebHook hinzufügen’.

If your webhook URL requires basic HTTP authentication please add username and password. Otherwise, please leave these optional fields blank.

If you want to get the notification delivered to an E-Mail address, then you can choose between two different formats. The format “raw” means, that Bilendo sends an Email with the JSON of the Invoice as content. This format is the best choice if you want to process the content with software. The format “readable” results in a HTML-Email that is designed for humans.

Possible values for trigger_status

In order to subscribe to all events listed below use “all” as trigger_status in your request.

{
  "webhook_notification": {
    "id": 859645991,
    "created_at": "2016-01-18T13:53:32+01:01",
    "trigger_status": "sent"
  },
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "sent",
    "invoice_number": "400001",
    "bilendo_url": "https://www.bilendo.de/xxxxxxxx/invoices/<invoice-id>",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "interest_fee": "0.0",
    "distortion_fee": "0.0",
    "fees": "0.0",
    "source": "API",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [
      {
        "id": "<payment-id>",
        "external_id": "<your-payment-id>",
        "amount": "611.9",
        "purpose": "ReNr 400001",
        "name": "Company Inc.",
        "account_numer": "DE123456789101112",
        "bank_code": "DEUTDE1234",
        "bank_name": "Example Bank",
        "currency": "EUR",
        "payment_date": "2015-12-01",
        "note": "Lorem Ipsum",
        "source": "API",
        "inkasso_payment": "false",
        "created_at": "2016-04-04T14:53:10+02:00",
        "updated_at": "2016-04-04T14:53:10+02:00"
      }
    ]
  }
}
Value Description
draft invoice is a draft
sent invoice was sent
due invoice is due
ready_for_reminder1 invoice is due and you should send a first reminder
reminder1_sent first reminder was sent
ready_for_reminder2 invoice is due and you should send a second reminder
reminder2_sent second reminder was sent
ready_for_reminder3 invoice is due and you should send a third reminder
reminder3_sent third reminder was sent
ready_for_debt_collection invoice is still due after a third reminder was sent and you should send the invoice to a debt collection service
sent_to_debt_collection invoice was sent to a debt collection service
written_off invoice was written_off
written_off_reverted invoice is not written_off anymore
paid invoice is paid
partial_payment partial payment was added
payment_removed a payment was removed from an invoice
archived invoice was archived
deleted invoice was deleted
all subscription to all events listed above
due_since_x invoice is due for x number of days after a due date(e.g. due_since_30). The maximum allowed number of days is 365. Warning: this event is not included in “all” subscription.*

*in order to subscribe to all events including this event, you must set a number of days and provide due_since_x in addition to 'all’(e.g. events = ['all’, 'due_since_30’])

Receiving notifications

Once you set a URL and selected notifications you will receive notifications in the format as shown on the right hand side.

Notifications always contain a current/latest status. A notification is considered to be successfully sent if we get a response with a request status code 200 within 10 seconds after a request has been made. Otherwise we will trigger up to 19 additional attempts until we get a response with a status code 200. If we get a status code of 400, we will not retry anymore.

Notifications are sent in the order they were created. However, it is also possible that during the retry process of sending a previously unsuccessfuly sent notification, an invoice status might change and in that case, another notification is sent. In this case, you can easily sort received notifications in a chronological order, by:

Intervals between repeated attempts

Attempt number Time in seconds
1 0
2 1
3 2
4 4
5 8
6 16
7 32
8 64
9 128
10 256
11 512
12 1024
13 2048
14 4096
15 8192
16 16384
17 32768
18 65536
19 131072
20 262144


Webhook Object

{
  "webhook": {
    "id": "<webhook-id>",
    "notification_type": "url",
    "url": "https://your.webhook.url",
    "email": "",
    "email_format": "raw",
    "events": ["sent","ready_for_reminder1"],
    "username": "carl_2017",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T15:53:10+02:00"
  }
}
Attribute Type Description
id string Bilendo Id of the Webhook
notification_type string email or url, default is url
url string Webhook URL
email string Webhook Email
email_format string raw (json) or readable (html)
events array of strings A list of trigger_status values
username string
password string

Create a new Webhook

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/webhooks" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "notification_type=url" \
  -d "url=<webhook-url>" \
  -d "events[]=sent&events[]=ready_for_reminder1" \
  -d "username=<webhook-auth-username>" \
  -d "password=<webhook-auth-password>" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "notification_type" => "url",
  "url" => "<webhook-url>",
  "events" => ["sent","ready_for_reminder1"],
  "username" => "<webhook-auth-username>",
  "password" => "<webhook-auth-password>"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "notification_type" => "url",
    "url" => "<webhook-url>",
    "events" => ["sent","ready_for_reminder1"],
    "username" => "<webhook-auth-username>",
    "password" => "<webhook-auth-password>"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
    url = "https://s01.bilendo.de/api/v1/webhooks",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    },
    data = {
     "notification_type":"url",
     "url":"<webhook-url>",
     "events":["sent","ready_for_reminder1"],
     "username":"<webhook-auth-username>",
     "password":"<webhook-auth-password>",
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response


{
  "webhook": {
    "id":"<webhook-id>",
    "notification_type":"url",
    "url":"<webhook-url>",
    "email":"",
    "email_format":"raw",
    "events":["sent","ready_for_reminder1"],
    "username":"<webhook-auth-username>",
    "created_at":"2017-05-18T11:43:20+02:00",
    "updated_at":"2017-05-18T12:43:20+02:00"
  }
}

Parameter Type Description
notification_type optional url or email, fallback to url if not provided
url mandatory if notification_type=url Webhook URL
email mandatory if notification_type=email Webhook Email
email_format optional raw or readable, fallback to raw if not provided
events mandatory A list of trigger_status values
username optional only for notification_type=url
password optional only for notification_type=url

API Endpoint

POST https://s01.bilendo.de/api/v1/webhooks

Get Webhooks

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/webhooks" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/webhooks",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "webhooks":[
    {
      "id":"<webhook-id>",
      "notification_type":"url",
      "url":"<webhook-url>",
      "email": null,
      "email_format": "raw",
      "events":["sent","ready_for_reminder1"],
      "username":"<webhook-auth-username>",
      "created_at":"2017-05-18T11:43:20+02:00",
      "updated_at":"2017-05-18T12:43:20+02:00"
    },
    {
     "id":"<webhook-id2>",
     "notification_type":"email",
     "url":"",
     "email": "email@example.com",
     "email_format": "raw",
     "events":["paid", "sent","reminder3_sent"],
     "username":"",
     "created_at":"2017-05-19T14:43:20+02:00",
     "updated_at":"2017-05-19T15:43:20+02:00"
    }
  ]
}

API Endpoint

GET https://s01.bilendo.de/api/v1/webhooks

Find a specific Webhook

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks/<webhook-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks/<webhook-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "webhook": {
    "id":"<webhook-id>",
    "notification_type": "url",
    "url":"<webhook-url>",
    "email": null,
    "email_format": "raw",
    "events":["sent","ready_for_reminder1"],
    "username":"<webhook-auth-username>",
    "created_at":"2017-05-18T11:43:20+02:00",
    "updated_at":"2017-05-18T12:43:20+02:00"
  }
}

API Endpoint

GET https://s01.bilendo.de/api/v1/webhooks/<webhook-id>

Update existing Webhook

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "url=<webhook-url>" \
  -d "events[]=paid&events[]=reminder1_sent" \
  -d "username=<webhook-auth-username>" \
  -d "password=<webhook-auth-password>" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks/<webhook-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "url" => "<webhook-url>",
  "events" => ["paid","reminder1_sent"],
  "username" => "<webhook-auth-username>",
  "password" => "<webhook-auth-password>"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks/<webhook-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "url" => "<webhook-url>",
    "events" => ["paid","reminder1_sent"],
    "username" => "<webhook-auth-username>",
    "password" => "<webhook-auth-password>"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
         "url" => "<webhook-url>",
         "events" => ["paid","reminder1_sent"],
         "username" => "<webhook-auth-username>",
         "password" => "<webhook-auth-password>"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "webhook": {
    "id":"<webhook-id>",
    "notification_type":"url",
    "url":"<webhook-url>",
    "email": null,
    "email_format": "raw",
    "events":["paid","reminder1_sent"],
    "username":"<webhook-auth-username>",
    "created_at":"2017-05-18T11:43:20+02:00",
    "updated_at":"2017-05-18T12:43:20+02:00"
  }
}

Api Endpoint

PATCH https://s01.bilendo.de/api/v1/webhooks/<webhook-id>

Delete a Webhook

Request

curl -X "DELETE" "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/webhookapi/v1/webhooks/<webhook-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks/<webhook-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Delete.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.delete(
      url = "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

Action Response Code
delete 204 (No Content)

API Endpoint

DELETE https://s01.bilendo.de/api/v1/webhooks/<webhook-id>

Recent Changes

28.08.2018 Custom Fields for invoices

With custom fields, you can now add more data to your invoices. You can use this additianal data in your invoice- and reminder texts.

01.08.2018 more options for Webhooks

Bilendo can now send Webhooks via Email in two different formats.

26.07.2018 one field renamed

The fields dunning_stop and dunning_stop_date were added to the invoice and customer object. Two new filters for the invoices#index were added: dunning_stopped and dunning_not_stopped

25.07.2018 one field renamed

The old field “stop_automatic_reminders” of the customer object was renamed to dunning_stop. You can still use the old field in your API-Calls but the response will only contain the new field.

23.07.2018 new fields added

The fields purpose, name, account_numer, bank_code and bank_name where added to the payment part of an invoice object. The fields distortion_fees and interest_fees where added to the invoice and reminder objects.