Getting Started

Billogram is a payment lifecycle platform for recurring revenue businesses. One API covers the full chain: onboarding, charging, communication, and recovery. This guide walks you through the data model, authentication, and a working code example. About 10 minutes, top to bottom, and you should be able to describe how the integration fits your stack. For more about the platform, see billogram.com.

Introduction

The Billogram API is built on RESTful principles, providing a straightforward interface for managing invoices, customers, and other billing-related operations. This page covers the mental model, the auth model, and a working code example. For per-endpoint detail, see the API Reference.

What is a Billogram?

A "billogram" (lowercase) is the central entity in the system. It is not a synonym for invoice.

A billogram is a stateful container representing the full lifecycle of a billing relationship between a company and its customer. It holds three things:

A collection of invoices — or, while still in draft, a representation of an invoice to be. Invoices are immutable; any change (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 what has occurred: 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 is presented to the recipient across web, mobile, email, and SMS.

An invoice is a snapshot. A billogram is the timeline — its state changes over time as payments are made, new invoices are generated, or the debt is otherwise settled. The collection of all such snapshots makes up its invoice history.

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

Core Concepts

Billogram: The core entity described above. By default, a new billogram created via the API is not yet attested (approved). Use the on_success parameter during creation to attest and send the invoice atomically.
Invoice: Immutable documents produced by billograms and sent to customers. Invoice-related changes generate new invoices (such as credit invoices) rather than modifying existing ones. Invoices cannot be created stand-alone — they always belong to a single billogram.
Customer: Registered recipients of invoices. A customer's legal status (private/business, domestic/foreign) is set by company_type, which controls how identifiers like org_no are validated.
Item: Products, services, or other reasons to invoice. Items can be saved for reuse or included as single-use items directly within a billogram.
Stand-alone Credit Invoice: A credit created as an isolated billogram, with a negative sum, that can be allocated flexibly across multiple billograms for the same customer.
Payment Source: Abstractions over concrete payment schemes (Autogiro, AvtaleGiro, SEPA Direct Debit). They authorize withdrawals from the customer's account toward a debt.
Offers: Promotional elements attached to billograms — either a banner (linking out) or a sale (an overlay the recipient can accept to add items).
Billing Tab: Add items to a customer's "tab" over time. On a scheduled date, the tab is emptied into a single invoice.
Webhooks: Real-time HTTP POST notifications about events. Because Billogram operations are asynchronous, webhooks (verified with signed secrets) are how you keep your system in sync.

Quickstart

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

Prerequisites

All requests use HTTP Basic Auth, with 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 script below connects to the Sandbox, creates a customer, and sends them an invoice in one go.

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"
}

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 atomically
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!"},
    # on_success creates and sends in a single, atomic operation
    "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}")

The on_success block does the work. It tells the API to create and send in one atomic call. We recommend this over the two-step approach (create, then call /command/send separately) because it avoids billograms getting stuck in Unattested state if the second call fails to land.

What comes after the quickstart

The quickstart shows the happy path. Three things turn it into a production integration. Each has its own guide:

Webhooks. Lifecycle events (sent, paid, overdue, recalled, ended) arrive as signed HTTP POSTs (HMAC SHA-256). Sort by event.created_at, deduplicate on callback_id, and return 200 OK to acknowledge — webhooks are not guaranteed in order. See Webhooks.

Errors. Structured responses with a machine-readable status (e.g., INVALID_PARAMETER), a human-readable message, and a field_path pointing at the exact parameter that failed. Drive application logic from status; log all three. Retry 5xx errors with exponential backoff and jitter. See Requests & Responses.

Workflows. Before go-live, plan for crediting, respite, dunning, and payment-recall handling — not only create-and-send. The Workflows guide covers commands, constraints, and the webhooks each flow emits.

The shape of an integration

In one sentence: your system creates customers and billograms, you receive lifecycle webhooks (sent, paid, overdue, recalled, ended), you correlate them with your own records using the custom field, and Billogram handles dunning and recall logic.

The work that typically becomes someone's full-time job — webhook reliability, error decoding, status reconstruction, manual reconciliation — is in the API itself, not in your team.

Where to go next

If the integration shape has formed in your head, the docs did their job.

API Reference — every endpoint, every field
Authentication — credential management, API user setup
Webhooks — signature verification, retry behavior, event types
Requests & Responses — error format, pagination, filtering
Workflows — atomic vs two-step, crediting, recalls, respite, dunning
Walk through the integration with an engineer — 15 minutes, no slides, no sales

If it hasn't, that's a docs problem on our end — let us know.

Authentication