Billing Period and Statement Documents

Use these endpoints to show buyers the invoices and credit notes that Two has assigned to a billing period or included in an issued statement. They let your product present Two's document view without sending buyers to the Two buyer portal.

They return structured document metadata and reconciliation state, not individual document PDFs. Use GET /billing/v1/statement/{statement_id}/download_url when you need the PDF for an issued statement.

This guide assumes you already use Billing Accounts for grouped invoicing.

Choose the right endpoint

When you need	Endpoint	What can change
The documents currently assigned to a period, including an open period	GET /billing/v1/account/{billing_account_id}/period/{period_id}/documents	Document membership and invoice reconciliation data can change.
The documents captured in one issued statement	GET /billing/v1/statement/{statement_id}/documents	Document membership is fixed. Invoice reconciliation data remains current.

Both endpoints return the complete, non-paginated document list. Use the period endpoint for a buyer's current billing view. Use the statement endpoint when displaying or reconciling a specific statement that Two has issued.

Get the IDs you need

Store billing_account_id when you create or update an order. There is no separate endpoint for listing open billing periods. After an order is invoiced, persist its billing_period_id from either:

• the order.reconciliation.invoiced.v1 webhook; or
• GET /v1/order/{order_id}/invoice_details.

You can then use those two IDs to retrieve the current billing-period documents.

Get the current documents in a billing period

curl --request GET \
  --url "https://api.two.inc/billing/v1/account/{billing_account_id}/period/{period_id}/documents" \
  --header "X-Api-Key: <your-api-key>"

This endpoint is available before a statement has been issued. Refresh it when you need the latest period content or invoice reconciliation state. A newly issued credit note or payment activity can change the response.

Get the documents captured in an issued statement

curl --request GET \
  --url "https://api.two.inc/billing/v1/statement/{statement_id}/documents" \
  --header "X-Api-Key: <your-api-key>"

Use this endpoint to show what a specific statement contained when it was issued. The document membership and document identity fields are fixed, while invoice reconciliation fields remain live.

If Two later issues an amended statement for the same billing period, keep the original statement_id for historical display. To find the current issued version, call GET /billing/v1/statement?billing_account_id={billing_account_id}, find the statement with the same billing_period_id, and then request that statement's documents. The statement list returns the latest version for each billing period.

Read the response

{
  "documents": [
    {
      "document_type": "INVOICE",
      "document_id": "invoice_123",
      "document_number": "INV-1001",
      "issue_date": "2026-10-01",
      "amount": "120.00",
      "currency": "GBP",
      "order_id": "order_123",
      "related_invoice_id": null,
      "current_outstanding_amount": "70.00",
      "current_reconciliation_status": "PARTIAL_PAYMENT"
    },
    {
      "document_type": "CREDIT_NOTE",
      "document_id": "credit_note_456",
      "document_number": "CN-1001",
      "issue_date": "2026-10-03",
      "amount": "-20.00",
      "currency": "GBP",
      "order_id": "order_123",
      "related_invoice_id": "invoice_123",
      "current_outstanding_amount": null,
      "current_reconciliation_status": null
    }
  ]
}

• amount is the gross document amount: invoices are positive and credit notes are negative.
• related_invoice_id identifies the invoice credited by a credit note.
• current_outstanding_amount and current_reconciliation_status apply to invoices only. They are null for credit notes.

Current reconciliation state

Use current_reconciliation_status and current_outstanding_amount to show the latest state recorded in Two's reconciliation ledger. They are live fields, including when returned through the statement endpoint. The values below are the statuses returned by these document endpoints.

Status	Meaning
NOT_PAID	No payment, credit, collection, or recourse has been applied.
PARTIAL_PAYMENT	The invoice is partly paid.
PAID	The invoice is fully settled by payment or collection.
REFUNDED	The invoice is fully credited.
PARTIAL_REFUND	The invoice is partly credited.
IN_COLLECTIONS	Collection activity exists while a balance remains.
RECOURSED	The full amount has been recoursed.
PARTIAL_RECOURSE	Part of the amount has been recoursed.

current_outstanding_amount is signed: a positive amount is still outstanding, zero is fully reconciled, and a negative amount means the reconciliation ledger records more applied value than the invoice amount. It is a reconciliation-ledger condition, not a separate credit-note document. Do not clamp a negative amount to zero; show it as returned and contact Two support if you need help reconciling it.

Recommended integration pattern

1. Store billing_account_id when assigning an order to a billing account, then persist billing_period_id when the order is invoiced.
2. Retrieve period documents for the current buyer-facing billing view.
3. Use reconciliation webhooks as refresh signals for period data. Do not assume an open period or its reconciliation fields are immutable.
4. Subscribe to billing_statement.created.v1. It tells you that a statement has been issued for a billing account and period, but does not include the issued statement_id.
5. In response to that event, list statements for the billing account, find the entry with the event's billing_period_id, and use its statement_id to retrieve the issued-statement document view.
6. Treat a statement's document membership as fixed, but allow its invoice reconciliation fields to update in your UI. Retain the original statement ID if a later amended statement is issued.

These endpoints do not define a separate billing-document rate limit. Follow standard retry and backoff practices if your integration receives a rate-limit response.

For statement-generation timing and amendment behaviour, see Understanding Billing Accounts. For complete request and response schemas, see the Billing Account API reference.