Getting Started

Introduction

Welcome to the Billogram API documentation. The Billogram API is built on RESTful principles, providing a straightforward interface for managing invoices, customers, and other billing-related operations. This documentation will guide you through the API endpoints, webhooks, authentication, and best practices for integration with Billogram. For detailed endpoint documentation, see the API Reference.

What is a Billogram?

A "billogram" (lowercase) refers not to the company or the product, but to the central entity within the Billogram system.

A billogram is a stateful container that represents the full lifecycle of a billing relationship between a company and their customer. At its core, it holds three things:

A collection of invoices — or, while still in draft (not yet attested), a representation of an invoice to be. Because invoices are immutable, any change to the billing (such as a credit) produces a new invoice within the same billogram rather than modifying an existing one.
An activity log — a complete history of everything that has occurred on the entity: invoices sent, payments received, reminders issued, messages from the recipient, and other lifecycle events.
State for payments and access — credentials and identifiers (such as payment references) that enable payment channels, route payments through providers, and control how the billogram's contents are presented to the recipient across different surfaces (web, mobile app, email, SMS, etc.).

Unlike an invoice, which is a static snapshot, a billogram's state changes over time as payments are made, new invoices are generated, or the debt is otherwise settled. In fact, a snapshot of a billogram's state at any given point is what produces an invoice — and the collection of all such snapshots makes up its invoice history.

In short: a billogram is the entity that ties together what is owed, by whom, to whom, how it can be paid, and everything that has happened along the way.

Core Concepts

To effectively use the API, it is helpful to understand the central concepts of the Billogram data model:

Billogram: The core entity described above. By default, a new billogram created via the API is not yet attested (approved). You can use the on_success parameter during creation to automatically attest and send the invoice in a single step.
Invoice: Immutable documents produced by billogram objects and sent to customers. Because they are immutable, invoice-related changes to a billogram object generate new invoices (such as credit invoices) rather than modifying existing ones. They cannot be created stand-alone and always belong to a single billogram.
Customer: Registered recipients of invoices. Invoices can only be sent to an existing customer. A customer's legal status (e.g., private person or business, and domestic or foreign) is determined by their company_type field. This classification controls how specific data is handled and validated by the API, for example, dictating whether the org_no field is processed as a personal identification number or a corporate registration number.
Item: Products, services, and other reasons to invoice customers. On an invoice, they appear as a row with text, a unit price, a number of units, and the calculated total cost. They can be saved as stand-alone objects for reuse or included as "single-use" items directly within a billogram.
Stand-alone Credit Invoice: Credit invoices created as isolated billograms, distinct from "default credits" which are automatically allocated within an existing billogram. Stand-alone Credit Invoices always have a negative sum and can be allocated flexibly across multiple billograms for the same customer.
Payment Source: Deliberate abstractions for various concrete payment schemes like Autogiro, AvtaleGiro and SEPA Direct Debit. They authorize the withdrawal of funds from a customer's underlying account to pay towards a debt.
Offers: Promotional elements attached to billograms for branding or upselling. They operate as either a banner (linking to an external URL) or a sale (opening an overlay that the recipient can accept to add items to their purchase).
Billing Tab: A scheduling feature that allows you to add items to a customer's ongoing "tab" over time. On a predefined scheduled date, billogram automatically empties the tab and generates a single invoice containing all accumulated items.
Webhooks: Real-time HTTP POST notifications about events occurring in your Billogram account. Because actions in the Billogram system trigger asynchronous events, utilizing webhooks (and verifying them via signed secrets) is critical for keeping your application in sync.

Quickstart

This guide assumes you have registered a Sandbox account and generated your API credentials.

Prerequisites

All requests to the API must be authenticated using HTTP Basic Auth, passing your API User ID as the username and your API Key as the password.

Environment	Base URL
Sandbox	`https://sandbox.billogram.com/api/v2`
Production	`https://billogram.com/api/v2`

Code Example (Python)

The following script connects to the Sandbox API, creates a new customer, and issues an invoice (billogram) directly to their email.

import requests

# Configuration
API_USER = "YOUR_API_USER_ID" 
API_PASSWORD = "YOUR_API_KEY"
BASE_URL = "https://sandbox.billogram.com/api/v2"

# 1. Create a Customer
customer_body = {
    "name": "ACME Corp",
    "contact": {
        "email": "acme@example.org"
    },
    "company_type": "business"
}

# The 'requests' library handles HTTP Basic Auth natively via the 'auth' parameter
response = requests.post(
    f"{BASE_URL}/customer", 
    auth=(API_USER, API_PASSWORD), 
    json=customer_body
)

if response.status_code == 200:
    customer = response.json()["data"]
    print(f"Created customer: {customer['customer_no']}")
else:
    print(f"Error creating customer: {response.text}")
    exit()

# 2. Create and Send a billogram
billogram_body = {
    "customer": {
        "customer_no": customer["customer_no"]
    },
    "items": [{
        "title": "Consulting Services",
        "count": 10,
        "vat": 25,
        "price": 1500,
        "unit": "hour"
    }],
    "info": {
        "message": "Thank you for your business!"
    },
    # The on_success block dictates what happens after creation
    "on_success": {
        "method": "Email",
        "command": "send"
    }
}

response = requests.post(
    f"{BASE_URL}/billogram", 
    auth=(API_USER, API_PASSWORD), 
    json=billogram_body
)

if response.status_code == 200:
    billogram = response.json()["data"]
    print(f"Billogram created and sent with ID: {billogram['id']}")
else:
    print(f"Error creating billogram: {response.text}")

Authentication