Skip to main content
Version: 1.0

Two Billing Account API

Download this API's OpenAPI YAML

Overview and usage​

This API is for creating and managing billing accounts. A billing account serves as a record of transactions and payments for a collection of orders. It helps track and manage the payments a customer owes for the services or products they have received. Billing accounts can be linked to specific businesses and are used to generate grouped payment statements.

To request access to the billing account service, please contact our team at [email protected].

The API enables you to:

  • Create billing accounts for businesses, allowing them to receive grouped payment statements.
  • Define the schedule for sending out grouped payment statements from the billing account.
  • Specify the primary and secondary email recipients who will receive the grouped payment statement emails.

Below is a typical flow of how the API endpoints are used to create a new billing account.

Step 1: Create Billing Account​

Use POST /billing/v1/account to create a new billing account for a given company by passing their legal name and number and defining the billing account configuration for the payment terms, schedule and any delay days. The request response will return a global id which represents the billing_account_id.

Step 2: Attach Or Update Billing Account On Orders​

You can link orders to a billing account in two merchant-facing order flows:

  • Order creation: pass billing_account_id in POST /v1/order.
  • Order edit: pass billing_account_id in PUT /v1/order/{order_id} to add, change, or remove the link

For order edit requests, explicitly sending "billing_account_id": null removes an existing link. Do not pass terms when setting billing_account_id. Billing account payment terms take precedence for repayment scheduling.

Step 3: Validation Rules For billing_account_id​

  • The billing account must belong to the same merchant as the order.
  • The billing account buyer company (country + organization number) must match the order buyer company.
  • Billing account payment terms take precedence over request terms.
  • terms.type=INSTALMENTS cannot be combined with billing_account_id.
  • terms.duration_days_calculated_from (EOM/EOW schemes) cannot be combined with billing_account_id.
  • Updating billing_account_id is only allowed while the order is still editable (pre-fulfillment); post-fulfillment changes are blocked.

Key Details and Interactions for Billing Account Setup**​

Schedule

  • The schedule you set determines how often the recipients on the billing account receive their grouped statements from Two. When setting the schedule, ensure it aligns with the payment terms so that recipients receive their statements within a time frame that makes sense relative to the due date. Avoid setting a schedule that is too frequent for long payment terms or too delayed for short order terms.

Due in Days

  • The due in days setting specifies the payment terms for all orders assigned to the billing account. The total repayment period is calculated based on the schedule and the "due in days" you set. For example, if you choose a schedule of DAILY and set due_in_days to 14, your buyer will have 14 days to pay their order from the time they receive their statement, which in this setup, starts the next day. A common configuration we support is "End of Month plus 30 days." To achieve this, set the schedule to MONTHLY and the due_in_days to 30. This setup will allow billing account recipients to receive their grouped statement at the end of the month, with payment terms starting from that date. As a rule, the payment term begins when the billing account recipients receive their statement.

Generation Delay Days

  • The primary purpose of setting delay days is to allow you, as the merchant, to process any final refunds or changes for orders on a billing account before recipients receive their statements. Note that the generation delay window does not include newly fulfilled orders in the same billing cycle. Any orders created within the generation delay window will roll over to the next billing cycle. By default, billing accounts are created with a 4-day generation delay, but you can adjust this during the setup process if you need a shorter or longer window.

Account Name

  • For a given company, you can create multiple billing accounts to accommodate different areas, departments, or branches. To ensure these accounts are easily distinguishable, we recommend assigning descriptive account names to differentiate them.

Environments​

Testing​

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production​

https://api.two.inc

Authentication​

For instructions on how to obtain API keys, visit this page. You will obtain two different keys, an initial one for testing in our sandbox environment and once ready, for production. Your API keys enables others to act on your behalf if they are able to obtain them, so make sure to keep them safe. Your API key is not to be shared with anyone, including in your version control system, client-side code, in public chatrooms and so on. The API key is applied in the request header. For example:

GET /something
X-Api-Key: secret_test_aabbccddeeff0123456789

API Keys have the following structure: secret_<env>_<key> where:

  • env is determined by the environment (prod for production, test for test environments)
  • key is a random, URL-safe, 64-bit encoded text string containing 32 random bytes.

Security Scheme Type:

apiKey

Header parameter name:

X-Api-Key