dubbl

Official Python SDK for the Dubbl double-entry bookkeeping API

The Dubbl Python SDK provides a convenient, fully-typed interface to the Dubbl API — an open-source, double-entry bookkeeping platform with 70+ resource endpoints. Both synchronous and asynchronous clients are included.

Installation

pip install dubbl

Quick Start

import dubbl

client = dubbl.Dubbl(api_key="dk_live_...")

# Create a contact
contact = client.contacts.create(
    name="Acme Corp",
    email="billing@acme.com",
    type="customer",
)

# Create an invoice
invoice = client.invoices.create(
    contact_id=contact["id"],
    issue_date="2025-01-15",
    lines=[
        {
            "description": "Consulting services",
            "quantity": 10,
            "unitPrice": 15000,  # $150.00 in cents
        }
    ],
)

# List all accounts
accounts = client.accounts.list()

Async Usage

import asyncio
import dubbl

async def main():
    async with dubbl.AsyncDubbl(api_key="dk_live_...") as client:
        invoices = await client.invoices.list(status="sent")
        print(invoices)

asyncio.run(main())

Configuration

client = dubbl.Dubbl(
    api_key="dk_live_...",          # or set DUBBL_API_KEY env var
    organization_id="org_...",      # or set DUBBL_ORGANIZATION_ID env var
    base_url="https://dubbl.dev",       # or set DUBBL_BASE_URL env var
    timeout=30.0,                   # request timeout in seconds (default: 60)
    max_retries=3,                  # retry attempts for transient errors (default: 2)
)

Environment Variables

Resources

The SDK provides access to all 73 Dubbl API resources:

Core Bookkeeping

Sales & Purchasing

Purchasing

Contacts & Payments

Banking

Expenses & Inventory

Inventory & Warehousing

Tax & Compliance

Reports

# Trial balance
trial_balance = client.reports.trial_balance(from_date="2025-01-01", to_date="2025-12-31")

# Profit and loss
pnl = client.reports.profit_and_loss(from_date="2025-01-01", to_date="2025-03-31")

# Aged receivables
aged = client.reports.aged_receivables()

# Custom report
report = client.reports.run(
    data_source="invoices",
    filters=[{"field": "status", "operator": "eq", "value": "overdue"}],
    group_by=["contactId"],
    columns=["contactName", "total", "amountDue"],
)

Payroll & HR

CRM

Documents & Communication

Organization & Team

Billing & Payments

Advanced Features

Data Management

Error Handling

The SDK raises specific exceptions for different error types:

import dubbl
from dubbl import AuthenticationError, NotFoundError, ValidationError, DubblError

client = dubbl.Dubbl(api_key="dk_live_...")

try:
    invoice = client.invoices.retrieve("non-existent-id")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Invoice not found")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except DubblError as e:
    print(f"Something went wrong: {e}")

Exception Hierarchy

DubblError
├── APIError
│   ├── ValidationError        (400)
│   ├── AuthenticationError    (401)
│   ├── PermissionDeniedError  (403)
│   ├── NotFoundError          (404)
│   ├── ConflictError          (409)
│   ├── RateLimitError         (429)
│   └── InternalServerError    (500)
├── APIConnectionError
└── APITimeoutError

Common Patterns

Pagination

# Paginated listing
page1 = client.invoices.list(page=1, limit=50)
for invoice in page1["items"]:
    print(invoice["invoiceNumber"], invoice["total"])

# Next page
page2 = client.invoices.list(page=2, limit=50)

Invoice Workflow

# Create -> Send -> Record Payment
invoice = client.invoices.create(
    contact_id="...",
    issue_date="2025-01-15",
    lines=[{"description": "Services", "quantity": 1, "unitPrice": 50000}],
)

client.invoices.send(invoice["id"])

client.payments.create(
    contact_id=invoice["contactId"],
    type="received",
    date="2025-02-01",
    amount=50000,
    allocations=[
        {"documentType": "invoice", "documentId": invoice["id"], "amount": 50000}
    ],
)

Journal Entry Workflow

# Create -> Post
entry = client.entries.create(
    date="2025-01-15",
    description="Office supplies purchase",
    lines=[
        {"accountId": "expense-account-id", "debitAmount": 5000, "creditAmount": 0},
        {"accountId": "cash-account-id", "debitAmount": 0, "creditAmount": 5000},
    ],
)

client.entries.post(entry["id"])

Download Invoice PDF

pdf_bytes = client.invoices.pdf("invoice-id")
with open("invoice.pdf", "wb") as f:
    f.write(pdf_bytes)

Requirements

• Python 3.10+
• httpx (automatically installed)

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License — see the LICENSE file for details.