API documentation

header__body--api-docs-page

header__body-mobile--api-docs-page

Welcome to Billogram's API documentation!

This documentation will cover everything you need to know to integrate your service with our API. Have fun!

Back to API overview
Our API documentation is a bit lengthy and too complex to read on such a small screen, we recommend you to visit this page on a bigger device, such as a tablet or a desktop.

If you only want a brief overview of the API, you can read more here.

1. Sign up

First off, you need to register an account. We recommend that you sign up on our sandbox environment first, where it’s possible to test your code before it’s shipped into production.

2. Generate an API user

Log in to your newly created or existing account, whether it’s in the sandbox environment or not. An API user and key can be generated on the bottom of the Settings page for authorizing to the API.

3. Start developing

There are two libraries available for Python and PHP which you can find on Github. Both of the libraries have code examples that we recommend you to look through and test before you get started. If you are developing in another language, we have a full list of all functions in the documentation.

4. You’re done!

When you have finished and tested the integration in our sandbox environment, all you need to do is generate an API user and key in your company’s account, and then you’re done! Now you’re all set to start invoicing!

It’s easy to get started!

Create an invoice
from billogram_api import *
api = BillogramAPI(api_username, api_authkey)
billogram = api.billogram.create_and_send({
    ‘customer’: {‘customer_no’: 1},
    ‘items’: [
        {
            ‘item_no’: ‘2’, ‘count’: 6
        }, {
            ‘title’: ‘Work’, ‘unit’: ‘hour’,
            ‘vat’: 25, ‘price’: 300, ‘count’: 2.50
        }
    ]
}, ‘Email+Letter’)
# print the OCR number
print billogram.ocr_number

Conceptual overview

The Billogram API is built according to RESTful principles, which means it uses HTTP as an application protocol rather than just as a transport layer for a custom protocol, like SOAP does. In other words, HTTP features such as the various request types (GET, PUT, POST, DELETE), response codes (403 Forbidden, 404 Not Found, 500 Internal Server Error) and standard headers (Accept, Authorization, Cache-Control) are a part of the API.

Because HTTP is stateless (each request is completely stand-alone), so is the Billogram API. Each request that modifies a resource on the server is atomic: the modification is either carried through completely, or not carried through at all.

For security reasons, you must access the API via HTTPS. The server will reject any unencrypted requests.

The API_BASE for the API is https://billogram.com/api/v2 for production use. Read more about using the sandbox environment for testing further down in the documentation.

The URL structure is also a part of the API. As an example, consider this URL path:

URL path for item id 1234
/api/v2/item/1234

The /api/v2 part is the base part of the URL path and signifies that you are using version 2 of the API. The rest of the URL path describes the specific resource you are accessing. First, item describes the class of objects you are accessing. The URL path /api/v2/item is a valid resource: it represents all item objects belonging to your business account, and you could do a GET request to that URL path to fetch list of them, or a POST request to create a new item. However, in this case we're accessing /api/v2/item/1234, and 1234 is the ID of a specific item. Thus, this example URL path describes a specific object resource.

For authentication, the API uses HTTP Basic Access Authorization, which is quite simple: concatenate your API username, a colon and your password (i.e. username:password), base64-encode the resulting string and add the HTTP header Authorization: Basic <your base64-encoded string> to each request. This is covered in more detail below.

Data model overview

The following 4 concepts are central to the use of the Billogram service:

Billogram Represents a debt, usually one owed to your business by one of your customers. A billogram contains one or more items and is addressed to a recipient (a customer). A new billogram created via the API is not yet attested (in other words, approved). When the billogram is attested (either via the Billogram web site or via the API), it generates an invoice which is sent to the recipient. A billogram keeps track of its payment status.
Invoices Produced by Billogram objects and sent to customers. A Billogram can have more than one invoice, and invoices always belong to a single Billogram. (They cannot be created stand-alone, only through actions taken with the Billogram object). When the recipient has paid the current invoice belonging to a Billogram, the Billogram enters a "finished" state.
Customers Effectively contact book entries, customers are recipients of Billogram/invoices.
Items Products, services and other reasons to invoice customers. These objects exist stand-alone and can be re-used across many Billogram, but a Billogram can also include "single-use" items that do not exist as an object.

Additionally the API provides services to let applications manage settings for the business account on Billogram, including contact information, payment information and invoicing defaults.

In a fresh Billogram business account, to invoice a customer you will first need to ensure all required settings are configured. These can be accessed via the settings object, but for a first-time setup it's usually easier to simply enter the data using the Billogram web page.

Next, you must create a customer to send a Billogram to. This is done through the customer class. The customer created will be identified by a unique ID, customer_no.

The third step is to create the items that will be invoiced for, through the item class. The items will be identified by their unique item_no.

Finally, a billogram can be created. It is created for a specific customer, identified by their customer_no, and contains a number of items (either ones already existing in the Billogram database, or ones created with the billogram for single use on that billogram only) and the items by their item_no, additionally for each item a number of how many are being invoiced for is given, and any discount can be specified. The due-by date, reminder dates, fees and additional data can optionally also be specified. The billogram can be saved for later manual approval, sent to the customer right away, or be sold to a factoring partner if the Billogram business account has been approved for this.

When a billogram has been sent, additional actions can also be taken on it: Registering a payment received from the customer outside the payment services Billogram offers, crediting the customer the invoiced amount in part or whole, sending reminders, and more.

Conventions used in this documentation

The various object classes will be described separately, with references to other sections when appropriate.

For each class, the format of object structures is described. Each possible field is listed along with the data type it holds, a description of its purpose, validation constraints and more, the default value (or the result of leaving it out), and often some example values for it.

When a field in a structure contains a major sub-structure, that sub-structure is described in a separate section, which is then linked.

In many cases, leaving a field as null in the JSON sent to the API endpoint will have the same effect as leaving out the field entirely, but there may be cases where the effect is different. For this reason, it is strongly recommended to only send the minimum set of fields required to accurately describe the intended request.

Names of fields

Most often, structures and sub-structures are presented in a flat manner, i.e. a single level at a time. However at times it is necessary to refer to a field by its complete position in a structure, particularly when performing filtering in searches.

In this use, the field name is given as a "path", consisting of the names leading up to it, separated by colons.

For instance in the following structure:

JSON encoded data
{
    "name": "Sample",
    "address": {
        "street_address": "Somestreet 3"
    }
}

Here the street_address field inside the address sub-structure will be referenced as address:street_address. Meanwhile, the name field will just be written as name with no colons, since it is on the top level.

This notation is also used in error messages returned from the API, when e.g. a field validates wrong.

Data types commonly used

string A text string. Must always be a quoted string in the JSON, if other types are sent the result is undefined. Unless the description mentions it being free-form or similar, line breaks are not allowed. This is also used for more strictly defined data formats, e.g. e-mail addresses, or European VAT registration numbers; in those cases the expected format is given in the description.
number A number. Should always be sent as a JSON number, if other types are sent the result is undefined. The description will typically explain further limitations to the number expected, e.g. whether negative or zero values are allowed, whether non-integer values are allowed, and possible range values. This type is also used for currency amounts, in that case the currency the value is taken as will be mentioned in the description text.
numeric string A string containing decimal digits. Should always be sent as a JSON quoted string. This type is used for data that is numeric, but not numbers in the mathematical sense. This includes, for instance, bank account numbers, organisation registration numbers and such.
boolean A true or false value, sent as the respective JSON values. If other types are sent the result is undefined.
enumerated string A string where only a strict list of values are valid. The list of valid values is always given, or described, and specifying a value not in the list is an error.
enumerated number A number where only a strict list of values are valid. The list of valid values is always given, and specifying a value not in the list is an error.
timestamp string A date-time value. Should always be sent as a JSON string. The Billogram API uses ISO 8601 format for date-time values, except that a single space character is used to separate date and time, instead of an uppercase T (YYYY-MM-DD hh:mm:ss). The date-time is given in UTC.
date string A date value. Should always be sent as a JSON string. The Billogram API uses ISO 8601 format for date values (YYYY-MM-DD). When only a date value is expected, do not include a time part, even if it is zeroes.
array of type An array of another type, this must always be sent as a JSON array. All the values in an array must always be valid.
Named sub-structure Some fields will refer to a specific, named sub-structure. A link to the definition of that structure will be included. Some trivial structures are defined at the place they are used.

Default and required values

For each field in a structure it will be specified what the default value is, if the field is left out. For fields that must always be specified in a structure, required is written instead. There are also a couple other cases described below.

required The field must always be specified on an object. Note that this only applies when specifying a full object for creation, not when modifying an existing object via a partial structure.
required when condition Some fields are required only together with others, or only when others are left out. This particularly happens in the items sub-structures for billogram objects, where there are generally two ways of specifying an item to use.
blank When a field holds a string value, this indicates that the default for the field is the empty string.
generated or automatic Indicates that the Billogram service will determine this value, and it will be read-only. Attempting to set the value of a generated field will generally be an error.
automatic sequential number Indicates that the Billogram service will produce a new, unique number in sequence, if no other value is specified. The generated sequence may depend on the existing values present in the database, do not depend on specific values being generated. This field may be set and modified.
uses account default The field will be filled with the current default value from the business account settings.
blank (use account default) The field will default to the empty string. When it is referenced in other contexts internally by the Billogram system and is found to be blank, the related business account setting will be looked up and its value used.

Internet is internet – remember your error handling

Our API is built for the great Internet and lays behind all the layers of TCP connections. Please remember that timeouts may occur if a service provider is down or that you may get error codes from proxies or routers on your request even before you reach our API.

If you didn't get the expected result (which probably is a 200 OK on most cases) or that your connection unexpectedly dropped, we encourage you to verify that it's safe to try again before you actually make a second request. Nobody wants a bunch of extra invoices due to a wrongly configured network switch somewhere on your route.

General usage considerations

Request format

The API is accessed via HTTPS, authenticated by HTTP Basic authentication. See below for details.

When sending POST and PUT requests to the Billogram API the data must always be sent in JSON format, with the application/json content-type.

In requests to create or update remote objects, the request body must be a partial object of the appropriate type, containing just the fields to set or update. Note that you must never send read-only fields when creating or updating objects, even if the value given is identical to the current value.

In requests that send a command to an object (e.g. performing a crediting of a billogram) the request body must be a JSON object containing data appropriate for the type of command. See the documentation for each individual command for which fields are required.

If your language or framework does not allow you to send POST or PUT bodies in other formats than application/x-www-form-urlencoded (used for common HTML form submission), you can instead send your body by encoding your data to JSON, URL-encoding the resulting string, and passing it as a single post-data field which must be named json.

For instance, the following two HTTP requests (shortened for exposition) are handled the same by the Billogram API:

HTTP request using plain JSON
PUT /api/v2/item/4 HTTP/1.1
Host: billogram.com
Authorization: Basic <auth-data>
Content-Type: application/json

{ "title": "Shipping & handling" }
HTTP request using encoded JSON
PUT /api/v2/item/4 HTTP/1.1
Host: billogram.com
Authorization: Basic <auth-data>
Content-Type: application/x-www-form-urlencoded

json={+"title":+"Shipping+%26+handling"+}

The response will always be a JSON document and have content-type application/json. The response document will contain the request status and any extended status information (such as detailed error diagnostics), as well as possibly the updated data for the object the request was made to. Note that successful DELETE requests have an empty response body, since the object in question was deleted.

Authentication

The Billogram API uses HTTP Basic authentication. You obtain a username and password for API use at the bottom of the company settings in the regular user interface.

Example image of API settings in web interface
image of add api users

You can have multiple username/password combinations for API use, for instance if you need multiple applications to have access. This will also allow you to rekove access for a single application if required.

For security reasons, it’s not possible to create or change API users using the API without specific access.

The HTTP authentication must be included with every request sent. There is no concept of a session or similar. There are no actions that can be performed without authentication.

The API is only available over HTTPS secure connections.

Callbacks

Whenever something happens with a billogram, an event will be added to the event-list of the billogram and a callback will be sent to a specified URL to let you know about the change.

Each callback will be sent as a HTTP POST request with JSON-encoded data as its body. A signature parameter is included and may be used to verify the request's authenticity. You can read more about which parameters to set for the signature key as well as the callback URL or see the full specification about which parameters are included in the callback later on.

Search query parameters

All requests to list/search objects of a specific class follow the same pattern, which is described here. Note that the terms "filtering" and "searching" are used to mean the same here.

There are two primary things to consider when searching. First, it is only possible to filter based on a single field at a time. (A syntax to search multiple fields may be added later.) Second, searches always return results paged, there is no mechanism to always fetch all results in one go.

Each class has its own set of fields that can be searched on, and for most fields it is possible to use one of a few different conditions.

A search request is performed with HTTP GET, and takes the following query parameters in the request path:

Name Description Default
page

Integer. The result page number to fetch. The first page has number 1 (one).

required
page_size

Integer. How many results to return per page. Settings this number too high may impact performance, we recommend values between 10 and 100.

required
filter_type Enumerated string. The kind of search to perform. if left out no filtering is performed
Type
Function
field
Exact match for the given field
field-prefix
Match a prefix for the given field
field-search
Match any substring in the given field
special
Perform a special search
filter_field

Enumerated string. Name of the field to search in. The available fields depends on the class the request is made to.

required when filtering is performed
filter_value

String. The value to search for.

required when filtering is performed
order_field

Enumerated string. Name of the field to order the results by. The available fields depends on the class the request is made to.

if left, out, an arbitrary ordering is used
order_direction

Enumerated string. Whether to use ascending or descending ordering for the field specified. Valid values are: asc, desc

required when order_field is specified

It's worth noting that when filtering is performed, all of filter_type, filter_field and filter_value must be specified. When ordering is performed, both order_field and order_direction must be specified.

Each class has both regular and special fields that can be filtered by. The regular fields are generally a subset of those available in the structure. The field names are specified in path form, with colon-separated elements. The special fields do not have a direct representation in the structure, and are used for special queries such as a full-text search across multiple fields, or some limited reporting features.

In search responses, the data field in the returned JSON contains an array of results for the requested page. There is also an additional field in the returned JSON named meta, which contains a structure with aggregated information about the result set; this meta-information applies across all pages of the results, not just for the requested page. Most importantly, it contains the total_count field, which gives the total number of results matched for the given query, regardless of the requested page and page size.

The billogram class has some additional search options, which are described on its search call.

Error handling

The Billogram API always uses HTTP status code 200 to indicate success, no other 2xx codes are used.

Additionally, no 1xx or 3xx codes are expected to be sent. If you receive any of these, you can assume you are not accessing the API.

Errors with a HTTP response code of 500-599 indicate internal problems with the Billogram service, and are not covered here. Assume that 5xx errors are transient problems and try again later.

HTTP status codes in the range 400-499 indicate an error caused by the request, either due to missing or invalid values, or because of some other condition related to the sent request. These error responses are always accompanied with a JSON document detailing the error. The form of these JSON error responses is detailed here, as are some general errors that can occur.

Example of an error response
{
    "status": "UNKNOWN_PARAMETER",
    "data": {
        "message": "unexpected key: item_id",
        "field": "item_id",
        "field_path": []
    }
}

The above example is how an error response could look if an application tried to create an item with a "item_id" field, which does not exist. The HTTP status code would be 400, the content-type be application/json, and the response body contain the above JSON document.

An error response has a structure similar to the following. It may also have some additional fields, depending on the exact error, but the following are the common ones.

Name Description
status

string

The status name for the error. See list below for possible values. If no error occurred, this field will be "OK".

data

When the status field indicates an error, this contains a sub-structure describing the error in more detail.

Name
Description
message

string

Human-readable message for the error. You should not attempt to parse these, the message for a particular error condition may change without warning. The messages are intended to be helpful to developers, but may not be suitable for displaying to an end user.

field

string

Not always present. Only present for errors where the cause is the value (or presence/absence) or a single particular field. Contains the name of the offending field. Note that this only contains the name of the innermost field, if the field is in a sub-structure, the path to the field is given in the field_path field.

field_path

string

Not always present. Present when the field field is. Contains the names of the fields leading to the error-field, but not the error-field itself. The entries in this array may be both strings and integers, integers are used when an array is involved in the path.

For instance, if there was a problem with the title field of the third item row on a billogram, the field field would contain "title", and the field_path field would contain ["items", 2].

The following is a list of common errors that can occur.

Error name HTTP status Description
MISSING_AUTH 401 The authentication credentials are missing. The request did not include an HTTP Authorization header as described in the section on authentication and was rejected. This response includes a WWW-Authenticate header indicating to HTTP clients that they need to send HTTP Basic authentication credentials; for some HTTP libraries receiving this response first may be expected behaviour.
INVALID_AUTH 403 The API user and key combination used to authenticate is not valid. Either one of them is wrong, or the credentials have been revoked.
PERMISSION_DENIED 403 The API user does not have permission to perform the request. Authentication succeeded, but the credentials used do not have sufficient permissions to perform the operation.
NOT_FOUND 404 The request was sent to a specific object of a class, but the object id (ID) specified in the URL does not exist. If the ID was obtained from a previous request, the object might have been deleted in the meantime.
NOT_AVAILABLE_YET 404 The requested object does not exist yet, but is in the process of being created. Try again later.
METHOD_NOT_ALLOWED 500 The request used a HTTP method not allowed for the resource. Ensure all calls made correspond to those documented here.
MISSING_QUERY_PARAMETER 400

When performing a search/filter request, a required query parameter was missing. See the section on search queries above for more information about the required parameters.

This may include the field specification for the missing parameter.

INVALID_QUERY_PARAMETER 400

When performing a search/filter request, a query parameter was given an invalid value. See the section on search queries above for more information about the valid values for the query parameters.

This typically includes the field specification for the incorrect parameter.

INVALID_PARAMETER 400

A field in the request JSON data has an invalid value, wrong type or out of range. This error is caused by the request not adhering to the schema of the object structure, and can always be avoided by the client application.

This typically includes the field specification for the incorrect parameter.

INVALID_PARAMETER_COMBINATION 400 An illegal combiation of fields were given in the JSON. Either two fields were specified together when they may not occur together or a set of fields that must always occur together was missing one or more.
READ_ONLY_PARAMETER 400

A read-only parameter was given a value. These may never be given a value when the client application sends data to the Billogram API, they only contain information from the Billogram API to the client.

This typically includes the field specification for the offending parameter.

UNKNOWN_PARAMETER 400

A field with an unknown name was given in the JSON. Check that the JSON only contains legal fields, and check the spelling of all field names.

This typically includes the field specification, naming the unknown parameter.

INVALID_OBJECT_STATE 400 The request is not possible in the current state of the object. This mainly applies to billogram objects.

Billogram / Invoices

About billogram objects

A billogram is a collection of related invoices, and the base information used to create them. To invoice a customer, you create a billogram with the items to be invoiced for, assign the customer to it, and attest it by performing the send command. This generates an initial invoice to the customer. If circumstances later change and you need to e.g. credit part of the invoice, the credit invoice for this will be added to the same billogram, keeping related information together. The billogram object also lets you change the items invoiced for after sending the invoice, in this case the Billogram service will intelligently create additional regular invoices and credit invoices as required to ensure the customer pays the correct amount.

In the Billogram system, invoices are represented as sub-objects of billogram objects, and invoices are immutable. Changes to the billogram object will rather generate new invoices.

A billogram object also contains a complete history of all activity relating to it, such as it being created, invoices sent, payments received, reminders sent, and so on.

Billogram object structure

The billogram object is somewhat complex, but many parts are optional and only need to be specified in special cases. Leaving out optional parts will cause the defaults to be used, as in the web interface; this may often be the most desirable from a complexity of implementation perspective.

Name Description Default
id

string (read-only)

The unique ID for the billogram object. This ID is automatically generated when the billogram is first created, and can not be controlled by the application. The ID is the canonical way to refer to the billogram object through the API. Currently the ID is a string of 7 alpha-numeric characters (case-sensitive), but the length of the field may be extended in the future.

Example generated value: "2kAEEjE"

generated, read-only
invoice_no

number (read-only after creation)

When creating a billogram, this controls the invoice number used for the first invoice sent by the billogram. If the field is left out (or null) an automatic sequential number will be generated.

On already sent billogram objects this is the number of the latest valid invoice in the billogram. If changes are made to the billogram after sending it and this requires generating a new initial invoice, the invoice_no of the billogram will update to reflect this. The invoice_no parameter works a bit different when searching or querying for multiple billogram.

automatic sequential numbers
ocr_number

numeric string (read-only)

The OCR number used to identify payable invoices on the billogram. This is printed on the giro slip attached to printed invoices allowing electronic payments to register correctly. This is a unique value.

generated, read-only
customer

Billogram customer data sub-structure

Specifies the customer that is being invoiced.

required
items

Billogram items list

Array of the items that are being invoiced for.

required
invoice_date

date string

The original invoice date printed on the invoices. If specified, must be a string containing an ISO 8601 format date.

Example value: "2013-11-14"

time created
due_date

date string

Due date of the invoice. If specified, must be a string containing an ISO 8601 format date, and must be later than invoice_date. The Billogram service may perform additional checks to ensure legal requirements are fulfilled. There is no need to set both due_date and due_days.

Example value: "2013-12-16"

30 days after invoice_date (or depending on due_days)
due_days

number

Due days of the invoice. If specified, must be a postivie numeric integer. The due_date will be set automatically depending on invoice_date and due_days so there is no need to set both due_date and due_days.

30 days (or depending on due_date)
invoice_fee

number

Extra service fee to be added to the invoice. Specified in the invoicing currency, VAT exclusive. Will be printed on the invoice as an additional item line.

uses business account invoicing default
invoice_fee_vat

number (read-only)

The VAT calculated on the invoice fee. Given in the invoicing currency.

generated, read-only
reminder_fee

number

Fee added to the invoiced amount whenever the next late payment reminder is sent. Specified in the invoicing currency. Reminder fee for the next reminder will only be applied if no reminders has yet been sent for the billogram or if the already applied reminder fee for a sent reminder is 0 (for example if the billogram has been recently changed since the latest reminder or if the reminder fees has been written-off).

uses business account invoicing default
interest_rate

number

Yearly interest rate accrued if the invoice is not paid by the due date. Interest is calculated daily for each day over the due date (or at least 30 days after invoice_date). The interest rate must be specified in per cent, not the decimal rate. (E.g. you specify 8.5 for an 8.5 % interest rate, not 0.085.)

Example value: 8.5

uses business account invoicing default
interest_fee

number (read-only)

The calculated interest added to the invoice to date, based on the interest_rate. Given in the invoicing currency.

generated, read-only
currency

enumerated string

Currency the invoice is billed in.

Available currencies: SEK (Swedish Kronor)

"SEK"
info

Billogram additional information sub-structure

Contains additional information about the business errand invoiced for. Will be printed on the invoice. This data is purely informational to the customer and does not affect the invoicing logic.

see sub-structure section
regional_sweden

Billogram Swedish regional data sub-structure

Contains special options available under Swedish law.

see sub-structure section
delivery_method

enumerated string

The last method used to deliver an invoice to the customer. This value is set by the delivery method specified when sending the billogram.

Can be one of the following: Email+Letter, Email, SMS+Letter, SMS, Letter, Efaktura.

The value of the field can be changed only after the billogram has been sent and can be set only to Email, SMS or Letter.

generated
state

string (read-only)

Current state of the billogram. See the section on billogram states for details of the values that can occur here.

generated, read-only
url

string (read-only)

URL to the web version of the billogram. This is almost the same URL that is sent to the customer_email (though, in this URL we're excluding the accept-pin that is being sent in the email) when sending the billogram as email. This value may be null. This value is null if the invoice has not yet been sent, or the invoice has been sold. Please note that if you're sending a billogram with email, give out this URL and the recipient who then uses this URL instead of the one in the email, the billogram will not be marked as read (since they need to click the link in the email for proper delivery accept). Because of this we recommend against using it if delivery method is set to Email+Letter or SMS+Letter.

generated, read-only
flags (read-only)

array of enumerated string

Array of flag strings describing various details of the current state of the billogram.

For the possible flag values, see the section about billogram flags.

generated, read-only
events (read-only)

Billogram events list

Array with the event history of the billogram. Only the latest 100 events will be returned. If you have a billogram with lots of changes and history you can query the billogram_event resource for more events.

generated, read-only
remaining_sum

number (read-only)

Amount left to be paid by the customer, given in the invoicing currency, including the calculated VAT. This value is calculated automatically.

generated, read-only
total_sum

number (read-only)

The total amount the customer has been ordered to pay, given in the invoicing currency, including the calculated VAT. This value is calculated automatically.

generated, read-only
rounding_value

number (read-only)

Amount added or subtracted from the total invoice sum to round it to a whole number, given in the invoicing currency. This may be null if rounding was not performed on the billogram.

generated, read-only
automatic_reminders

boolean

Whether to use automatic reminders or not for this billogram. Uses automatic_reminders_settings if specified, otherwise uses business account's settings. If set to false no automatic reminders at all will be sent for this billogram.

true
automatic_reminders_settings

Automatic reminder data array

Set of late payment reminders to use for this billogram. If this parameter is submitted it will default automatic_reminders to a true value, unless automatic_reminders is sent in the same request. If set to empty array [] it forces automatic_reminders to be set as false regardless of what was specified in the request data. If set to null business account's default settings are used for this billogram.

uses business account invoicing default
reminder_count

number (read-only)

The number of reminders that has been sent for the billogram.

generated, read-only
created_at

timestamp string (read-only)

Timestamp the billogram object was first created at, automatically generated. Given as a date-time string in UTC.

generated
attested_at

timestamp string (read-only)

Time the billogram was originally attested (sent or sold), this may be null if the billogram has been created but not attested yet. Given as a date-time string in UTC.

generated, read-only
updated_at

timestamp string (read-only)

Timestamp the billogram object was last modified at, automatically generated. Given as a date-time string in UTC.

generated, read-only
callbacks

Billogram callbacks sub-structure

Requests for the Billogram service to actively call back when an event occurs on the billogram.

see sub-structure section
detailed_sums

sub-structure with detailed sums (read-only)

These are the same summary values that we show in the Billogram web frontend when you're viewing an invoice.

read-only
attachment

string

The name of the file attached to the Billogram. This value is null if no attachment is found.

generated
automatic_collection

Automatic collection sub-structure (or null)

Automatic collection settings for this billogram. If set up, the billogram will be automatically sent to collection if still unpaid after a set amount of days since due date / last reminder. Requires a collection agreement.

null

Compact structure

This compact structure is used when returning results from a search request. It only contains the key information for a billogram, but the full data can be requested by fetching the individual billogram objects by their ID.

Name Description
id

string

Unique ID of the billogram. Can be used to fetch the full billogram object.

invoice_no

string

Number on the latest main invoice on the billogram. Will return a null value if the billogram is not attested yet. If you've set invoice_no yourself and need to know the value of an unattested billogram, you will have to get the data for that specific object.

state

enumerated string

Current state of the billogram. See the section on billogram states for details of the values that can occur here.

flags

array of enumerated string

Details of the current state of the billogram. See the main flags property for a list of valid values.

invoice_date

date string

Invoice date printed on the invoice. Given as an ISO 8601 date string.

due_date

string

Due-by date for the invoice. Given as an ISO 8601 date string.

currency

enumerated string

Currency the invoice is billed in.

ocr_number

numeric string

OCR number for electronic bank payment of the invoice.

remaining_sum

number

Amount left to be paid by the customer, given in the invoicing currency, including the calculated VAT.

total_sum

string

The total amount the customer has been ordered to pay, given in the invoicing currency, including the calculated VAT.

created_at

timestamp string

Timestamp the billogram object was first created at. Given as a date-time string in UTC.

updated_at

timestamp string

Timestamp the billogram object was last updated at. Given as a date-time string in UTC.

customer

Billogram customer sub-object

Object containing information about the customer of the billogram.

Name
Description
customer_no

number

The customer number that was invoiced. Can be looked up in the customers class.

org_no

string

The organisational or personal number of the customer.

name

string

Customer name given on the invoice.

email

string

Customer e-mail address used for the invoice.

Billogram customer data sub-structure

This sub-structure specifies the recipient of the billogram, i.e. which customer the billogram will be sent to.

When creating a billogram you can only specify customer_no of these, the other fields will be filled in automatically from the customer information in the database. After the billogram object has been created the customer information stored in it can be changed.

The link from a billogram to the customer is "soft", meaning that if the customer object is updated, the customer data in the billogram are not affected. Similarly, changing the customer information in the billogram object does not affect the original customer object.

Prior to creating the billogram (invoice) you must already have created the customer, via a POST API request to customer.

Name Description Default
customer_no

number

Customer number of the recipient of the billogram. This field is required when creating a billogram, and becomes read-only after the billogram object has been created. (It is not possible to change which customer a billogram was sent to.)

required
org_no

numeric string

Organisational or personal number of the customer, depending on the customer type.

filled from specified customer object
name

string

Name of the customer, business name or person name, depending on the customer type.

filled from specified customer object
email

string

E-mail address of the customer.

filled from specified customer object
vat_no

string

European VAT-registration number of the customer.

filled from specified customer object
phone

string

Phone number of the customer.

filled from specified customer object
address

Billogram customer address sub-object

Address to the customer. Contains the following fields, with the same meanings as on a regular customer object.

Field name
Type
street_address
string
city
string
zipcode
string
country
enumerated string
careof
string (only one of careof or attention could be set, they cannot be combined)
attention
string (only one of careof or attention could be set, they cannot be combined)

Billogram items list

The items on a billogram is an array of billogram item structures. Even when only a single item is being invoiced, an array must still be given for the items field in the main billogram structure.

When modifying an existing billogram and the items field is specified, the list of items in it will always completely replace the old list of items. For instance, to remove a single item from a billogram, you would fetch the original billogram, copy the old items list, remove the desired item from it, then send back the new item list. Similar for adding items to the list, and editing items on the list; the entire original list must be specified with the changes made to it.

By specifying an item_no that already exists in the item database, the data from that item object will be used as a base for the remaining fields. However the items database will not be updated by overriding fields in a billogram items list, and new entries in the items database can not be created this way either.

Each element of the items list is a structure with the following fields.

Name Description Default
item_no

string

Number of the item. If an item with the given number already exists in the items database, the data for that item will be used where it isn't overridden. If no item number is given, or a non-existing one is given, a single-use item is created, which only exists for the billogram it is used on. The max length for item_no is 30 characters IF the value is non-numeric, otherwise (if the value is numeric) the max value is 999999999.

blank (required unless title, price, unit and vat are all given)
count

number

The number (amount) of the item that is being invoiced. The value can be any whole or decimal number.

always required
title

string, max 40 characters

Primary (short) name for the item being invoiced.

filled from specified item object or required if a blank or non-existent item_no is specified
description

string, max 200 characters

Free-form description text for the item being invoiced.

filled from specified item object or blank
unit

enumerated string

Unit of measure for the item. See the primary item structure for the valid values.

filled from specified item object or required if a blank or non-existent item_no is specified
price

number

Cost per unit of the item. This value may be zero.

filled from specified item object or required if a blank or non-existent item_no is specified
vat

number

VAT rate for the item being invoiced. This must be a numeric value between 0 and 100. See the primary item structure for the valid values.

filled from specified item object or required if a blank or non-existent item_no is specified
discount

number

Discount to be applied to the total (ex. VAT) sum for the item, given in the invoicing currency.

0 (zero)
bookkeeping

Billogram item bookkeeping information object

Sub-object describing bookkeeping information for this item. If left out, an empty object is created automatically and the default values will be used. See below for structure.

default values of item bookeeping information object
regional_sweden

Swedish regional data sub-structure

Whether this item affects ROT/RUT deductions under Swedish taxation law or is used for electicity collection.

Field name
Description Default
rotavdrag

boolean

false
electricity_collection

Billogram item electricity collection information object

Sub-object describing electricity collection information for this item. If left out, an empty object is created automatically and the default values will be used. See below for structure.

default values of item electricity collection information object

Billogram item bookkeeping information objects

This is a sub-object of billogram item objects. The information in this object is used for generating bookkeeping files from paid invoices. It has the following fields.

Name Description Default
income_account

string

Account number for payments received for this item. If left out or blank, the item uses the default account set up. If the value is blank or null, the default income account will be populated to the field when the billogram is attested.

blank (will use account default)
vat_account

string

Account number for VAT payments received for this item. If left out or blank, the item uses the default account set up. If the value is blank or null, the default income account will be populated to the field when the billogram is attested.

blank (will use account default)
objects

objects list (array)

This is for objects and dimensions in accounting.

Swedish: Objektredovisning – resultatenheter, dimensioner)

Array of the bookkeeping objects and dimensions that are connected to this item (and in turn, this income account). This is only needed if you need very specific bookkeeping.

For each object in the list, the following parameters should be specified.

[]
Field name
Description
dimension_id

number, should be 1-6 characters

Dimension for your object, the values 1-19 may be used, but are reserved for standardized dimensions (for example 1 is 'Avdelning / kostnadsställe / resultatenhet', 7 is 'Anställd / anställningsnummer'). Values over 20 should have a custom dimension_name set.

Some bookkeeping applications require the dimension_id to be a numeric value between 1 and 999999.

dimension_id and object_id are required for each object.

object_id

string

An identifier for this object.

Some bookkeeping applications require the object_id to be a numeric value between 1 and 999999.

dimension_id and object_id are required for each object.

dimension_name

string (write-only)

A description for the dimension_id. Values over 20 may have a custom dimension_name set. If your dimension_id is 1-19, the dimension_name field will be ignored and the standardized name will be used. The latest submitted dimension_name will be saved for the specificed dimension_id.

object_name

string (write-only)

A description for the object_id. The latest submitted object_name will be saved for the specificed object_id.

Billogram item bookkeeping information objects

This is a sub-object of billogram item objects. The information in this object is used for electricity collection. It has the following fields.

Name Description Default
nyttighet

enumerated string

Commodity (Nyttighet).
Available values are EL, EH, EN, FV, GA, VA, RH, YY.

blank

Billogram additional information sub-structure

This sub-structure contains additional, optional information that can be included on an invoice for the convenience of the customer.

These fields are purely informational, they do not affect the invoicing logic.

Name Description Default
order_no

string, max 30 characters

Order number reference, for e.g. referencing an order made in another system.

blank
order_date

date string

Date the order for the invoiced items was placed.

blank
our_reference

string, max 35 characters

blank
your_reference

string, max 35 characters

blank
shipping_date

date string

Date the items invoiced were sent to the customer.

blank
delivery_date

date string

Date the items invoiced were delivered to the customer.

blank
reference_number

string, max 30 characters

blank
message

string, max 350 characters

Free-form long message that will be printed on the invoice.

uses business account invoicing default

Billogram Swedish regional data sub-structure

This sub-structure specifies special invoicing options available under Swedish taxation law. These options are only available in some special cases.

Note that the rotavdrag and reversed_vat options are mutually exclusive, it is not possible to create an invoice using both options. If reversed_vat is true then rotavdrag must be 0, and if rotavdrag is non-zero then reversed_vat must be false.

Note also that Autogiro requires to be activated for your Billogram business account. Contact Billogram support if you wish to have more information about it.

Name Description Default
rotavdrag

number

Amount to deduct from the invoiced amount under ROT/RUT deduction rules, given in the invoicing currency. The exact rules for these deductions are outside the scope of this documentation.

0
rotavdrag_personal_number

numeric string

Swedish personal number of the individual eligible for the tax deduction.

required when rotavdrag is non-zero
rotavdrag_description

string

Description of services invoiced for which the deduction is based on.

blank
rotavdrag_description_of_property

string

Description of property for deduction.

blank
rotavdrag_apartment_designation

string

Apartment designation for deduction.

blank
rotavdrag_housing_association_org_no

string

Housing association org. no. for deduction.

blank
reversed_vat

boolean

Whether to use Swedish reversed VAT payment rules for this invoice.

false
autogiro_betalarnummer

string

The ID number that identifies the payer in the Autogiro system. It follows BGC format (numeric, max 16 characters).

blank
autogiro_payment_date

date string

Date on which the due amount is going to be withdrawn from payer's account.

generated, read-only
autogiro_status

string

Current status of the Autogiro payment for the Billogram. Will be null if autogiro is disabled. If enabled, status can be any of the following statuses unattested, scheduled, processing, successful or failed

generated, read-only
autogiro_full_status

string

Extra information in case autogiro_status is failed

generated, read-only
autogiro_total_sum

number

Amount to be withdrawn from payer's account.

generated, read-only
efaktura_recipient_identifier

string, max 20 characters

E-faktura recipient identifier, sometimes referred to as the FMI (fakturamottagaridentitet). Should be in the format YYYYMMDDXXXX.BANK.SE for individuals or individual companies or 00XXXXXXXXXX.BANK.SE for companies with organization number (06XXXXXXXXXX.SBF.SE for companies using Swedbank) where 'BANK' would be replaced by the bank_code.

You may either submit this value or a combination of efaktura_recipient_type, efaktura_recipient_bank_name, efaktura_recipient_bank_id, efaktura_recipient_bank_code, efaktura_recipient_id_number. The remaining values will be calculated automatically.

We recommend users to either only submit the efaktura_recipient_identifier or both efaktura_recipient_id_number + efaktura_recipient_bank_code to avoid errors.

blank
efaktura_recipient_type

enumerated string

E-faktura recipient type, wether the recipient is an individual or a company. One of the following values: individual, company

blank
efaktura_recipient_bank_name

string

E-faktura recipient's fully qualified bank name. Available banks are Danske Bank, SEB, Handelsbanken, Skandiabanken, Swedbank, Nordea, Länsförsäkringar bank, ICA banken, Sparbanken Syd, Forex Bank, Ålandsbanken, Marginalen Bank

blank
efaktura_recipient_bank_id

numeric (4 digits)

E-faktura recipient's bank's internal id, may differ if the recipient is an individual or a company. The numeric bank id is used in some e-faktura formats (for example BGCInvoice).

blank
efaktura_recipient_bank_code

string (2-4 characters)

E-faktura recipient's bank's internal code, may differ if the recipient is an individual or a company. Available values are OEB, SEB, SHB, SKB, FSPA, NB, LFB, ICA, SYD, FRX, AAB, MARG, DBF, SEBF, SHBF, NBF, SBF

blank
efaktura_recipient_id_number

numeric (10-12 digits)

E-faktura recipient's id number or organization number. (Recommended 12 digits for individuals or individual companies, 10 digits for companies)

blank
efaktura_requested_amount

number

The default amount to be paid when an E-faktura is viewed in the recipients internet bank (the amount can always be changed by the recipient though). If left as null (recommended) the invoice's amount to be paid will be the default specified amount.

This value may not be changed after the E-faktura has been sent to the recipient.

blank
electricity_collection

Collection for electricity invoices data sub-structure

Contains special options for using collection for electricity invoices.

see sub-structure section

Collection for electricity invoices data sub-structure

This sub-structure specifies special options used when sending electricity invoices for collection. They can be set either when first creating the billogram or at a later time, before the collection demand is sent. If any of these values are present when the collection demand is sent, they will be included in the demand.

Name Description Default
kommunkod

numeric string (3 digits)

Municipality (Kommun) code.

blank
naringsidkare

boolean

Customer is a business owner (Näringsidkare).

blank
avflyttad

boolean

Customer is moved out (Avflyttad).

blank
avflyttad_datum

date string

Date of move out (Avflyttad, datum).

blank
frankopplad

boolean

Customer is disconnected (Frånkopplad).

blank
frankopplad_datum

date string

Date of disconnect (Frånkopplad, datum).

blank
anladr

string (35 characters)

Facility adress (Anläggningsadress).

blank
natom

string (3 characters)

Grid area (Nätområde).

blank
arsforb

numeric string (10 digits)

Yearly consumption (Årsförbrukning).

blank
anlid

string (20 characters)

Facility ID (Anläggnings-ID).

blank
kravmall

string (2 characters)

Claim template (Kravmall).

blank
plombkod

string (2 characters)

Seal code (Plombkod).

blank
slutfaktura

boolean

Ending invoice (Slutfaktura).

blank
objtyp

enumerated numeric string (1 character)

Type of object (Objektstyp). Valid values are "1" (Lägenhet/Villa utan eluppvärmning), "2" (Villa med eluppvärmning) or "3" (Övrigt).

blank
faktforb

number

Consumption on invoice (Förbrukning på faktura) specified in kWh.

blank
faktfrek

number

Frequency of invoicing (Fakturafrekvens) in months. If you would send invoices every month the value would be 1. For bi-monthly the value would be 2. Quarterly is 3, etc.

blank

Billogram states

A billogram always has a specific state, performing commands on a billogram may change its state. For a simple integration you will probably only have to care about the Paid and Credited states, but for a more complex integration you may need to use a few more of the available states.

State Meaning
Unattested A billogram that has been created, but not yet sent or sold.
Sending A billogram that is being sent right now (will only be visible in callbacks).
Unpaid A sent billogram that hasn't been paid yet.
CollectorEnded An ended billogram with a collection request that has been ended.
Collecting A billogram that is being sent for collection but has not yet been verified by the collection partner.
Collection A billogram that has been sent for collection.
Factoring A billogram that is being sold but has not yet been approved by the factoring partner.
Sold A sold billogram. This is an ended state.
Ended An ended billogram. This state will only happen if the billogram was sent with a zero sum amount.
Paid An ended billogram that has been paid.
Credited An ended billogram that has been credited.
FactoringDenied A billogram that was sent for factoring but the sale request was denied by the factoring partner.
PartlyPaid A billogram that has received a payment.
Overdue A billogram that has past it's due date and not yet received a payment.
Reminder_1 A billogram that has been reminded once.
Reminder_2 A billogram that has been reminded twice.
Reminder_3 A billogram that has been reminded thrice.
Reminder_Many A billogram that has been reminded more than 3 times.
Deleted A deleted billogram. This state will only happen if the billogram has been deleted and it will only be shown in a potential callback.

Billogram flags

A billogram can have some flags that give extended status information for it. Some of the flags are purely informative, while others may indicate that action is required. The flags are set by the Billogram system and can not be modified. In the API, the flags are represented as an array of strings. This array should be treated as a set, the order the flags appear in is not significant.

Flag name Meaning
partly paid Payments have been received on the billogram, but the invoiced amount has not yet been paid in full.
new message A message has been received on the billogram, but has not been read yet. This flag can currently only be cleared by visiting the Billogram web site, not by the API.
new event Deprecated New events have occurred on the billogram, but have not yet been seen. This flag can currenly only be cleared by visiting the Billogram web site, not by the API.
message One or more messages have been sent/received on the billogram.
delivery failed The billogram could not be delivered to the customer for some reason (see the events list for details).
not delivered The billogram has not yet been delivered to the customer, but may yet arrive (primarily if delivered by e-mail and the customer has not yet clicked the link in the mail).
paid on collection Billogram has received a payment on the invoice after it had been sent to the collection agency.
factoring denied The billogram was attempted sold to a the factoring partner, but the factoring partner rejected the sale.
rot-deduction A deduction under Swedish ROT/RUT taxation law has been applied to the invoice.
has been sold The billogram has been sold to a factoring partner.
has been in collection The billogram has been in debt collection state.
overpaid The billogram has been overpaid
autogiro payment order sent An autogiro payment order has been sent to Bankgirot. If the pay via autogiro is also set, the billogram awaits information about wether the payment succeeded or failed.
pay via autogiro The billogram is marked to be paid via autogiro, and has yet to receive information about wether the payment succeeded or failed. Once the success/fail information has been received, this flag will be unset.
overpaid via autogiro The payment via autogiro was on a higher amount than what was remaining on the billogram, and the creditor may need to refund part of the payment to the customer.
efaktura order sent An e-faktura (electronic invoice to a Swedish internet bank) has been sent to Bankgirot and in turn to the recipients internet bank. The invoice will then be available in the internet bank within 12-24 hours on a normal banking day. Triggered by the BillogramSent event.
send efaktura The billogram is marked to be sent via E-faktura (electronic invoice to a Swedish internet bank) or has already been sent as an e-faktura.
efaktura show payment details A billogram that has originally been sent via E-faktura (electronic invoice to a Swedish internet bank), but later on has been delivered via email or letter, will show the payment information to the recipient since it's no longer assumed that the payment will go via E-faktura.
written down There are still remaining principal sum on the billogram that has been written down as a potential loss of receivables. This flag is only available for billogram that has not been fully paid, fully credited or otherwise ended. If there are no remaining principal sum to be paid the flag will be unset.

Billogram events list

When querying for a billogram you will receive an array of 100 of the past events (sorted) and when you receive callbacks about new events you will only receive the single new event. The data parameter will contain different data depending on the event type.

If you need to go back in time more than the latest 100 events, you may query the billogram_event resource.

There are quite many different events, but usually you will end up only needing a few of them. The more basic ones are of course Payment, Credit and BillogramEnded.

Name Description
created_at

timestamp string

Timestamp the event was created at. Given as a date-time string in UTC.

type

string

Notes which type of event this is. Can be any of the following values.

Type
Meaning
BillogramCreated
The billogram has been created.
BillogramSent
The billogram has been sent.
Payment
A payment has been made. Look at the data for the paid amount.
ReminderSent
A reminder has been sent.
Overdue
Invoice has past its due date.
Credit
A credit invoice has been created. Look at the data for the credited amount.
BillogramEnded
The billogram has ended (usually when paid or credited).
Resent
The billogram has been re-sent.
DeliveryAccepted
If you're using the delivery method Email+Letter, Email, SMS+Letter or SMS (in some cases also Efaktura if the customer_email parameter was supplied) and the recipient has clicked the link in the email or SMS.
DeliveryFailed
If you're using the delivery method Email+Letter or Email and the email could not be delivered (usually when the email has bounced due to wrong email address).
DeliverySmsFailed
If you're using the delivery method SMS+Letter or SMS and the invoice via SMS could not be delivered (usually when the SMS has bounced due to invalid phone number).
EmailNotAccepted
If you're using the delivery method Email+Letter and the email has not been read within 48 hours.
SmsNotAccepted
If you're using the delivery method SMS+Letter and the invoice sent via SMS has not been read within 48 hours.
LetterSent
Directly after EmailNotAccepted or SmsNotAccepted a letter may be sent if you're using the delivery method Email+Letter or SMS+Letter.
OverpaymentAdjustment
If too much has been paid on a billogram we will, once an hour, create overpayment adjustments to send back money to the payee.
InterestStarted
Interest fee starts ticking. This event will be created if the interest starts separate from when sending a reminder.
CustomerMessage
The billogram recipient has written/sent a message/comment. Look at the data for actual message.
CreditorMessage
A new message/comment from you/your company. Look at the data for actual message.
DataChange
Values has changed on the billogram.
InvoiceSent
If values has changed a billogram so that a full credit has been issued and a new invoice has been created and sent.
Collection
The billogram has been sent for collection.
CollectionPayment
A payment has been received by the collection partner. Look at the data for the paid amount.
CollectionEnded
The debt collection case has ended (usually when paid or credited).
CollectionCancelled
The debt collection case has been cancelled.
CollectionStatusUpdate
The debt collection case has updated status.
FactoringRequest
The event is created when the billogram is marked for sale. A sale request will be sent to the factoring partner.
BillogramSold
The billogram has been sold to the factoring partner.
FactoringCreditRequest
A factoring request to credit the sold invoice.
FactoringDenied
The factoring request was denied and the billogram will go back to the FactoringDenied state and may be sent instead.
FactoringCreditRequestDenied
The factoring credit request was denied.
Writeoff
An amount from the billogram has been written-off - usually remaining interest and/or reminder fees.
Writedown
The remaining sum of the billogram has been booked as a potential loss of receivables. This is used for bookkeeping purposes.
RevertWritedown
An earlier writedown has been reverted.
NewInvoicePDF
There is a new PDF available for the billogram. This usually occurs after the billogram has been updated with new information or the billogram has been credited.
AutogiroFailed
If an order to pay via autogiro has failed for some reason. The most common reason is that the payer was missing money on their bank account.
EfakturaSent
An e-faktura (electronic invoice to a Swedish internet bank) has been sent to Bankgirot and in turn to the recipients internet bank. The invoice will then be available in the internet bank within 12-24 hours on a normal banking day.
EfakturaFailed
The e-faktura (electronic invoice to a Swedish internet bank) could not be delivered and need to be resent via either email or letter.
SaleAccepted
A sale offer has been accepted by a recipient.
Deleted
The billogram has been deleted. This event will only be available through a callback.
data

See the events data sub-structure for which parameters are included for which events.

Holds information about amounts, reference numbers and/or letter id:s. You may not need all of these, but for starters you may want to look at the amount and letter_id parameters.

Event data sub-structure

Name Description
invoice_no

string

Events: BillogramSent, InvoiceSent, Credit

The invoice's invoice number.

delivery_method

string

Events: BillogramSent, InvoiceSent, Credit, Resent, LetterSent, ReminderSent

The actual delivery method used for the action.

Can be one of the following: Email+Letter, Email, SMS+Letter, SMS, Letter, Efaktura.

original_delivery_method

string

Events: BillogramSent, InvoiceSent, Credit, Resent, LetterSent, ReminderSent

The original delivery method selected for the action by the sender.

Can be one of the following: Email+Letter, Email, SMS+Letter, SMS, Letter, Efaktura.

delivery_redirected

boolean

Events: BillogramSent, InvoiceSent, Credit, Resent, LetterSent, ReminderSent

If the delivery is redirected according to recipient's choice instead of the sender's for the action.

letter_id

string

Events: BillogramSent, Credit, ReminderSent, LetterSent, Resent, InvoiceSent, BillogramSold, NewInvoicePDF

ID string which may be used to get a specific invoice PDF file.

amount

number

Events: Payment, Credit, OverpaymentAdjustment, CollectionPayment, Writeoff, AutogiroFailed, EfakturaSent, EfakturaFailed

The amount sum for the event.

payer_name

string

Events: Payment

If the payment is sent via Billogram client funds accounts this parameter will hold the name of the payee.

payment_flags

array

Events: Payment

Extra values that describe specific characteristics of the payment. Returned as an array of zero or many string values. May hold the values "collector payment", "swish payment" and/or "autogiro payment".

banking_amount

number

Events: Payment

The sum that has been paid to your bank account (if payment is sent via Billogram client funds accounts).

manual

boolean

Events: Payment

Boolean for whether the payment command was made manually by you (true) or if money were received via the Billogram client funds accounts (false).

reminder_fee

number

Events: ReminderSent

The reminder fee added to the billogram with this reminder.

reminder_count

number

Events: ReminderSent

Describes which reminder this is, starting with 1 and increasing.

interest_rate

number

Events: InterestStarted

The interest rate for which interest has started ticking on.

customer_email

string

Events: DeliveryAccepted, EmailNotAccepted, DeliveryFailed

The email address for the recipient.

customer_phone

string

Events: DeliveryAccepted, SmsNotAccepted, DeliverySmsFailed

The phone number for the recipient.

ip

string

Events: DeliveryAccepted

The IP address of the recipient that clicked the link in the email.

type

enumerated string

Events: DeliveryFailed

Failure type.

message

string

Events: DeliveryFailed

Failure message.

message

string

Events: CustomerMessage, CreditorMessage

Message/comment posted on the billogram.

full_status

string

Events: AutogiroFailed

The full status of why the autogiro payment order failed, if available. May be an empty string if the full status is unavailable.

collector_method

enumerated string

Events: Collection

Holds which collection partner the billogram has been sent for collection at.

collector_reference

string

Events: Collection, CollectionEnded, CollectionCancelled, CollectionStatusUpdate

Reference number at the collection partner. May be null or empty and may be updated later with a new event with the same type.

factoring_method

enumerated string

Events: FactoringRequest, BillogramSold, FactoringDenied

Holds which factoring partner the billogram is using for factoring.

factoring_reference

string

Events: FactoringRequest, BillogramSold, FactoringCreditRequest, FactoringDeniedFactoringCreditRequestDenied

Reference number at the factoring partner.

sells_for

number

Events: FactoringRequest

The value for which the billogram may be sold for.

sold_for

number

Events: BillogramSold

The value for which the billogram has been sold for.

bankgiro

string

Events: EfakturaSent

Bankgiro number used for payment.

recipient_identifier

string

Events: EfakturaSent

The identifier for the recipient of an e-faktura, this identifier may in some cases be referred to a the FMI (fakturamottagaridentitet).

error_status

enumerated string

Events: EfakturaFailed

The internal error code received from the banks for a failed e-faktura delivery. Possible values are recipient_not_available, recipient_blocked, invalid_identifier, amount_too_high, invalid_ocr

total_sum

number

Included in most but not all events.

The total sum, including fees, of the billogram.

remaining_sum

number

Included in most but not all events.

The remaining to be paid, including fees, of the billogram.

scanning_central

boolean

Events: BillogramSent, Credit, InvoiceSent, LetterSent, Resent, ReminderSent

If the billogram was sent to a scanning central.

offer_id

string

Events: SaleAccepted

The id of the accepted sale offer.

sale_type

enumerated string

Events: SaleAccepted

The type of the accepted sale offer.

Possible values are update, purchase

accepted_at

timestamp string

Events: SaleAccepted

The timestamp when the offer is accepted.

customer_no

positive integer

Events: SaleAccepted

The unique identification of the customer who accepted the offer.

item_title

string

Events: SaleAccepted

The title (i.e. name) of the item sold in the offer.

item_price

float

Events: SaleAccepted

The price of the item sold in the offer.

item_type

enumerated string

Events: SaleAccepted

The type of the item sold in the offer.

Possible values are physical, digital

Billogram events resource

If you somehow need more than the 100 latest history events (see structure above) for a billogram you may query the /api/v2/billogram_event resource.

You may only GET (list/search) from the resource with the billogram_id parameter equal to the id of the billogram you wish to get events from. filter_type must be set to "field" (string).

The list is automatically sorted by creation-time (ascending) starting with the oldest event as the first object (typically the BillogramCreated event). There is no way to GET for a single event as the events don't have any unique id:s returned.

List billogram events for a billogram

HTTP method: GET
Target path: billogram_event
GET parameters: See the section on search and filtering for details.
Searchable fields:

The following fields can be used for filter queries:

  • billogram_id
Orderable fields:

The following fields can be used for ordering query results:

  • created_at
Response:
  • OK (200) The listing was successful.

    The data of the response contains an array of found billogram events. The meta field in the response contains a total_count field with the total number of billogram that were matched in the database, disregarding page size.

  • MISSING_QUERY_PARAMETER / INVALID_QUERY_PARAMETER (400) Indicate that the query parameters are invalid in some manner. Check that a valid combination of parameters are given, and that you use legal field names.

Billogram callbacks sub-structure

This sub-structure specifies a few parameters to be used for callbacks. To receive callbacks you will at least need to specify the url parameter or set the API callback settings for your Billogram business account (value editable available through the web interface). However, we strongly advice you to also make use of the sign_key parameter for added security.

Name Description Default
url

string

The full URL to where we will do the callback HTTP POST requests.

blank
custom

string

A custom value that will be included as the parameter custom on all callbacks.

blank
sign_key

string

A string that we will use to create a hashed signature which is included in all callbacks. We advice you to use the sign_key value and verify the callback's authenticity on the signature parameter.

If sign_key is left blank the callback's signature parameter will be null.

blank

Callbacks

Whenever something happens with a billogram, a new event is added to the event list and a callback for that event is sent. The callback is sent as a HTTP POST request to the API callback URL specified for your business account's settings (value only editable through web interface) or to the url if specified in the callbacks structure of the billogram.

The server receiving a callback must answer with a 200 OK status or the callback will be marked as failed. Failed callbacks will automatically retry up to a total of five times with increasing time intervals (immediately; 10 seconds; 45 seconds; 4 minutes; 20 minutes). The last (fifth) callback attempt will be tried after a total of 25 minutes.

If the last callback attempt is also failed, a detailed email will be sent to the API callback email address specified in the business account's settings on the web site. Because of retries, callbacks are not guaranteed to be received in the correct order (if any prior callbacks have failed).

The POST body of the request is a JSON encoded structure as follows.

Callback example

Example of a callback body (tidied), sent as a HTTP POST request
{
    "billogram": {
        "id": "2kAEEjE",
        "ocr_number": "9999437500039365",
        "state": PartlyPaid",
        "remaining_sum": 13000,
        "total_sum": 13775,
        "attested_at": "2015-11-15 15:25:05",
        "detailed_sums": {
            "credited_sum": 0,
            "net_sum": 11640.15,
            "gross_sum": 13775.108,
            "invoice_fee_vat": 12,
            "paid_sum": -775,
            "interest_fee": 0,
            "vat_sum": 2134.958,
            "reminder_fee": 0,
            "invoice_fee": 25,
            "rounding": -0.108,
            "regional_sweden": {
                "rotavdrag_sum": 0
            },
            "collector_paid_sum": 0,
            "remaining_sum": 13000
        }
    },
    "event": {
        "type": "Payment",
        "created_at": "2015-12-04 13:28:51",
        "data": {
            "total_sum": 13775,
            "payer_name": null,
            "manual": true,
            "remaining_sum": 13000,
            "amount": 775,
            "banking_amount": null,
            "payment_flags": []
        }
    },
    "callback_id": "522f1ed3efe8f",
    "custom": null,
    "signature": "360c5b6b83ad0ca7fb2eedd04052aec9"
}
Example of a callback HTTP request to /example-callback-url
POST /example-callback-url HTTP/1.1
Host: example.org
User-Agent: Billogram API Callback/2.00
Content-Type: application/json

{"billogram":{"id":"2kAEEjE","ocr_number":"9999437500039365","state":PartlyPaid","remaining_sum":13000,"total_sum":13775,"attested_at":"2013-08-15 15:25:05","detailed_sums":{"credited_sum":0,"net_sum":11640.15,"gross_sum":13775.108,"invoice_fee_vat":12,"paid_sum":-775,"interest_fee":0,"vat_sum":2134.958,"reminder_fee":0,"invoice_fee":25,"rounding":-0.108,"regional_sweden":{"rotavdrag_sum":0},"collector_paid_sum":0,"remaining_sum":13000}},"event":{"type":"Payment","created_at":"2015-12-04 13:28:51","data":{"total_sum":13775,"payer_name":null,"manual":true,"remaining_sum":13000,"amount":775,"banking_amount":null,"payment_flags":[]}},"callback_id":"522f1ed3efe8f","custom":null,"signature":"360c5b6b83ad0ca7fb2eedd04052aec9"

Detailed specification of callback parameters

Name Description
billogram

A JSON object with brief billogram data.

Name
Description
id

billogram id

ocr_number

billogram ocr_number

state

billogram state

remaining_sum

billogram remaining_sum

total_sum

billogram total_sum

attested_at

billogram attested_at

detailed_sums

billogram detailed_sums

event

A JSON object with event data.

Name
Description
created_at

event created_at

type

event type

data

event data

callback_id

unique string

Unique identifier generated for each callback. Used to create the signature hash.

custom

string (or null)

The same custom value that you may have supplied when creating the billogram as the custom parameter in the callbacks structure.

signature

md5 hash (or null)

A md5 hash of the concatenated values of callback_id and the sign_key parameter you may have supplied in the callbacks structure.

If you have supplied a sign_key you should verify that the signature parameter equals <md5-hash of [callback_id][sign_key]>

For security reasons, if you choose not to use the sign_key (or if you're using the global API callback URL settings for your business account that will make you receive callbacks for all Billogram events and not only for billogram created via API) we suggest that you GET the billogram upon receiving a callback and verify the contents of the callback.

Example:
callback_id is "522f1ed3efe8f" and you have set sign_key to "NCC1701-S1gnK3y" the signature value will be "360c5b6b83ad0ca7fb2eedd04052aec9" (calculated as md5("522f1ed3efe8fNCC1701-S1gnK3y").)

sandbox
(only set if on sandbox)

bool

If you are testing your integration on our sandbox API environment this parameter will be set to true. If you are using our production endpoint this parameter will not be sent at all.

Sample billogram structures

Example of the returned JSON-data for one billogram
{
    "id": "gQjEEZL",
    "created_at": "2013-09-05 15:28:51",
    "updated_at": "2013-09-05 15:35:42",
    "attested_at": "2013-09-05 15:28:52",
    "currency": "SEK",
    "reminder_fee": 50.0,
    "interest_rate": 8.5,
    "state": "Unpaid",
    "attachment": "orderdetails.pdf"
    "automatic_reminders": true,
    "automatic_reminders_settings": [
        {
            "delay_days": 5,
            "message": ""
        },
        {
            "delay_days": 7,
            "message": "Invoice overdue. Pay the invoice to avoid collection."
        }
    ],
    "automatic_collection": {
        "delay_days": 5,
        "amount": 70
    }
    "rounding_value": -0.25,
    "ocr_number": "324810046924",
    "events": [
        {
            "type": "BillogramCreated",
            "created_at": "2013-09-05 15:28:51",
            "data": null
        },
        {
            "type": "BillogramSent",
            "created_at": "2013-09-05 15:28:52",
            "data": {
                "invoice_no": 146,
                "letter_id": "jc3NTIyOGEz6d46fc6ff9613f5c3b2ebd6d2aa",
                "delivery_method": "Letter"
                "remaining_sum": 411,
                "total_sum": 411,
            }
        }
    ],
    "due_date": "2013-10-05",
    "due_days": 30,
    "invoice_date": "2013-09-05",
    "callbacks": {
        "url": "http://example.org/billogram-callback",
        "sign_key": "bowties-are-cool!",
        "custom": null
    },
    "interest_fee": 0,
    "invoice_no": 146,
    "customer": {
        "name": "Company AB",
        "vat_no": "SE777777777701",
        "phone": null,
        "customer_no": 12,
        "address": {
            "city": "STOCKHOLM",
            "country": "SE",
            "attention": "",
            "zipcode": "11444",
            "careof": "",
            "street_address": "Gatan 2"
        },
        "email": "",
        "org_no": "777777-7768"
    },
    "info": {
        "reference_number": "",
        "our_reference": "",
        "order_no": "",
        "shipping_date": null,
        "order_date": "2013-09-01",
        "message": "Thank you for using our services. Have a nice weekend.",
        "delivery_date": null,
        "your_reference": "Adam Andreasson"
    },
    "invoice_fee": 29,
    "invoice_fee_vat": 25,
    "items": [
        {
            "title": "Software, administration features",
            "price": 300,
            "vat": 25
            "unit": "hour",
            "count": 1,
            "discount": 0,
            "item_no": "3",
            "description": "",
            "bookkeeping": {
                "income_account": "3001",
                "vat_account": "2610",
                "objects": []
            },
            "regional_sweden": {
                "rotavdrag": false,
                "electricity_collection": {
                    "nyttighet": "RH"
                }
            }
        }
    ],
    "total_sum": 411,
    "remaining_sum": 411,
    "reminder_count": 0,
    "delivery_method": "Letter",
    "url": "https://billogram.com/r/324810046924/ABCDE",
    "flags": [],
    "regional_sweden": {
        "rotavdrag": 0,
        "rotavdrag_personal_number": "",
        "rotavdrag_description": "",
        "rotavdrag_housing_association_org_no": "7777777777",
        "rotavdrag_apartment_designation": "ABC123",
        "rotavdrag_description_of_property": "Snace 1:12",
        "reversed_vat": false,
        "autogiro_betalarnummer": null,
        "autogiro_payment_date": "",
        "autogiro_status": null,
        "autogiro_full_status": null,
        "autogiro_total_sum": null,
        "efaktura_recipient_type": null,
        "efaktura_recipient_identifier": null,
        "efaktura_recipient_bank_name": null,
        "efaktura_recipient_bank_id": null,
        "efaktura_recipient_bank_code": null,
        "efaktura_recipient_id_number": null,
        "efaktura_requested_amount": null,
        "electricity_collection": {
            "kommunkod": null,
            "slutfaktura": null,
            "kravmall": null,
            "frankopplad": false,
            "arsforb": null,
            "plombkod": null,
            "natom": null,
            "avflyttad_datum": "2016-10-01",
            "frankopplad_datum": null,
            "anladr": null,
            "anlid": null,
            "avflyttad": true,
            "naringsidkare": null,
            "objtyp": 2,
            "faktforb": 400,
            "faktfrek": 1
        }
    },
    "detailed_sums": {
        "invoice_fee": 29,
        "invoice_fee_vat": 25,
        "net_sum": 329,
        "vat_sum": 82.25,
        "gross_sum": 411.25,
        "rounding": -0.25,
        "reminder_fee": 0,
        "interest_fee": 0,
        "paid_sum": 0,
        "collector_paid_sum": 0,
        "remaining_sum": 411,
        "regional_sweden": {
            "rotavdrag_sum": 0,
        }
    }
}

Billogram calls

Since billogram objects have a state and it must be possible to perform complex actions on them, they have several more calls than the simple objects such as items and customers.

Create billogram

Create a new billogram object. The new object will be in the Unattested state initially, and from there can be sent or otherwise. Alternatively, a special value can be present in the billogram structure passed, which indicates that the billogram is to be sent to factoring for sale.

HTTP method: POST
Target path: billogram
Data:

The billogram object to be created.

Response:
  • OK (200) The billogram was created successfully.

    The data of the response contains the actual billogram object created in the database, including any auto-generated values. The new billogram will be in the Unattested state.

  • PERMISSION_DENIED (404) This special response (note that this is HTTP 404, not 403) may happen if the business account has been blocked from invoicing. Accounts may be blocked if they, after an inspection, are suspected of abuse.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Fetch single billogram

Fetch the data for a single billogram object, identified by its unique id.

HTTP method: GET
Target path: billogram/id
Example path: billogram/CDAEyKE
Response:
  • OK (200) The billogram was found.

    The data of the response contains full data for the billogram.

  • NOT_FOUND (404) No billogram by the given id was found.

List/search billogram

List or search for billogram objects. Since billogram objects are generally quite large, this call returns compact objects instead that only contain some key information suitable for listing them. The full data for each returned billogram can be fetched one by one using the regular fetch by id call.

HTTP method: GET
Target path: billogram
GET parameters: See the section on search and filtering for details.
Searchable fields:

The following fields can be used for filter queries:

  • id
  • invoice_no (only for attested billogram)
  • invoice_date
  • due_date
  • ocr_number
  • customer:name
  • customer:customer_no
  • customer:org_no
  • state
Special filters:

A single special filter name is available:

search: Perform a full text search across several fields at once

Orderable fields:

The following fields can be used for ordering query results:

  • invoice_no (only for attested billogram)
  • invoice_date
  • due_date
  • customer:name
  • customer:customer_no
  • state
Response:
  • OK (200) The search was successful. This is used even if no billogram objects matched the filter.

    The data of the response contains an array of found billogram objects, in the compact format. The meta field in the response contains a total_count field with the total number of billogram that were matched in the database, disregarding page size.

  • MISSING_QUERY_PARAMETER / INVALID_QUERY_PARAMETER (400) Indicate that the query parameters are invalid in some manner. Check that a valid combination of parameters are given, and that you use legal field names.

Update billogram

Change data on a billogram. If the billogram has been sent, some changes are not possible, and some changes will cause new invoices to be generated and sent.

HTTP method: PUT
Target path: billogram/id
Example path: billogram/CDAEyKE
Data:

Partial billogram object, containing just the fields to update.

Keep in mind that depending on the state of the billogram object, not all fields may be available to update, and some changes may cause a new invoice to be generated and sent.

Response:
  • OK (200) The billogram object was updated.

    The data of the response contains the new state of the billogram object.

  • NOT_FOUND (404) No billogram by the given id was found.

  • INVALID_OBJECT_STATE (400) The billogram is in a state where the attempted changes are not allowed.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Send billogram

Send a billogram, only possible from the Unattested state. To be able to send a billogram via delivery method E-faktura (electronic invoice to a Swedish internet bank) you must first activate the feature by contacting Billogram support and in some cases signing an agreement with your bank and Bankgirot.

HTTP method: POST
Target path: billogram/id/command/send
Example path: billogram/CDAEyKE/command/send
Data:

A JSON object with one field:

Name
Description
method

enumerated string

One of the following values: Email, SMS, Letter, Email+Letter, SMS+Letter, Efaktura

Response:
  • OK (200) The billogram was sent successfully.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Typically indicates that the method is missing or invalid.

  • INVALID_OBJECT_STATE (400) The billogram has already been sent or sold. Use the resend call to send a new copy of an already sent billogram.

Sell billogram

Sell a billogram, only possible from the Unattested state and only if your business account is approved for factoring services. Remember that a sold billogram or a billogram that is in the state "Factoring" can not be changed.

HTTP method: POST
Target path: billogram/id/command/sell
Example path: billogram/CDAEyKE/command/sell
Response:
  • OK (200) The billogram has successfully been marked for factoring.

    The data of the response contains the actual billogram object from the database.

  • INVALID_OBJECT_STATE (400) The billogram has already been sent or sold, selling is no longer available. This may also indicate that one or more properties of the billogram prevents it from being sold, such as not having a postal address for the customer or the total amount being too low.

  • PERMISSION_DENIED (403) The business account does not have a factoring agreement, and is not allowed to sell invoices.

Re-send billogram

Send an already-sent billogram again, optionally using a different delivery method.

HTTP method: POST
Target path: billogram/id/command/resend
Example path: billogram/CDAEyKE/command/resend
Data:

A JSON object with one field:

Name
Description
method

enumerated string

One of the following values: Email, Letter

Response:
  • OK (200) The billogram was successfully resent.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Typically indicates that the method is missing or invalid.

  • INVALID_OBJECT_STATE (400) The billogram may not be re-sent from its current state.

Send reminder for billogram

Send a reminder for a billogram, only possible after the due date has passed.

HTTP method: POST
Target path: billogram/id/command/remind
Example path: billogram/CDAEyKE/command/remind
Data:

A JSON object with one field:

Name
Description
method

enumerated string

One of the following values: Email, Letter

Response:
  • OK (200) The reminder has been successfully sent.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Typically indicates that the method is missing or invalid.

  • INVALID_OBJECT_STATE (400) The billogram's current state does not allow reminders to be sent.

Send billogram to collector

Send a billogram past due date to collection. If the billogram has not been paid you may wish to send it for collection. Requires the business account to have a collection agreement.

HTTP method: POST
Target path: billogram/id/command/collect
Example path: billogram/CDAEyKE/command/collect
Data: No data expected, send an empty JSON object
Response:
  • OK (200) The invoice has been sent for collection successfully.

    The data of the response contains the actual billogram object from database.

  • INVALID_OBJECT_STATE (400) The billogram is not in a state where it may be sent to collection; this may also indicate that it is not yet past the due date.

  • PERMISSION_DENIED (403) The business account does not have a collector agreement, and is not allowed to send invoices to collection.

Register payment on billogram

Manually register a payment on a billogram. This is intended to be used if a payment is received outside the services offered by Billogram, e.g. if the customer pays by cash rather than via the Billogram client funds accounts.

HTTP method: POST
Target path: billogram/id/command/payment
Example path: billogram/CDAEyKE/command/payment
Data:

A JSON object with one field:

Name
Description
amount

number

The size of the payment to register, given in the invoicing currency. Must be greater than zero.

Response:
  • OK (200) The payment was created successfully.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Typically indicates that the amount is missing or invalid.

  • INVALID_OBJECT_STATE (400) The billogram is not in a state where it can accept payments.

Credit billogram

Credit part, remaining or the full billogram.

HTTP method: POST
Target path: billogram/id/command/credit
Example path: billogram/CDAEyKE/command/credit
Data:

A JSON object with two fields:

Name
Description
mode

enumerated string

Required. One of the following values: full, remaining, amount

amount

number

Only required when mode is amount, should not be present in the other modes. The amount to credit the billogram by, given in the invoicing currency.

Please note that the absence of the amount field when mode is amount will result in a full credit.

method

string

Can be one of the following: Email, SMS, Letter or Efaktura.

If left out, the same method as the original invoice will be used.

Response:
  • OK (200) The credit was created successfully.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Indicates that the mode is missing or invalid, or that the amount is missing or invalid in the amount mode.

  • INVALID_OBJECT_STATE (400) The billogram is not in a state where it can be credited.

Write-off remaining amount (only fees) from billogram

Usuable if you for example have a billogram fully paid and want to write-off the remaining fees but don't want to create a credit invoice just for the fees.

HTTP method: POST
Target path: billogram/id/command/writeoff
Example path: billogram/CDAEyKE/command/writeoff
Response:
  • OK (200) The write-off was successful.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Usually if there is no remaining fees to write-off.

  • INVALID_OBJECT_STATE (400) The billogram is not in a state where it can be written-off.

Writedown remaining principal sum

If you expect that the billogram won't be paid you can book the remaining principal sum as a potential loss of receivables. The billogram can still be paid and interacted with, but a bookkeeping post will be created.

HTTP method: POST
Target path: billogram/id/command/writedown
Example path: billogram/CDAEyKE/command/writedown
Response:
  • OK (200) The writedown was successful.

    The data of the response contains the actual billogram object from the database.

  • INVALID_OBJECT_STATE (400) The billogram is not in a state where it can be written down.

Revert an earlier writedown

If a billogram was accidentally written down you may revert the bookkeeping post by reverting the writedown.

HTTP method: POST
Target path: billogram/id/command/revert-writedown
Example path: billogram/CDAEyKE/command/revert-writedown
Response:
  • OK (200) The reverted writedown was successful.

    The data of the response contains the actual billogram object from the database.

  • INVALID_OBJECT_STATE (400) The billogram is not in a written down state where it can be reverted.

Add message to billogram

Add a message to the conversation on the billogram. The message will be delivered via email.

HTTP method: POST
Target path: billogram/id/command/message
Example path: billogram/CDAEyKE/command/message
Data:

A JSON object with one field:

Name
Description
message

string

Free-form string, the message to add to the billogram's conversation.

Response:
  • OK (200) The message/comment was created successfully.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Typically indicates that the message parameter is missing or empty.

Add PDF attachment to billogram

Add a PDF attachment to the billogram. The PDF attachment will be printed and sent along with the invoice if delivered by letter and will be available to download as the recipient received the billogram via email or link.

The attachment can later be fetched from the target path billogram/id/attachment.pdf.

To remove an attachment update the attachment field of the billogram to null.

HTTP method: POST
Target path: billogram/id/command/attach
Example path: billogram/CDAEyKE/command/attach
Data:

A JSON object with two fields:

Name
Description
filename

string

Required. The filename of the attached file, for example example.pdf.

content

base64 encoded string

The content (base64 encoded) of the PDF file that you wish to attach.

Response:
  • OK (200) The attachment was attached successfully.

    The data of the response contains the actual billogram object from the database.

  • INVALID_PARAMETER (400) Typically indicates that any of the parameters is missing or empty.

Get invoice PDF file

Receive the base64 encoded content for a PDF file on the billogram. You can query for a specific invoice_no, letter_id or the default, the latest active invoice. PDF files are not generated instantly so in case the file has yet been created you will receive a HTTP 404 NOT_AVAILABLE_YET error.

HTTP method: GET
Target path: billogram/id.pdf
Example path
(latest pdf):
billogram/CDAEyKE.pdf
Example path
(by invoice_no):
billogram/CDAEyKE.pdf?invoice_no=1234
Example path
(by letter_id):
billogram/CDAEyKE.pdf?letter_id=xA3N7366afaa65a7827aad4e
Example path
(attachment):
billogram/CDAEyKE/attachment.pdf
Query parameters:

You can use one of the following query parameters to fetch specific PDF files. If none is given, the latest PDF for the billogram is sent.

Name
Description
invoice_no

string

An invoice number that exists on the billogram. If you use this parameter you will receive the latest PDF for the specified invoice number (invoice_no).

letter_id

string

An letter ID that exists on the billogram. If you use this parameter you will receive the PDF for the specified letter_id. Certain event types (in the event list) and callbacks generated specify letter_ids.

Response:
  • OK (200) The PDF content is returned.

    The data of the response contains two parameters, the file_type (application/pdf) and the base64 encoded content. If you're requesting the PDF attachment you will also receive a third parameter, filename.

  • NOT_AVAILABLE_YET (404) The PDF file has not yet been generated but are going to be. Please try again later.

  • NOT_FOUND (404) There are no such billogram, invoice_no on that billogram or letter_id on that billogram.

Customers

About customers

Customers are registered recipients of invoices, invoices can only be sent to an existing customer.

The company_type field of a customer determines the customer's legal status; whether they are a private person or a business, and whether they reside in the Billogram business account's country or not. This information controls the availability of some of the invoicing features, for instance the ROT/RUT deduction options are only available when a Swedish business is invoicing a Swedish private customer, not when they invoice a foreign customer or another business.

Due to internal limitations, the invoicing and shipping addresses are currently given in slightly different forms and are both explicit. The API may later have more flexible customer address options available.

Customer structure

The data structure for a customer object has the following fields.

Name Description Default
customer_no

positive integer

Unique identification for the customer. Only positive integers are allowed as customer numbers, and all customers must have a unique number. If the customer_no is modified for an existing customer, any further accesses to the customer object must be done using the new value. If no value is given when creating a customer, an automatic sequential value is generated. If you want automatic customer-numbering, please do not set this parameter at all, not even to a null value.

automatic sequential numbers
name

string

Name used to identify the customer. In the case of a private person, the person's name. In case of a business, the business' name. Used for printing postal addresses on letters.

required
notes

string

Free-form text for internal notes. The contents of this field is never visible to the customer.

blank
org_no

alphanumeric string

The personal identification number (for individuals) or organizational registration number (for businesses) of the customer. Only applicable for Swedish national customers. (Must be given as a string as this is not a number in the mathematical sense.)

blank
vat_no

string

European Union VAT number of the customer. The Billogram service does not directly use this number. Should be in the format of a two-letter country code followed by the country-specific format.

Example value: SE556677889901

blank
contact

Customer contact person information object

Specifies the primary contact person for the customer

see defaults for sub-object
address

Customer primary address information object

Primary billing address for the customer

see defaults for sub-object
delivery_address

Customer delivery address information object

Delivery address for the customer (location where the sold goods is delivered or the services are performed)

see defaults for sub-object
created_at

timestamp string (read-only)

Timestamp the customer object was first created at. May not be specified when creating or updating items, generated automatically when the customer is first created. Returned when fetching customer objects. String contains a date-time in UTC.

generated
updated_at

timestamp string (read-only)

Timestamp the customer object was last modified at. May not be specified when creating or updating items, generated automatically every time the customer is modified. Returned when fetching customer objects. String contains a date-time in UTC.

generated
company_type

enumerated string

The legal status of the customer. Must be one of the following values

required
Type
Description
business
A company or an one-man business located in the same country as the Billogram business account
individual
A private individual located in same country as the Billogram business account, not operating a business
foreign business
A business located outside the country of the Billogram business account
foreign individual
A private individual located outside country of the Billogram business account

Customer contact person information object

This is a sub-object of customer objects. This object holds e-mail and phone contact information for the customer. The contact person name and e-mail address must be completed to enable sending invoices by e-mail for the customer. Has the following fields.

Name Description Default
name

string

Name of the (primary) contact person for the customer.

blank
email

string

Email address the customer can be reached at. Used to send invoices via Email.

blank
phone

string

Phone number the customer can be reached at. Used to send invoices via SMS.

blank

Customer primary address information object

This sub-object of a customer describes the billing address for the customer. This address must be completed for to enable sending invoices by post for the customer.

The country field specifies the country for the customer as a whole too, and is for this reason required.

Has the following fields.

Name Description Default
careof

string

Care-of (C/O) line to include in the address. Also see the use_careof_as_attention field.

blank
use_careof_as_attention

boolean

If this flag is set to true then the careof field will instead be printed as an "Att:" line in the address. (It is currently not possible to have both an C/O and an Att: line in an address.)

false
street_address

string

Street address part of the address (i.e. typically street name, house number, floor, apartment/room). Line breaks are not recommended.

blank
zipcode

string

Postal code for the address

blank, required if street_address is specified
city

string

City name for the address

blank, required if street_address is specified
country

enumerated string

Country for the address and the customer. Must be a two-letter ISO 3166-1 alpha-2 format code. Converted to uppercase in the Billogram system.

Example value: SE

SE

Customer delivery address information object

This sub-object of a customer specifies the delivery address, i.e. the location where the goods is delivered or the services performed. The delivery address is not used directly by the Billogram service, but is printed on invoices for the customer's reference. Has the following fields.

Name Description Default
name

string

Name to print on the address

blank, required if street_address is specified
street_address

string

Street address part of the address (i.e. typically street name, house number, floor, apartment/room). Line breaks may not work.

blank
careof

string

Care-of (c/o) line to include in the address. Note that unlike the billing address, there is currently no option to specify an "Attention" line for delivery addresses.

blank
zipcode

string

Postal code for the address

blank, required if street_address is specified
city

string

City name for the address

blank, required if street_address is specified
country

enumerated string

Country for the address. Must be a two-letter ISO 3166-1 alpha-2 format code if specified. Converted to lowercase in the Billogram system.

blank, required if street_address is specified

Example customer structures

This is an example of customer, as it might be sent to the API for creation:

Example of customer structure for creation or update
{
    "customer_no": 10032,
    "name": "Peter Jonsson",
    "company_type": "individual",
    "org_no": "",
    "contact": {
        "name": "Peter Jonsson",
        "email": "peter.jonsson@example.com"
    },
    "address": {
        "street_address": "Lavendelväg 27",
        "zipcode": "12345",
        "city": "Stadby",
        "country": "SE"
    }
}

Customer calls

Create customer

This call creates a new customer object and returns the created object.

HTTP method: POST
Target path: customer
Data: The customer object to be created
Response:
  • OK (200) The customer was created successfully.

    The data of the response contains the actual customer object created in the database, including any auto-generated customer_no value.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Fetch single customer

This fetches all data about a single customer. The command is sent to the customer object.

HTTP method: GET
Target path: customer/customer_no
Example path: customer/234
Response:
  • OK (200) The customer was found.

    The data of the response contains the requested customer object's current state.

  • NOT_FOUND (404) No customer exists with the given customer_no.

List/search customers

This fetches many customer objects, filtered based on optional criteria.

HTTP method: GET
Target path: customer
GET parameters: See the section on search and filtering for details.
Searchable fields:

The following fields can be used for filter queries:

  • customer_no
  • name
  • notes
  • org_no
  • company_type
  • contact:name
  • contact:email
  • contact:phone
  • address:street_address
  • address:careof
  • address:zipcode
  • address:city
  • address:country
  • delivery_address:name
  • delivery_address:street_address
  • delivery_address:careof
  • delivery_address:zipcode
  • delivery_address:city
  • delivery_address:country
Special filters:

A single special filter name is available:

search: Perform a full text search across several fields at once

Orderable fields:

The following fields can be used for ordering query results:

  • customer_no
  • name
  • org_no
  • contact:email
  • contact:phone
  • address:zipcode
  • address:city
  • delivery_address:name
  • delivery_address:zipcode
  • delivery_address:city
  • created_at
  • updated_at
Response:
  • OK (200) The search was successful. This is used even if no customers matched the filter.

    The data of the response contains an array of found customer objects. The meta field in the response contains a total_count field with the total number of customers that were matched in the database, disregarding page size.

  • MISSING_QUERY_PARAMETER / INVALID_QUERY_PARAMETER (400) Indicate that the query parameters are invalid in some manner. Check that a valid combination of parameters are given, and that you use legal field names.

Update customer

This command changes an existing customer. The command is sent to the customer object to modify. This does not affect the customer data on any billograms or invoices sent to the customer, if the information needs to be updated on any existing billograms those must be updated individually afterwards.

HTTP method: PUT
Target path: customer/customer_no
Example path: customer/234
Data:

Partial customer object, containing just the fields to update.

If the regional_sweden, contact, address or delivery_address fields are left out or set to null (instead of containing the structures) those sub-objects are left unchanged.

Other fields that have default values will be set to their default value if they are specified as null in the passed structure.

Response:
  • OK (200) The customer was updated.

    The data of the response contains the new state of the customer object.

  • NOT_FOUND (404) No customer exists with the given customer_no.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Items

About items

An item is a product or service that can be invoiced for. On an invoice, they appear as a row with a text, a unit price, a (possibly fractional) number of units invoiced for, and the calculated total cost.

Item structure

The data structure for an item object has the following fields.

Name Description Default
item_no

string

Identification for the item. Always present on existing items. If no item_no is given when creating an item object, a new number is generated and assigned automatically. The item number is a string and may contain other characters than just numerals. Must be unique. If the item_no is changed on an item object, the new value must be used to refer to it from that point. If you want automatic item-numbering, please do not set this parameter at all, not even to a null value. The max length for item_no is 30 characters IF the value is non-numeric, otherwise (if the value is numeric) the max value is 999999999.

Example values: "207", "42-B081"

automatic sequential numbers
title

string, max 40 characters

The short text given for the item. Should generally be a human-readable description of the product or service sold. Must not be empty.

required
description

string, max 200 characters

A longer description for the item. Appears below the main item row on an invoice. Can be used to e.g detail the work performed in the case of services.

blank
price

number

The cost per unit of the item. May be positive, zero or negative.

required
vat

number

VAT rate applied to this item, in percent. No more than two decimals allowed, for example 10.25 is valid, but 10.255 is not.

All values between 0 and 100 are valid, but if you wish to use Swedish VAT rates, you should use: 0, 6, 12 or 25

required
unit

enumerated string

Unit of measure for the item. May have one of the following values:

required
Unit name
Typically used to measure
unit
units of piece goods
hour
hours of work/service
day
days of service/rent
month
months of service
quarter
yearly quarter
kg
kilogram product sold
gram
gram product sold
kwh
kwh sold
ton
ton product sold
meter
meters product sold
mm
millimeters product sold
km
kilometer product sold, or distance travelled
m2
square meters product sold
m3
cubic meters product sold
litre
liters product sold
minute
minutes product sold
second
seconds product sold
bookkeeping

Item bookkeeping information object

Sub-object describing bookkeeping information for this item. If left out, an empty object is created automatically. See below for structure.

default values of item bookeeping information object
created_at

timestamp string (read-only)

Timestamp the item object was first created at. May not be specified when creating or updating items, generated automatically when the item is first created. Returned when fetching item objects. String contains a date-time in UTC.

generated
updated_at

timestamp string (read-only)

Timestamp the item object was last modified at. May not be specified when creating or updating items, generated automatically every time the item is modified. Returned when fetching item objects. String contains a date-time in UTC.

generated

Item bookkeeping information objects

This is a sub-object of item objects. The information in this object is used for generating bookkeeping files from paid invoices. It has the following fields.

Name Description Default
income_account

string

Account number for payments received for this item. If left out or blank, the item uses the default account set up.

blank (will use account default)
vat_account

string

Account number for VAT payments received for this item. If left out or blank, the item uses the default account set up.

blank (will use account default)

Example item structures

This is an example of an item describing a service performed, as it might be sent to the API for creation:

Example of item structure for creation or update
{
    "item_no": "CLN",
    "title": "Apartment cleaning",
    "description": "Vacuum cleaning floor, dusting shelves and taking out trash",
    "price": 130,
    "vat": 25,
    "unit": "hour",
    "bookkeeping": {
        "income_account": "302",
        "vat_account": "303"
    },
}

This is an example of a product sold as it might be returned from the API in a search:

Example of the full returned item structure
{
    "item_no": "3004202",
    "title": "Wooden pole (⌀ 60cm)",
    "description": "Untreated pine wood, originated in northern Sweden",
    "price": 43.6,
    "vat": 25,
    "unit": "meter",
    "bookkeeping": {
        "income_account": null,
        "vat_account": null
    },
    "created_at": "2013-02-06 14:57:03",
    "updated_at": "2013-08-05 12:16:57"
}

Item calls

Create item

This call creates a new item object and returns the created object.

HTTP method: POST
Target path: item
Data: The item object to be created
Response:
  • OK (200) The item was created successfully.

    The data of the response contains the actual item object created in the database, including any auto-generated item_no value.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Fetch single item

This fetches all data about a single item. The command is sent to the item object.

HTTP method: GET
Target path: item/item_no
Example path: item/207
item/42-B081
Response:
  • OK (200) The item was found.

    The data of the response contains the requested item object's current state.

  • NOT_FOUND (404) No item exists with the given item_no.

List/search items

This fetches many item objects, filtered based on optional criteria.

HTTP method: GET
Target path: item
GET parameters: See the section on search and filtering for details.
Searchable fields:

The following fields can be used for filter queries:

  • item_no
  • title
  • description
  • price
  • bookkeeping:income_account
  • bookkeeping:vat_account
Special filters:

A single special filter name is available:

search: Perform a full text search across several fields at once

Orderable fields:

The following fields can be used for ordering query results:

  • item_no
  • title
  • price
  • created_at
  • updated_at
Response:
  • OK (200) The search was successful. This is used even if no items matched the filter.

    The data of the response contains an array of found item objects. The meta field in the response contains a total_count field with the total number of items that were matched in the database, disregarding page size.

  • MISSING_QUERY_PARAMETER / INVALID_QUERY_PARAMETER (400) Indicate that the query parameters are invalid in some manner. Check that a valid combination of parameters are given, and that you use legal field names.

Update item

This command changes an existing item. The command is sent to the item object to modify. This does not affect the item data on any billograms or invoices that reference the item, if the information needs to be updated on any existing billograms those must be updated individually afterwards.

HTTP method: PUT
Target path: item/item_no
Example path: item/207
item/42-B081
Data:

Partial item object, containing just the fields to update.

If the bookkeeping or regional_sweden fields are left out or set to null (instead of containing the structures) those sub-objects are left unchanged.

Other fields that have default values will be set to their default value if they are specified as null in the passed structure.

Response:
  • OK (200) The item was updated.

    The data of the response contains the new state of the item object.

  • NOT_FOUND (404) No item exists with the given item_no.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Delete item

This removes an item from the database. The command is sent to the item object to delete. Any billograms or invoices that referenced the item object will have their references cut, but the item data in the billograms and invoices will be left as-is.

HTTP method: DELETE
Target path: item/item_no
Example path: item/207
item/42-B081
Data: Do not pass any data to DELETE
Response:
  • OK (200) The item was deleted.

  • NOT_FOUND (404) No item exists with the given item_no.

Settings

About settings

The settings object lets a client application modify global values for a Billogram business account. These settings are also available on the web interface, most applications may never need to use the settings object.

Structure

The base settings structure is as follows:

Name Description
name

string

Name of the business managing the business account (a.k.a. company name). Displayed on all invoices sent from the account. Changes need to be verified via email that will be sent out to the main user (most likely the same as registration_email) or the user requesting the change, if the change request is being done via a "partner-API integration".

org_no

string (read-only if already set)

Organization number of the business managing the business account. Currently only accepting Swedish creditors and Swedish organization numbers. Displayed on all invoices sent from the account. Can only be set if already blank. Can only be set once. If a creditor wishes to change their org_no, they will need to contact the Billogram support.

contact

Business contact data sub-structure

Contact information from Billogram to the business. Not used on invoices.

address

Business address data sub-structure

Postal address to reach your company. This is the address where your company may receive invoices sent from Billogram (if they are sent by letter).

invoice_address

Invoice address data sub-structure

An optional sub-object of the creditor. Used when the creditor wish to receive invoices from Billogram (by using the service) to an address other than the default creditor address (email or physical).

visiting_address

Visiting address data sub-structure

An optional sub-object of the creditor. Used when the creditor has multiple addresses and want to specify a dedicated visiting address. The visiting address will show up on the web invoice and be visible to recipients instead of the default creditor address, but will not affect the default address otherwise.

payment

Payment data sub-structure

Bank account information allowing Billogram to forward received payments to the business.

tax

Tax data sub-structure

Information required for taxation purposes.

bookkeeping

Bookkeeping configuration sub-structure

Configuration data used in generation of the bookeeping files available from Billogram.

invoices

Invoice defaults sub-structure

Default values for invoice creation, these can be overridden on individual invoices when required.

Business contact data sub-structure

Name Description
name

string

Name of the person reached by these contact data. Should be the person primarily responsible for managing the Billogram account at the business.

email

string

E-mail address printed on the invoices.

phone

string

Phone number the contact person can be reached on. This will also be printed on the invoices.

www

string

Website address to be presented for receivers of digital invoices.

Business address data sub-structure

Name Description
street_address

string

Street address part of the address (i.e. typically street name, house number, floor, apartment/room). Line breaks may not work.

careof

string

Care-of (C/O) line to include in the address. Note that these is no (direct) way of specifying an "attention" line in the address.

zipcode

string

Postal code for the address

city

string

City name for the address

country

enumerated string

Country for the address. Must be a two-letter ISO 3166-1 alpha-2 format code if specified. Converted to uppercase in the Billogram system.

Required.

Invoice address data sub-structure

Name Description
street_address

string

Street address part of the address (i.e. typically street name, house number, floor, apartment/room). Line breaks may not work.

careof

string

Care of, or c/o, is an addendum to the address, specifying whom the mail should be forwarded to.

zipcode

string

Postal code for the address

city

string

City name for the address

country

enumerated string

Country for the address and the creditor. Must be a two-letter ISO 3166-1 alpha-2 format code. Converted to uppercase in the Billogram system.

Example value: SE

email

email address

Email address where the creditor will receive invoices from Billogram.

Visiting address data sub-structure

Name Description
street_address

string

Street address part of the address (i.e. typically street name, house number, floor, apartment/room). Line breaks may not work.

careof

string

Care of, or c/o, is an addendum to the address, specifying whom the mail should be forwarded to.

zipcode

string

Postal code for the address

city

string

City name for the address

country

enumerated string

Country for the address and the creditor. Must be a two-letter ISO 3166-1 alpha-2 format code. Converted to uppercase in the Billogram system.

Example value: SE

Payment data sub-structure

Holds the information required for Billogram to transfer received funds from paid invoices to the invoicing business. Only one of the three methods (bankgiro, plusgiro, domestic_bank_account) need to be specified. The international_bank_account must be specified to allow for international invoicing. Changes need to be verified via email that will be sent out to the main user (most likely the same as registration_email) or the user requesting the change, if the change request is being done via a "partner-API integration".

Name Description
bankgiro

numeric string (hyphens allowed)

Swedish bankgiro account number for transferring funds received from customers to the invoicing business.

plusgiro

numeric string (hyphens allowed)

Swedish plusgiro account number for transferring funds received from customers to the invoicing business.

domestic_bank_account

A domestic Swedish bank account number for transferring funds received from customers to the invoicing business.

Name
Description
account_no

numeric string (hyphens allowed)

Account number part

clearing_no

numeric string (hyphens allowed)

Clearing number part

Required if the account number part is specified.

international_bank_account

A international bank account number (IBAN) for transferring funds received from customers to the invoicing business.

Name
Description
bank

string

Name of the bank

Required if the IBAN is specified.

iban

string

International bank account number

bic

string

Bank identification code (BIC) for the bank the account is located at

Required if the IBAN is specified, and SWIFT is not.

swift

string

SWIFT code for the bank the account is located at

Required if the IBAN is specified, and BIC is not.

Tax data sub-structure

Name Description
is_vat_registered

boolean

Whether the business is registered for VAT in Sweden.

has_fskatt

boolean

Whether the business pays Swedish F-skatt tax.

vat_no

string

European VAT registration number for the business.

Bookkeeping configuration sub-structure

Name Description
income_account_for_vat_25

numeric string

Default bookeeping account number for income from items with 25% VAT applied.

income_account_for_vat_12

numeric string

Default bookeeping account number for income from items with 12% VAT applied.

income_account_for_vat_6

numeric string

Default bookeeping account number for income from items with 6% VAT applied.

income_account_for_vat_0

numeric string

Default bookkeeping account number for income from VAT-free items.

reversed_vat_account

numeric string

Bookkeeping account number for income from invoices with reverse VAT rules applied.

vat_account_for_vat_25

numeric string

Default bookkeeping account number for 25% VAT.

vat_account_for_vat_12

numeric string

Default bookkeeping account number for 12% VAT.

vat_account_for_vat_6

numeric string

Default bookkeeping account number for 6% VAT.

sie_serie

string

Series for SIE4 import files.

sie_continuous_numbering

enumerated string

Continuous supporting of document numbering for SIE4. Could be either "monthly" - verification number starts from 1 every month, or "yearly" - continuous numbering throughout the year.

financial_year_start

string

Starting year and month (e.g. "2017-08") of fiscal year. The year will always be stored as current year.

financial_year_months

number

Number of months in fiscal year.

account_receivable_account

numeric string

Bookkeeping account for account receivables.

client_funds_account

numeric string

Standard bookkeeping account for client funds.

banking_account

numeric string

Standard bookkeeping account for the business' bank.

interest_fee_account

numeric string

Bookeeping account number for interest fees added to late paid invoices.

reminder_fee_account

numeric string

Bookkeeping account number for reminder fees added to late paid invoices.

rounding_account

numeric string

Bookkeeping account number for rounding adjustments of invoice amounts.

factoring_receivable_account

numeric string

Bookkeeping account number for receivables for sold invoices.

non_allocated_account

numeric string

Bookkeeping account number for non allocated funds on payment triggers. Only used for specific use cases.

income_payout_account

numeric string

Bookkeeping account number for non income generated for payment trigger payouts. Only used for specific use cases.

written_down_receivables_account

numeric string

Bookkeeping account number for written down account receivables. Will be used when writing down a billogram or on payments/credits of a written down billogram.

expected_loss_account

numeric string

Bookkeeping account number for expected loss on a written down billogram. Will be used when writing down a billogram or on payments/credits of a written down billogram.

regional_sweden

Sub-structure for bookkeeping account numbers unique to Swedish taxation laws.

Name
Description
rotavdrag_account

numeric string

Bookeeping account number for receivables due to ROT/RUT deductions.

Invoice defaults sub-structure

Name Description
default_message

string

The message printed on late payment reminders by default.

default_interest_rate

number

Default interest rate added to late invoices. The rate must be given in per-cent (i.e. specify 8.5 and not 0.085 for an 8.5 % rate) and is a yearly rate. The interest is calculated daily.

default_reminder_fee

number

Default reminder fee added to invoices when a late payment reminder is sent. Value is in SEK.

default_invoice_fee

number

Default invoice fee added to all new invoices, unless a different value is given for a specific invoice. Value is in SEK.

automatic_reminders

Automatic reminder data array

Default set of late payment reminders to use for new invoices, where different reminders are not specified.

automatic_writeoff

Automatic writeoff sub-structure

Automatic writeoff settings for your account. If set up, automatic write-offs of remaining fees will occur when a payment is received and the principal sum for a billogram has been fully paid.

automatic_collection

Automatic collection sub-structure (or null)

Automatic collection settings for your account. If set up, unpaid invoices will be automatically sent to collection after a set amount of days since due date / last reminder. Requires a collection agreement.

Automatic reminder data array

This array specifies the sequence of automatic late payment reminders. It can be used as a part of the invoice defaults sub-structure and of the billogram structure.

When automatic reminder data are sent, the entire array must always be sent, it is not possible to do partial updates. In other words, the entire array is always replaced with the given new array, if one is present.

The array lists the reminders to be sent, in order. Each reminder specifies a number of days after the previous reminder it is to be sent, and optionally a message to include.

The entries in the array are structures with the following fields.

Name Description Default
delay_days

number

Must be an integer greater than zero. Number of days since previous reminder (or the invoice due date for first reminder) this reminder is to go out.

required
message

string

Free-form string, a message to be included with this reminder.

blank

Automatic writeoff sub-structure

Name Description Default
settings

enumerated string (or null)

We support different types of automatic write-offs and you may set the settings parameter to choose how automatic write-off will be applied on your invoices.

null
Type
Description
all_fees
All unpaid fees (reminder fee and interest fee) will be written off.
interest_only
Unpaid interest fee will be written off when principal sum and reminder fee has been paid.
fee_amount
Unpaid fees (reminder fee and interest fee) up to the amount of the amount parameter will be written off.
null
If the value is set to null no automatic writeoff will occur.
amount

number (or null)

The maximum amount of fees that will be written-off if settings is set to fee_amount.

May only be set to a numeric value but will return a null unless the settings> parameter is set to fee_amount.

null

Automatic collection sub-structure

This sub-structure defines the condition under which unpaid invoices will be automatically sent to collection. It can be used as a part of the invoice defaults sub-structure and of the billogram structure. If set to null no automatic collection will occur. It requires the business account to have a collection agreement.

When used as part of the invoice defaults sub-structure, this option will only affect new invoices created via the web interface.

Name Description Default
delay_days

number

Must be an integer greater than one. Number of days since due date / last reminder invoices are to be automatically sent to collection.

required
amount

number

Must be a number greater than 50. The minimum unpaid amount an invoice should have in order to be automatically sent to collection.

required

Samples

The following is a settings structure as returned from the service:

Complete settings structure sample
{
    "address": {
        "careof": "",
        "city": "Exempelköping",
        "country": "SE",
        "street_address": "Långgatan 10",
        "zipcode": "23456"
    },
    "bookkeeping": {
        "account_receivable_account": "1500",
        "banking_account": "1920",
        "client_funds_account": "1940",
        "expected_loss_account": "6352",
        "factoring_receivable_account": "1512",
        "income_account_for_vat_0": "3004",
        "income_account_for_vat_12": "3002",
        "income_account_for_vat_25": "3001",
        "income_account_for_vat_6": "3003",
        "sie_continuous_numbering": "monthly",
        "sie_serie": "AA",
        "financial_year_start": "2017-05",
        "financial_year_months": 3,
        "income_payout_account": "3005",
        "interest_fee_account": "8313",
        "non_allocated_account": "2800",
        "regional_sweden": {
            "rotavdrag_account": "1513"
        },
        "reminder_fee_account": "8313",
        "reversed_vat_account": "3231",
        "rounding_account": "3740",
        "vat_account_for_vat_12": "2620",
        "vat_account_for_vat_25": "2610",
        "vat_account_for_vat_6": "2630",
        "written_down_receivables_account": "1519"
    },
    "contact": {
        "name": "Sonja",
        "phone": "",
        "email": "billing@example.com"
    },
    "invoices": {
        "automatic_reminders": [],
        "automatic_writeoff": {
            "settings": null,
            "amount": null
        },
        "automatic_collection": null,
        "default_interest_rate": 8.5,
        "default_invoice_fee": 0.0,
        "default_message": "",
        "default_reminder_fee": 50
    },
    "name": "Testbolaget AB",
    "org_no": "848484-2326",
    "payment": {
        "bankgiro": "1234-5678",
        "domestic_bank_account": {
            "account_no": "",
            "clearing_no": ""
        },
        "international_bank_account": {
            "bank": "",
            "bic": "",
            "iban": "",
            "swift": ""
        },
        "plusgiro": ""
    },
    "tax": {
        "has_fskatt": true,
        "is_vat_registered": true,
        "vat_no": ""
    }
}

Settings calls

Fetch settings

This fetches the current settings for the Billogram business account.

HTTP method: GET
Target path: settings
Response:
  • OK (200) The settings were retrieved.

    The data of the response contains the settings object.

Update settings

This changes the current settings for the Billogram business account.

HTTP method: PUT
Target path: settings
Data:

Partial settings object, containing just the fields to update.

Sub-structures that do not need modification can be left out of the object, or be set to null.

Response:
  • OK (200) The settings were updated.

    The data of the response contains the new settings object.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER / INVALID_PARAMETER_COMBINATION / READ_ONLY_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Logotype

About logotypes

You may upload or download the logotype for your company (your Billogram business account) with the logotype resource. The logotype should be either JPG or PNG and will be rescaled to 797x135 px with white boxing if exceeding the limitations. The logotype should never contain any transparency or semi-transparency. The logotype will be converted to PNG and will be returned in PNG-format when requested from the API.

Structure

The base logotype structure is as follows:

Name Description
content

base64 encoded string

The content of the logotype in PNG-format encoded with base64 encoding.

file_type

string

The MIME-type of the logotype image. May be for example image/png or image/jpeg. When returned will always be image/png.

Logotype API calls

Get logotype

This fetches the current logotype for the Billogram business account.

HTTP method: GET
Target path: logotype
Response:
  • OK (200) The logotype was retrieved.

    The data of the response contains the logotype object.

Upload logotype

This changes the current logotype for the Billogram business account.

HTTP method: POST
Target path: logotype
Data:

Should contain the full structure for the logotype object, content and file_type.

Response:
  • OK (200) The logotype wasw updated.

    The data of the response contains the new logotype object.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Cover photo

About cover photos

You may upload or download the cover photo for your company (your Billogram business account) with the cover photo resource. The cover photo should be JPG and will be rescaled with white boxing if exceeding the limitations. The cover photo should never contain any transparency or semi-transparency. The cover photo will be converted to JPG and will be returned in JPG-format when requested from the API.

Structure

The base cover photo structure is as follows:

Name Description
content

base64 encoded string

The content of the cover photo in JPG-format encoded with base64 encoding.

file_type

string

The MIME-type of the cover photo image.

Cover photo API calls

Get cover photo

This fetches the current cover photo for the Billogram business account.

HTTP method: GET
Target path: coverphoto
Response:
  • OK (200) The cover photo was retrieved.

    The data of the response contains the cover photo object.

Upload cover photo

This changes the current cover photo for the Billogram business account.

HTTP method: POST
Target path: coverphoto
Data:

Should contain the full structure for the cover photo object, content and file_type.

Response:
  • OK (200) The cover photo was updated.

    The data of the response contains the new cover photo object.

  • INVALID_PARAMETER / UNKNOWN_PARAMETER (400) These standard errors may happen if the sent structure contains invalid data.

Delete cover photo

This removes the current cover photo for the Billogram business account.

HTTP method: DELETE
Target path: coverphoto
Response:
  • OK (200) The cover photo was deleted.

    The data of the response contains the cover photo object.

Reports

About reports

Your report files are available for fetching via the API. If you want to know more about what they are and when they become available, please refer to the Q&A page.

For the reports resource, you should use the filename attribute as id. And please note that this is a read-only resource, you cannot modify any reports.

Structure

The base report structure is as follows:

Name Description
filename

string (read-only)

The filename of the report.

type

string (read-only)

Type of report. sie4, sie4 report or debtors ledger journal.

file_type

string (read-only)

The MIME-type of the report file. May be for example application/octet-stream or application/pdf.

info

string (read-only)

Daterange (e.g. 2014-10-28 - 2014-10-31) for report types sie4, sie4 report and debtors ledger journal.

created_at

timestamp string (read-only)

Timestamp of when the report object was first created at. Given as a date-time string in UTC.

content

timestamp string (read-only)

The actual contents of the report, Base64 encoded. ONLY available when fetching a single report, NOT when listing multiple.

Reports API calls

Get reports

This fetches a single report by filename.

HTTP method: GET
Target path: report/filename
Response:
  • OK (200) The report was retrieved.

    The data of the response contains the report object.

List reports

This fetches many report objects.

HTTP method: GET
Target path: report
GET parameters: See the section on search and filtering for details.
Searchable fields:

The following fields can be used for filter queries:

  • filename
Orderable fields:

The following fields can be used for ordering query results:

  • filename
  • created_at
Response:
  • OK (200) The search was successful. This is used even if no reports matched the filter.

    The data of the response contains an array of found report objects. The meta field in the response contains a total_count field with the total number of items that were matched in the database, disregarding page size.

  • MISSING_QUERY_PARAMETER / INVALID_QUERY_PARAMETER (400) Indicate that the query parameters are invalid in some manner. Check that a valid combination of parameters are given, and that you use legal field names.

Sandbox & testing

Testing your integration

It's natural that you want to test your integration on our sandbox environment before your start sending API invoices for real. Therefore we have a testing environment set up at https://sandbox.billogram.com/ from where no real invoices will be sent and no real transactions will be processed. We recommend that you use it for testing your integration

To register a sandbox/testing account, head over to https://sandbox.billogram.com/register. Enter your testing company details when registered and then go to Settings » API users (on the bottom of the settings page) and create an API user for your test company.

The API_BASE for testing should be https://sandbox.billogram.com/api/v2 instead of https://billogram.com/api/v2. Please also note that any callbacks from the sandbox environment will include the sandbox parameter.

If you are using our libraries you must invoke the constructor methods with the sandbox API_BASE to work against the sandbox.

Using our libraries with the sandbox API_BASE in Python
from billogram_api import BillogramAPI, BillogramExceptions

api = BillogramAPI(api_user, api_authkey, api_base='https://sandbox.billogram.com/api/v2')
Using our libraries with the sandbox API_BASE in PHP
use Billogram\Api as BillogramAPI;

$apiIdentifier = 'Sandbox integration - Testing AB'
$api = new BillogramAPI(
    $apiUser,
    $apiAuthkey,
    $apiIdentifier,
    'https://sandbox.billogram.com/api/v2'
);

Libraries

Python Library

Available on GitHub and as part of our download package.

The Billogram library for Python depends on the Requests package, but nothing else. The library is designed to work on both Python 2.7 and Python 3.

What follows is a very short introduction to the library. Complete documentation for it is available in the docstrings embedded in the code.

Connection object

The BillogramAPI class represents a pseudo-connection to the API. It is responsible for managing the credentials used and performing the low-level requests to the service.

Six properties are provided to access the basic services: customers, items, billogram, logotype, reports and settings. The first three represent the respective classes of objects on the service and provide methods to query and create objects. The settings object gives direct access to the business account settings. The logotype object gives direct access to the logotype for the business account. Lastly, the reports object gives the possibility to download bookkeeping reports (SIE4- or PDF-files).

Additionally, methods to perform HTTP requests to the service are given by the get, post, put and delete members.

Error handling

A number of exception classes are defined, they are used for error reporting. The ServiceMalfunctioningError and RequestFormError indicate problems outside the control of the client application, the latter is intended to indicate bugs in the Billogram API Python library itself.

Additionally, the library performs some limited validation using assertions. The purpose of these assertions is to catch bugs in the client application, the client application should never let the library receive values that would trigger them. Do not depend on them for validation of user input; your program should still run correctly also when Python is running with assertions disabled.

PHP Library

Available on GitHub and as part of our download package.

The Billogram library for PHP is following the PSR-standards and requires at least PHP 5.3.

The PHP library is written to follow the same scheme, connection objects and error handling as the Python library. Read more about it a few lines above.

Code examples

A few, short examples will be given here. The point of these examples are not to show every feature available or explore every nook and cranny, but rather to give a basic understanding of how the API is intended to be interacted with, and establish some good practices.

All of these examples are also available in the download package with the library code. The form of the examples may be a bit different between what is presented on this page and in the download package, but the core content will be the same.

The examples all use the supplied libraries.

Example 0: Connecting to the API

This simply shows how you would create a connection object to the API. It is worth noting that the connection object does not represent an active network connection that stays open, but rather manages the authentication credentials.

Connect to the Billogram API
from billogram_api import BillogramAPI, BillogramExceptions

api = BillogramAPI(api_user, api_authkey)

The example shows loading the library and creating the connection object. The constructor for the connection object requires two parameters, the API user id and its matching authentication key (password). User/key pairs can be obtained from the Settings page when logged in to the Billogram account via the web interface.

The connection object constructor also has two additional, optional parameters. These allow you to respectively change the HTTP user agent header sent, and change the API base-URL used.

Example 1: Create, send, credit

This example will create a minimal billogram object, send it, and after it has been confirmed sent credit it in full.

Create, send, then credit a billogram
def create_send_credit_example(api):
    data = {
        'customer': {
            'customer_no': 1
        },
        'items': [
            {
                'item_no': '1',
                'count': 1
            }
        ],
        'currency': 'SEK',
        'due_date': (date.today() + timedelta(days=35)).isoformat()
    }

    bg = api.billogram.create_and_send(data, 'Email')

    bg.credit_full()

The code assumes a connection to the API already exists, see example 0 for creating one.

First a structure definint the minimum required data for a billogram is defined. This contains a customer specified by their number, a single item specified by its number and the count invoiced for, the currency to be used for the invoice, and the due date. Keep in mind that the dates must always be given in ISO format (YYYY-MM-DD), other forms are not accepted. More data could be given here if needed.

The structure is then passed to the create-and-send method of the billogram class, asked to be sent via the "Email" delivery method.

Of course, at this point several things could go wrong: Maybe there is no customer with number 1, maybe there is no item with number 1, or maybe there is no e-mail address set for the customer. In any of those cases, the billogram would fail to be created and sent. If you wanted to be sure, you could look up the customer and item first to check they exist, and check that the customer has an e-mail address set.

Last, assuming the billogram did get created and an invoice sent, we can call the credit-full method on the billogram object. This simply creates a credit invoice for the full billogram, effectively cancelling it. (But it was still sent first, so if there was a real customer at the other end they would receive the invoice followed by the credit note.)

Here it's worth noting that while creating the billogram returns a new object, crediting it does not. Instead, crediting operates on the object and updates the view of the billogram's state to match it after crediting.

Example 2: Search and update

This example shows how to make a simple search query and update some values on an object.

Find and update certain items
def find_update_example(api):
    qry = api.items.query()

    qry.filter_search('title', 'gadget')

    for item in qry.iter_all():
        item.update({
            'price': item['price']*1.1
        })

The code assumes a connection to the API already exists, see example 0 for creating one.

First a query object for the items class is created. This query object keeps track of the parameters of a single search, and provides an interface to fetch the results of the search.

This query object has a filter condition added, specifically a search type filter for the title field. The search type filter indicates that the search term (here, "gadget") can match any substring of the searched field. There are also prefix and field filters, which match respectively the beginning of the field, or exact-only matches of the field.

The code libraries provide convenience wrappers to perform direct iteration over the results of a query, since the base API (for performance) only supports fetching entire pages at a time. This iteration is used to process all the matched items in a single loop.

Inside the loop, the update method is used to perform a partial update of each matched item. Just the price field is updated here, based on its old value. After the update has succeeded, the item object has also been refreshed to match the new state of the remote object.

Example 3: Get all PDFs for a billogram

In this example the query functions for finding billogram objects by state is used, the first result is picked out, and afterwards all the related PDF files are downloaded.

Get all PDFs for a billogram
def get_pdfs_example(api):
    query = api.billogram.query()
    query.filter_state_any('Paid', 'Credited')

    query.page_size = 1
    bgs = query.get_page(1)
    if not bgs:
        print("No billogram found")
        return

    bg = bgs[0]
    bg.refresh()

    for ev in bg['events']:
        if ev['data'] and 'letter_id' in ev['data']:
            try:
                pdf = bg.get_invoice_pdf(letter_id=ev['data']['letter_id'])
                # 'pdf' now contains the raw file contents
            except BillogramExceptions.ObjectNotAvailableYetError:
                # pdf not created yet
                pass
            except BillogramExceptions.ObjectNotFoundError:
                # pdf was not found
                pass

Like the previous examples, this one assumes a connection to the API already exists.

First a query object for the billogram class is created. A state-filter is added; the state filter works in a "logical or" fashion, meaning it matches billogram objects in any of the given states. This query will find billogram in either of the Paid or Credited states.

The page size is set to one, and the first result page fetched, effectively getting just the first result. If nothing was returned, the code aborts.

Since the billogram class returns compact objects from query results, the letter_ids required to get PDFs are in the events array, and that array is not in the compact representation, the found billogram is refreshed. This makes sure the complete object is available.

To actually find the PDFs, the events array is looped over. All events that have an associated letter_id has a PDF that can be downloaded. The get_invoice_pdf function is used to get these, it returns the raw file content which can then be saved to a file or otherwise processed. The possible errors from fetching a PDF are also shown.

Example 4: Fetch or create customer, then send invoice

This example tries to fetch a customer by number, creates the customer if it does not exist, then sends an invoice. It also updates the customer with some invoice data after the billogram object has been created but before it is sent.

Fetch or create customer, then send invoice
def fetchorcreate_send_example(api):
    customer_no = 12345
    try:
        customer = api.customers.get(customer_no)

    except BillogramExceptions.ObjectNotFoundError:
        customer_data = {
            "customer_no": customer_no,
            "name": "Terkel Testsson",
            "contact": {
                "name": "Terkel Testsson",
                "email": "terkel@example.com",
            },
            "address": {
                "street_address": "Exempelgatan 123",
                "city": "Stockholm",
                "zipcode": "123 45",
                "country": "SE",
            },
            "company_type": "individual",
        }
        customer = api.customers.create(customer_data)

    billogram_data = {
        "customer": {
            "customer_no": customer['customer_no'],
        },
        "items": [
            {
                "title": "Customer assistance",
                "description": "Phone conversation and physical warehouse search",
                "price": 300,
                "unit": "hour",
                "vat": 25,
                "count": 0.5,
            },
            {
                "item_no": "20",
                "description": "Adding 0.14 extra for your convenience",
                "count": 3.14,
            },
        ],
        "currency": "SEK",
        "invoice_fee": 50,
        "due_date": (date.today() + timedelta(days=30)).isoformat(),
        "automatic_reminders": False,
    }
    billogram = api.billogram.create(billogram_data)

    customer.update({
        "notes": "Last conversation: invoice {}".format(billogram['id'])
    })

    billogram.send('Email+Letter')

This example is somewhat more complex. Like the previous ones, it assumes a connection to the API already exists.

First it attempts to fetch a customer by their customer_no. This is protected by a try-statement that catches NOT_FOUND errors. If the customer is not found by their number, the example assumes they need to be created, and proceeds to do that. Notice how the customer data structure used also specifies the customer number to use for the creation, this prevents the Billogram system from choosing an automatic customer number.

After a customer object has been obtained, a billogram object is created. This billogram object references the customer by number, and includes two items. The first item is a single-use one that does not exist in the main items database. It contains a full definition of its data, but will not get an item_no listed on the invoice since none is specified. The second item references one that already exists in the database, but it has a custom description added.

The billogram object also specifies a special invoice fee for this case, and requests that no automatic reminders are created for the invoice.

After declaring these data, the billogram object is created, but is not yet sent. This allows the example to update the customer object with some information from the billogram before sending it. It also lets the billogram remain in the system, as unsent, if sending it fails for some reason. In that case it could then be manually inspected and sent later.