Two Billing Account API (1.0)

Download OpenAPI specification:Download

Overview and usage

This API is for creating and managing billing accounts. A billing account is a record of transactions and payments for a collection of orders. It is used to track and manage the payments owed by a customer for the services or products they have received. A billing account can be associated with a specific business, and is used to generate grouped invoices.

Specifically, the API enables you to:

  • Create a billing account attached to a specific business
  • Specify the currency to use for the billing account
  • Create invoice groupings based on the term dates of the invoice in e.g. 14 days
  • Specify the schedule at which the billing account sends out the grouped invoices
  • Specify the email account receiving the grouped invoices
  • Specify an optional CC email list to receive copies of the grouped invoices

Below you will find a description of a typical flow of how the endpoints are called for the purpose of creating a new billing account.

Step 0: Identify the business you are creating the account for

This represents the buyer_company which is defined by their company_name and organization number

Step 1: Create Billing Account

Use POST /billing/v1/account to create a new billing account. The request response will return an id which represents the billing_account_id which is used to form the request body for the POST /order endpoint when creating an order.

Step 2: Attach Order To Billing Account

When building the request body for creating an order POST /order you can specify the billing_account_id which we pulled from the response when creating the billing account. By specifying a billing_account_id when creating an order, it is then attached to that billing account.

Step 3: Get details for a Billing Account by ID

Use GET /billing/v1/account/<billing_account_id> to fetch the details of the billing account you specified through the id path parameter. The response body will detail the following

  • The invoice email
  • Billing account schedule
  • The buyer company associated with the account
  • The due in days
  • The billing account currency
  • Any generation delay in days

Environments

Testing

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production

https://api.two.inc

Create Billing Account

Create new billing account handler

The endpoint POST /billing/v1/account enables the merchant to create a new billing account for a specific buyer. A billing account is a record of financial transactions for goods or services that a customer or client has received and owes payment for. This endpoint allows you to configure the terms and configuration of the billing account through the request body. Key configurations include, the billing account schedule, due_in_days, currency, invoice_email , cc_email_addresses, primary_email_addresses, generation_delay_days and the buyer_company

SecurityX-Api-Key
Request
Request Body schema: application/json
primary_email_addresses
required
Array of strings <email> (Primary Email Addresses)

List of email addresses set to receive billing account emails

cc_email_addresses
Array of strings <email> (Cc Email Addresses)

List of CC email addresses set to receive billing account emails

schedule
required
string (BillingPeriod)

An enumeration for choosing the time period at which grouped invoices will be sent out. Note that BIWEEKLY means twice a month and NOT twice a week. Enum: DAILY WEEKLY BIWEEKLY MONTHLY.

Enum: "DAILY" "WEEKLY" "MONTHLY" "BIWEEKLY"
required
object (Buyer Company)

The company for which the billing account is being created

due_in_days
required
integer (Due In Days) [ 5 .. 60 ]

Due in days to allow for the monthly billing schedule, can be greater than or equal to 5 and less than or equal to 60

currency
required
string (CurrencyEnum)

Currency code in ISO 4217 format. E.g. 'NOK'

Enum: "NOK" "SEK" "GBP" "EUR" "USD" "DKK"
generation_delay_days
integer (Generation Delay Days) >= 0
Default: 4

Number of days to delay the grouped invoice being sent out

account_name
string (Account Name)

A name to identify the billing account

phone_number
string (Phone Number)

Phone number that should be used to contact the account holder

Responses
201

Create billing account

default

Error response

post/billing/v1/account
Request samples
application/json
{
  • "primary_email_addresses": [
    ],
  • "cc_email_addresses": [
    ],
  • "schedule": "DAILY",
  • "buyer_company": {
    },
  • "due_in_days": 5,
  • "currency": "NOK",
  • "generation_delay_days": 4,
  • "account_name": "string",
  • "phone_number": "string"
}
Response samples
application/json
{
  • "primary_email_addresses": [
    ],
  • "cc_email_addresses": [
    ],
  • "schedule": "DAILY",
  • "buyer_company": {
    },
  • "due_in_days": 0,
  • "currency": "NOK",
  • "generation_delay_days": 4,
  • "account_name": "string",
  • "phone_number": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Update Billing Account

Update billing account handler

Note: To update primary_email_addresses, cc_email_addresses, trade_names the request body must include all new values, including values that are not being updated. So if you are adding or removing even a single email to the emailing lists (primary_email_addresses & cc_email_addresses), the entire list must be provided with the updates you need to make.

SecurityX-Api-Key
Request
path Parameters
id
required
string

The ID of the billing account to be updated

Request Body schema: application/json
due_in_days
integer (Due In Days) [ 5 .. 60 ]

Due in days to allow for the monthly billing schedule, can be greater than or equal to 5 and less than or equal to 60

generation_delay_days
integer (Generation Delay Days) >= 0
Default: 4

Number of days to delay the grouped invoice being sent out

primary_email_addresses
Array of strings <email> (Primary Email Addresses)

List of email addresses set to receive billing account emails

cc_email_addresses
Array of strings <email> (Cc Email Addresses)

List of CC email addresses set to receive billing account emails

account_name
string (Account Name)

A name to identify the billing account

phone_number
string (Phone Number)

Phone number for contacting the account holder

Responses
200

Update billing account

404

The billing account with the given ID was not found

default

Error response

patch/billing/v1/account/{id}
Request samples
application/json
{
  • "due_in_days": 5,
  • "generation_delay_days": 4,
  • "primary_email_addresses": [
    ],
  • "cc_email_addresses": [
    ],
  • "account_name": "string",
  • "phone_number": "string"
}
Response samples
application/json
{
  • "primary_email_addresses": [
    ],
  • "cc_email_addresses": [
    ],
  • "schedule": "DAILY",
  • "buyer_company": {
    },
  • "due_in_days": 0,
  • "currency": "NOK",
  • "generation_delay_days": 4,
  • "account_name": "string",
  • "phone_number": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get Billing Account Details

Get billing account by ID.

The endpoint /billing/v1/account/{id} allows you to fetch the details for a given billing account that has been specified by its id

SecurityX-Api-Key
Request
path Parameters
id
required
string

The ID of the billing account to fetch

Responses
200

OK

404

The billing account with the given ID was not found

default

Error response

get/billing/v1/account/{id}
Request samples 
Response samples 
application/json
{
  • "primary_email_addresses": [
    ],
  • "cc_email_addresses": [
    ],
  • "schedule": "DAILY",
  • "buyer_company": {
    },
  • "due_in_days": 0,
  • "currency": "NOK",
  • "generation_delay_days": 4,
  • "account_name": "string",
  • "phone_number": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Billing Statement
Generate previews for billing statements
returns the statement as a file. Can choose period_status by status parameter. This will default to OPEN. Args:     account_id (UUID): Billing account ID


SecurityX-Api-Key 
Request 
path Parameters
account_id
required
string
Billing account ID


 
Responses 
200
OK


404
The billing account with the given ID was not found


default
Error response


get/billing/v1/account/{account_id}/preview_download
Request samples 
Response samples 
application/json
{
  • "error_message": "string"
}
Get all grouped payment statements for authenticated merchant.
SecurityX-Api-Key 
Request 
query Parameters
billing_account_id
string <uuid>  (Billing Account Id) 
 
limit
integer (Limit)   [ 1 .. 1000 ] 
 Default:  3000
 
page_cursor
string (Page Cursor) 
 
search_filter
string (Search Filter) 
 
due_date_from
string (Due Date From) 
 
due_date_to
string (Due Date To) 
 
payment_statuses
string (Payment Statuses) 
 
downloaded
boolean (Downloaded) 
 
Responses 
200
The list with all grouped payment statements for authenticated merchant.


default
Error response


get/billing/v1/statement
Request samples 
Response samples 
application/json
{
  • "statements": [
    ],
  • "cursor_page_metadata": {
    }
}
Get the download URL for the statement document.
SecurityX-Api-Key 
Request 
path Parameters
statement_id
required
string
 
Responses 
200
The download URL for the statement document.


404
Statement not found


default
Error response


get/billing/v1/statement/{statement_id}/download_url
Request samples 
Response samples 
application/json
{
  • "url": "string"
}
Get billing period summary
"Statements" object: Contains all statements issued by Two for this billing period, each statement object reflecting information displayed on the statements the moment they were issued. This section does not change unless a new statement is issued. "Totals" section: Shows the latest reconciliation status of the billing period, and gets updated real-time as each transaction (payments, refunds, etc.) related to invoices in the billing period are reconciled. It shows the current financial status of the billing period, including the currently outstanding balance, and the total payments, total refunds, etc. reconciled against these invoices. To get these details with more granularity, you should subscribe to our webhooks here. Args:     billing_account_id (str): Billing account identifier     period_id (str): Billing period identifier


SecurityX-Api-Key 
Request 
path Parameters
billing_account_id
required
string
Billing account identifier


 
period_id
required
string
Billing period identifier


 
Responses 
200
Billing period summary


404
The billing period with the given attributes was not found


default
Error response


get/billing/v1/account/{billing_account_id}/period/{period_id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "billing_account_id": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "currency": "NOK",
  • "totals": {
    },
  • "statements": [
    ],
  • "bank_account": {
    }
}