Guides

Workflows

This guide describes common workflows in the Billogram API. The workflows combine API requests, commands, and webhook events into practical sequences.

Workflow 1: The Standard Invoicing Flow

There are two ways to create and send a billogram: an atomic (single-request) approach and a two-step approach.

Option A: Atomic (Recommended)

Create and send in a single request. This is the most efficient approach and avoids the billogram getting stuck in an Unattested state.

  1. Create + Send: POST /billogram with an on_success object.
    • Payload Snippet: {"on_success": {"command": "send", "method": "Email"}}.
    • Events: BillogramCreated followed by BillogramSent.

Option B: Two-Step

Create the billogram first, then send it as a separate step. This is useful when you need to review or modify the billogram before sending.

  1. Create: POST /billogram without an on_success object. The billogram is created in the Unattested state.
    • Event: BillogramCreated.
  2. Send: POST /billogram/{id}/command/send to attest and send the billogram.
    • Event: BillogramSent.

After Sending

Regardless of which option you chose, the remaining flow is the same:

  1. Payment: The customer pays via provided methods.
    • Event: Payment (the remaining_sum decreases).
  2. Completion: The billogram is fully settled.
    • Event: BillogramEnded.

Workflow 2: Crediting an Invoice

Invoices are immutable. Corrections require a credit invoice generated within the same billogram via POST /billogram/{id}/command/credit.

Mode Payload Best For
Full {"mode": "full"} Full cancellations
Items {"mode": "items", "items": [...]} Per-item credit; count must be negative

Workflow 3: Stand-alone Credits and Allocation

What is a Stand-alone Credit?

Unlike credits in workflow 2 created within an existing billogram to offset a specific debit invoice, stand-alone credits are created as isolated objects. They are typically used in B2B scenarios where a credit needs to be applied flexibly across multiple different invoices over time.

Key Characteristics:

  • They always have a negative sum.
  • They cannot be converted into debit invoices.
  • They must be enabled by Billogram support before use.
  • They support the DoNotNotify delivery method if you prefer not to send a credit to the customer.

Workflow: Creating and Allocating Credit

  1. Create the Credit: POST /billogram with negative item prices.
  2. Identify Target: Find the debit billogram ID that should receive the credit.
  3. Allocate: POST /billogram/{debit_id}/command/credit-allocate.
    • Payload: {"amount": 500.00, "source_id": "credit_billogram_id"}.
    • Validation: The amount must not exceed the remaining credit or the target's remaining debt.
  4. Multi-allocation: If the credit has a remaining balance, repeat step 3 for the next debit billogram.

Workflow 4: Respite & Rescheduling

Use this to grant additional time for payment by setting a respite date, which postpones both dunning and any scheduled payments.

  1. Webhook: It could be triggered from BillogramEvent with event.type = CustomerMessage requesting for additional time to pay.
  2. Extend: POST /billogram/{id}/command/respite.
    • Constraint: The new date must be later than the current due_date.
    • Scheduled Payment: The scheduled payments are automatically moved to the new date.
  3. Remove: POST /billogram/{id}/command/remove-respite to cancel a previously granted respite.

Workflow 5: Overdue Management

  1. Reactive: Monitor event.type = Overdue and for example initiate manual reminders.
  2. Manual Reminder: POST /billogram/{id}/command/remind.
    • Constraint: You cannot send more than one reminder on the same day.
  3. Automatic: Configure automatic_reminders in your account settings to let billogram handle delivery schedules. You can also set automatic dunning settings per billogram during creation.

Workflow 6: Handling SEPA R-Transactions

Use this flow to handle scenarios where a settled payment is later recalled by the payer or their bank.

  1. Initial Settlement: Billogram is paid and BillogramEnded is triggered.
  2. Payment Recalled: A bank initiates a recall.
    • Webhook: callback_type: PaymentRecalled is triggered.
    • System Impact: The billogram is automatically reopened (state often changes to Overdue).
  3. Recovery: If the customer doesn't pay / settle the debt, the billogram will enter the configured dunning sequence.
Previous
Webhooks