Skip to main content

Billing Accounts & Grouped Statements

This guide explains how billing accounts and grouped statements behave for external integrators.

It covers:

  • How orders are linked to billing accounts
  • How billing periods and statements are formed
  • What grouped statements GET does and does not do
  • When statements become visible
  • How statement versions change
  • How amendments are reflected
  • Sandbox testing strategy and common pitfalls
Access to Service

To request access to the Billing Account service, contact [email protected].

Quick TL;DR​

  • Grouped statements GET is read-only. It never creates or regenerates statements.
  • start_date and end_date are period coverage dates, not payment due date.
  • due_date is a separate field.
  • Orders can be linked to a billing account only before fulfillment.
  • Statement generation is automated by Two on scheduled batch processing.
  • Final statement availability follows: period end + generation delay + next batch execution.
  • Amended statement availability follows: amendment created + amendment delay + next batch execution.
  • Finalized statements are snapshots. Later GET calls do not live-recalculate them.

API Endpoints Used in This Guide​

Full endpoint details are in the Billing Account API reference.

  • Create billing account: POST /billing/v1/account
  • Update billing account: PATCH /billing/v1/account/{billing_account_id}
  • Get grouped statements: GET /billing/v1/statement
  • Get billing period summary: GET /billing/v1/period-summary
  • Create order (linking billing account): POST /v1/order

Core Data Concepts​

Billing Account​

A billing account defines grouped billing behavior for a merchant + buyer setup.

Important fields:

  • schedule (DAILY, WEEKLY, BIWEEKLY, MONTHLY)
  • due_in_days
  • generation_delay_days
  • recipient email fields

Validation rule:

  • due_in_days must be greater than generation_delay_days

Billing Period​

A billing period is the time window used to group invoiced orders.

Important fields:

  • start_date
  • end_date
  • due_date
  • finalized_date

Open period lifecycle is typically:

  • OPEN
  • WAITING_REFUNDS
  • finalized/closed

Billing Statement​

A billing statement is a generated snapshot for a period.

Common statement reasons/types:

  • PREVIEW
  • FINALISED
  • AMENDED

If multiple versions exist for the same period, integrator-facing list responses return the latest version for that period.

Step 1: Create and Configure a Billing Account​

When creating a billing account, set fields that match your intended operational cadence.

{
  "primary_email_addresses": [
    "[email protected]"
  ],
  "schedule": "MONTHLY",
  "buyer_company": {
    "country_prefix": "GB",
    "organization_number": "00123456",
    "company_name": "Example Corp Ltd"
  },
  "due_in_days": 30,
  "currency": "GBP",
  "account_name": "Main Billing Account",
  "generation_delay_days": 4
}

Practical guidance:

  • Keep schedule and payment terms aligned.
  • Use low generation_delay_days for faster visibility in test environments.
  • Store and reuse returned IDs such as billing_account_id.

Attach billing_account_id when creating an order:

{
  "billing_account_id": "YOUR_BILLING_ACCOUNT_ID",
  "gross_amount": "500.00",
  "currency": "GBP",
  "buyer": {
    "company": {
      "organization_number": "00123456",
      "country_prefix": "GB"
    }
  }
}

Rules:

  • Allowed: add, change, or remove billing_account_id before fulfillment.
  • Not allowed: attach or change billing_account_id after fulfillment.

Best practice:

  • Set billing_account_id at order creation whenever possible.

How Orders Are Assigned to Statement Periods​

Grouping is based on invoicing/fulfillment timing context, not only raw order creation timestamp.

Operationally:

  • invoice_issue_date is the primary assignment date.
  • If invoice_issue_date is unavailable, fallback fulfillment-related dates are used.

Example:

  • Order created on March 30
  • Fulfilled/invoiced on April 2
  • Included in April period/cycle if April timing determines assignment

Period Dates vs Due Date​

In grouped statement responses:

  • start_date and end_date describe period coverage.
  • due_date describes when payment is due.

These values intentionally represent different concepts.

What Grouped Statements GET Actually Does​

Grouped statements GET:

  • reads existing statements from storage
  • returns latest version per period
  • applies normal filtering and pagination

Grouped statements GET does not:

  • create statements
  • trigger period closure
  • trigger preview generation
  • trigger finalization
  • recompute statements from raw orders at request time

Calling GET repeatedly only reveals new changes if generation occurred between calls.

Statement Generation Lifecycle​

1. Period is OPEN​

Orders/invoices are assigned to an open billing period.

2. Period passes close boundary​

The period transitions to WAITING_REFUNDS. A generation-delay window allows late refund or adjustment handling.

3. Finalization window passes​

When the generation-delay window has passed and generation runs, a FINALISED statement is created and the period is finalized.

4. Statement communication​

After statement creation, document delivery and notification flows proceed.

When New Statement Versions Appear​

A new statement version appears only when generation creates one, not when GET is called.

Typical triggers:

  • first eligible finalization (FINALISED)
  • post-finalization amendment processing (AMENDED)
  • preview-specific generation paths (PREVIEW)

Fulfillment Timing vs Existing Statements​

If another order is fulfilled, existing statements are not instantly regenerated.

  • Fulfilling an order does not immediately update statement snapshots.
  • New or updated statements appear only after generation runs.
  • If a period is already finalized, later fulfillments usually belong to a later cycle.
  • Finalized periods generally get new versions due to amendments, not arbitrary later fulfillments.

Amendments (Refunds and Adjustments)​

Amendments are recorded when created, but visibility in grouped statements depends on generation timing.

Typical timing:

  • amendment created
  • amendment delay window passes
  • next generation run creates/updates an AMENDED statement version

Availability Timing Model​

Use this model for operational expectations.

Final statement availability:

  • period end + generation_delay_days + next batch execution

Amended statement availability:

  • amendment creation time + amendment delay + next batch execution

Notes:

  • generation_delay_days is billing-account specific.
  • API defaults may apply where no custom value is configured.
  • Exact execution windows are environment-specific. Contact Two support if you need timing guidance.

Sandbox Testing Strategy​

For deterministic testing, use a dedicated sandbox billing account:

  • short schedule (for example DAILY)
  • low generation_delay_days (for example 0)
  • dedicated buyer/company for isolated test data

Suggested test pattern:

  1. Create order with billing_account_id attached.
  2. Fulfill order and set explicit invoicing timing fields when relevant.
  3. Wait for scheduled generation window.
  4. Validate using grouped statements GET.

Common Pitfalls​

  • Expecting grouped statements GET to generate or refresh statements.
  • Treating start_date and end_date as payment due dates.
  • Trying to attach/change billing_account_id after fulfillment.
  • Expecting finalized periods to include arbitrary later fulfillments.
  • Testing with long schedules and high delays while expecting immediate visibility.

Integration Checklist​

  • Attach billing_account_id at order creation.
  • Persist and reuse IDs from API responses.
  • Treat grouped statements as generated snapshots, not live queries.
  • Design operational SLAs using delay + batch cadence.
  • Keep statement period dates and payment due dates separate in your UI.
  • Add monitoring for "expected statement not yet available" windows.

FAQ​

Does calling grouped statements GET generate statements?​

No. It only returns statements that have already been generated.

Are grouped statements dynamically recalculated on every GET?​

No. They change only when generation creates a new statement version.

Are start_date and end_date due dates?​

No. They are period coverage dates. Due date is due_date.

Can I attach a billing account after order fulfillment?​

No. Billing account linkage is pre-fulfillment only.

When should operations teams expect statements?​

After period end + generation delay + next generation run.

When do amendments appear?​

After amendment delay + next generation run.