NAV Navbar
Billby api
shell ruby python php java

API Overview

Welcome to the Billby API! You can use our API to connect your app to a Billby site.

Getting Started

Before using the Billby API, you will need to:

  1. Sign up to Billby for a free account.
  2. Create an API Key via a browser on your Billby site for Billby API Access.

Authorisation

To authenticate, include the base64 encoded credentials in the Authorization header:

curl "https://api_endpoint_here"
  -u api_key:

# or if you have already base 64 encoded the api key:

curl "https://api_endpoint_here"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'
require 'base64'

uri = URI.parse("https://api_endpoint_here")
encoded_token = Base64.encode64(api_key+":")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic "+encoded_token

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests
import base64

encoded_token = base64.b64encode(bytes(api_key+':'))

headers = {
    'Authorization': 'Basic '+encoded_token,
}

response = requests.get('https://api_endpoint_here', headers=headers)
$encoded_token = base64_encode($api_key.':');
$headers = [
    'Authorization: Basic ' . $encoded_token,
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'api_endpoint_here');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;
import java.util.Base64;
import java.util.Base64.Encoder;
import java.util.Base64.Decoder;

String encoded_token = Base64.getEncoder().withoutPadding().encodeToString(api_key+":")
URL url = new URL("https://api_endpoint_here");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", encoded_token);

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Make sure to replace api_key with your API key.

Billby uses HTTP BASIC Auth for authenticating API requests. Use your API key for 'user' and leave 'password' empty. To create an API key see Getting Started.

To authenticate, include the authorisation header in all API requests:

Authorization: Basic encoded_token

The encoded_token is generated by base 64 encoding your api key in the format, base64_encode(user:) where user is your api key (remember to include the colon).

Access tokens do not expire.

Requests and Responses

Make a Request

The Billby API is a RESTful service. To make an API call, you direct a HTTP request using the relevant HTTP verb to the desired endpoint. The request must include the required headers and relevant body parameters. For GET queries, you may also include URL query parameters.

For example, to get a list of accounts, you make a GET request to

GET https://api.billby.com/v2/accounts

A successful request will return a response with a HTTP 200 status code and a body in JSON format. For unsuccessful responses, see HTTP Response Codes & Errors

For information on the requirements and options for each endpoint, see the API Reference for the specific resource.

Required Headers

Header Name Header Value
Authorization Basic ✱✱✱encoded_token✱✱✱
Content-Type application/json; charset=utf-8

See Authorisation for information on how to obtain the access token.

For POST/PUT requests, the content-type should be set to "application/json" and the encoding type should be set as "UTF-8"

API Limits

The API instates limits on the number of API calls your application can make:

Every response will be sent with the following HTTP headers containing the current rate limiting information:

X-Rate-Limit-Limit, the maximum number of requests allowed
X-Rate-Limit-Remaining, the number of remaining requests in the current 60 second window
X-Rate-Limit-Reset, the number of seconds to wait in order to get the maximum number of allowed requests

Requesting beyond this limit will return a HTTP Too Many Requests error with status code 429.

GET Requests

To send a GET request to list all accounts

curl "https://api.billby.com/v2/accounts"
  -H "Authorization: Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6',
}

response = requests.get('https://api.billby.com/v2/accounts', headers=headers)
$headers = [
    'Authorization: Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "accounts": [
      {
        "code": "BIG001",
        "currency": {
          "uuid": "AUD",
          "href": "https://api.billby.com/v2/currencies/AUD"
        },
        "country": {
          "uuid": "AU",
          "href": "https://api.billby.com/v2/countries/AU"
        },
        "tax": {
          "code": "GST",
          "href": "https://api.billby.com/v2/taxes/GST"
        },
        "account_name": "BIG Co.",
        "first_name": "Biggie",
        "last_name": "Smalls",
        "full_name": "Biggie Smalls",
        "email": "biggie@bigco.net",
        "phone": "03 9597 8898",
        "address": "1 Swans St",
        "address_2": "",
        "city": "Melbourne",
        "state": "Vic",
        "postcode": "3000",
        "terms": 0,
        "tax_exempt": false,
        "gateway": "STRIPE",
        "status": "OPEN",
        "email_reminder": true,
        "email_invoice_new": true,
        "email_invoice_overdue": true,
        "email_payment_confirmed": true,
        "email_payment_failed": true,
        "email_payment_voided": true,
        "email_refund": true,
        "pages_update_account": true,
        "pages_subscribe": true,
        "pages_update_subscription": true,
        "pages_update_payment_method": true,
        "pages_view_invoices": true,
        "pages_make_payment": true,
        "created_at": "2017-09-06T12:12:46+00:00",
        "updated_at": "2017-09-06T12:12:46+00:00",
        "href": "https://api.billby.com/v2/accounts/BIG001" 
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/accounts?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/accounts?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Retrieving Individual Resources

To retrieve a specific resource, append a resource identifer (e.g. UUID or code) to the end of the endpoint's url. For example, to retrieve a specific account:

GET https://api.billby.com/v2/accounts/BIG001

Date formats

Dates are returned in the ISO 8601 format, for example:

2017-03-14T05:15:11+00:00

Retrieving All Resources

To retrieve a full list of resources, simply include the resource endpoint in the URL, for example:

GET https://api.billby.com/v2/accounts

When retrieving lists from resources with large result sets, we recommend using filtering query parameters.

Retrieving Paged Resources

To retrieve specific pages, append the page parameter to URL. For example, the following will return the second page of results

GET https://api.billby.com/v2/accounts?page=2

By default, GET queries will return 20 resources per page. For most endpoints, you may modify the number of results returned per page by appending the page_size parameter to the URL. For example, the following will return a single resource per page

GET https://api.billby.com/v2/accounts?page_size=1

When retrieving lists, the response body will include the following parameters under the _meta parameter:

Key Description
total_count The total number of resources
page_count The total number of pages
current_page The current page number
page_size The number of resources per page

The response also includes hypermedia links to related pages under the _links parameter:

Key Description
self The URL of the current page
first The URL of the first page
next The URL of the next page
last The URL of the last page

Retrieving a Filtered Set of Resources

A number of the endpoints provide additional query parameters for filtering the result. Using filters will help limit the number of requests your app is required to make and thus improve app performance. For example, to filter accounts by account name:

GET https://api.billby.com/v2/accounts?name=Biggie%20Smalls

To filter using multiple values for a parameter:

GET https://api.billby.com/v2/subscriptions?status[]=COMMITTED&status[]=SUBSCRIBEDTRIAL

Sorting Results

A sort parameter may be included to sort on sortable attributes. Using sort may help limit the number of requests your app is required to make and thus improve app performance, however unneccessary sorting may impact performance. To sort, include the sort query parameter followed by the sortable attribute. To sort by multiple attributes delimit each attribute by a comma. For example, to order invoices by due date:

GET https://api.billby.com/v2/invoices?sort=due_date

Expanding Nested Attributes

Where an endpoint returns a resource with nested attributes (other resources), these are usually condensed references. As described in each endpoint documentation, some nested attributes may be expanded. To expand the attribute, include an expand query parameter follwed by the attribute. To expand multiple attributes delimit each attribute by a comma. For example, to expand the account on a subscription lookup:

GET https://api.billby.com/v2/subscriptions?expand=account

POST and PUT Requests

To send a POST request to create a new account

curl "https://api.billby.com/v2/accounts"
  -X POST
  -H "Authorization: Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "account": {
      "code": "BIG001",
      "currency": {
        "uuid": "AUD"
      },
      "country": {
        "uuid": "AU"
      },
      "tax": {
        "code": "GST"
      },
      "account_name": "BIG Co.",
      "first_name": "Biggie",
      "last_name": "Smalls",
      "phone": "03 9597 8898",
      "email": "biggie@bigco.net",
      "address": "1 Swans St",
      "address_2": "",
      "city": "Melbourne",
      "state": "Vic",
      "postcode": "3000",
      "state": "Victoria",
      "terms": "14",
      "tax_exempt": false
    }
  }'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  account: {
    code: "BIG001",
    currency: {
      uuid: "AUD"
    },
    country: {
      uuid: "AU"
    },
    tax: {
      code: "GST"
    },
    account_name: "BIG Co.",
    first_name: "Biggie",
    last_name: "Smalls",
    phone: "03 9597 8898",
    email: "biggie@bigco.net",
    address: "1 Swans St",
    address_2: "",
    city: "Melbourne",
    state: "Vic",
    postcode: "3000",
    state: "Victoria",
    terms: "14",
    tax_exempt: false
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'account': {
    'code': 'BIG001',
    'currency': {
      'uuid': 'AUD'
    },
    'country': {
      'uuid': 'AU'
    },
    'tax': {
      'code': 'GST'
    },
    'account_name': 'BIG Co.',
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'phone': '03 9597 8898',
    'email': 'biggie@bigco.net',
    'currency_code': 'AUD',
    'address': '1 Swans St',
    'address_2': '',
    'city': 'Melbourne',
    'state': 'Vic',
    'postcode': '3000',
    'state': 'Victoria',
    'terms': '14',
    'tax_exempt': false
  }
}

response = requests.get('https://api.billby.com/v2/accounts', headers=headers, data=data)
$headers = [
    'Authorization: Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "account" => [
    "code" => "BIG001",
    "currency" => [
      "uuid" => "AUD"
    ],
    "country" => [
      "uuid": "AU"
    ],
    "tax" => [
      "code" => "GST"
    ],
    "account_name" => "BIG Co.",
    "first_name" => "Biggie",
    "last_name" => "Smalls",
    "phone" => "03 9597 8898",
    "email" => "biggie@bigco.net",
    "currency_code" => "AUD",
    "address" => "1 Swans St",
    "address_2" => "",
    "city" => "Melbourne",
    "state" => "Vic",
    "postcode" => "3000",
    "state" => "Victoria",
    "terms" => "14",
    "tax_exempt" => false
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api_endpoint_here");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'account': {
    'code': 'BIG001',
    'currency': {
      'uuid': 'AUD'
    },
    'country': {
      'uuid': 'AU'
    },
    'tax': {
      'code': 'GST'
    },
    'account_name': 'BIG Co.',
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'phone': '03 9597 8898',
    'email': 'biggie@bigco.net',
    'currency_code': 'AUD',
    'address': '1 Swans St',
    'address_2': '',
    'city': 'Melbourne',
    'state': 'Vic',
    'postcode': '3000',
    'country_code': 'AU',
    'state': 'Victoria',
    'terms': '14',
    'tax_exempt': false
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "code": "BIG001",
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "country": {
      "uuid": "AU",
      "href": "https://api.billby.com/v2/countries/AU"
    },
    "tax": {
      "code": "GST",
      "href": "https://api.billby.com/v2/taxes/GST"
    },
    "account_name": "BIG Co.",
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "email": "biggie@bigco.net",
    "phone": "03 9597 8898",
    "address": "1 Swans St",
    "address_2": "",
    "city": "Melbourne",
    "state": "Vic",
    "postcode": "3000",
    "terms": 0,
    "tax_exempt": false,
    "gateway": "STRIPE",
    "status": "OPEN",
    "email_reminder": true,
    "email_invoice_new": true,
    "email_invoice_overdue": true,
    "email_payment_confirmed": true,
    "email_payment_failed": true,
    "email_payment_voided": true,
    "email_refund": true,
    "pages_update_account": true,
    "pages_subscribe": true,
    "pages_update_subscription": true,
    "pages_update_payment_method": true,
    "pages_view_invoices": true,
    "pages_make_payment": true,
    "created_at": "2017-09-06T12:12:46+00:00",
    "updated_at": "2017-09-06T12:12:46+00:00",
    "href": "https://api.billby.com/v2/accounts/BIG001" 
  }
}

Creating (POST) and updating (PUT) requests require JSON body parameters for all required fields as specified in the API reference for that endpoint. Note the requirement for a root node, e.g. 'account'.

A successful POST and PUT request will return a response with a HTTP 200 status code and the resource identifier (i.e. UUID) and hyperlink in the body in JSON format.

At present you may only POST or PUT a single resource at a time.

Creating Resources

Use POST for creating new resources. For example,

POST https://api.billby.com/v2/accounts

Updating Resources

Use PUT for updating current resources. For example,

PUT https://api.billby.com/v2/accounts/BIG001

DELETE Requests

To send a DELETE request to delete an account

curl "https://api.billby.com/v2/accounts/BIG001"
  -X DELETE
  -H "Authorization: Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts/BIG001")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6',
}

response = requests.delete('https://api.billby.com/v2/accounts/BIG001', headers=headers)
$headers = [
    'Authorization: Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts/BIG001');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts/BIG001");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestMethod("DELETE");
httpConnection.setRequestProperty("Authorization", "Basic NmjRTejklNFQwYzThYbFk3QVnWNzNBjBpNlNOFZmRUM6");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Use DELETE for deleting current resources. For example,

DELETE https://api.billby.com/v2/taxes/GST

HTTP Response Codes & Errors

A summary of HTTP response codes returned by the Billby API.

HTTP Code Type Description
200 OK The request was successful
400 Bad Request Bad request, eg. request body malformed
401 Unauthorized Unauthorised request. Check your access token
404 Not Found The requested resource could not be found
422 Unprocessable Entity Validation error
429 Too Many Requests Your application has made too many requests. See API Limits
500 Internal Server Error An error occured while the server was processing the request.
503 Service Unavailable The API is temporarily unavailable

HTTP 422 Unprocessable Entity

The response body will include an array of error messages. A validation error has occurred, for example due to missing required parameters.

A validation error will return a HTTP 422 response with messages in the body

{
  "success": false,
  "data": {
    "error": [
      "Account: First Name cannot be blank.",
      "Account: Account Code should contain at most 50 characters."
    ]
  }
}

Warnings

The response body may also include warning messages

{
  "success": true,
  "data": {
    "warning": [
        "Account: Email not sent"
    ]
  }
}

Quick Reference

Base URL

https://api.billby.com/v2/

Authentication

To authenticate include base64 encoded credentials in the Authorization header in all API requests.

Authorization: Basic encoded_token

encoded_token = base64_encode(user:) where user is your api key.

URI Format

Action URI Example
Create POST https://api.billby.com/version/resourceName https://api.billby.com/v2/accounts
Read (single) GET https://api.billby.com/version/resourceName/resourceIdentifer https://api.billby.com/v2/accounts/BIG001
Read (list) GET https://api.billby.com/version/resourceName/ https://api.billby.com/v2/accounts
Update PUT https://api.billby.com/version/resourceName/resourceIdentifer https://api.billby.com/v2/accounts/BIG001
Delete DELETE https://api.billby.com/version/resourceName/resourceIdentifer https://api.billby.com/v2/accounts/BIG001

Date formats

Request and response dates use the ISO 8601 format, for example:

2017-03-14T05:15:11+00:00

Error handling

See HTTP Response Codes & Errors

API Reference

Accounts

Overview

An account represents a customer who subscribes to a product that your business offers.

URL https://api.billby.com/v2/accounts
Methods GET POST PUT DELETE

List Accounts

GET https://api.billby.com/v2/accounts

curl "https://api.billby.com/v2/accounts"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/accounts', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "accounts": [
      {
        "code": "BIG001",
        "currency": {
          "uuid": "AUD",
          "href": "https://api.billby.com/v2/currencies/AUD"
        },
        "country": {
          "uuid": "AU",
          "href": "https://api.billby.com/v2/countries/AU"
        },
        "tax": {
          "code": "GST",
          "href": "https://api.billby.com/v2/taxes/GST"
        },
        "account_name": "BIG Co.",
        "first_name": "Biggie",
        "last_name": "Smalls",
        "full_name": "Biggie Smalls",
        "email": "biggie@bigco.net",
        "phone": "03 9597 8898",
        "address": "1 Swans St",
        "address_2": "",
        "city": "Melbourne",
        "state": "Vic",
        "postcode": "3000",
        "terms": 0,
        "tax_exempt": false,
        "gateway": "STRIPE",
        "status": "OPEN",
        "email_reminder": true,
        "email_invoice_new": true,
        "email_invoice_overdue": true,
        "email_payment_confirmed": true,
        "email_payment_failed": true,
        "email_payment_voided": true,
        "email_refund": true,
        "pages_update_account": true,
        "pages_subscribe": true,
        "pages_update_subscription": true,
        "pages_update_payment_method": true,
        "pages_view_invoices": true,
        "pages_make_payment": true,
        "created_at": "2017-09-06T12:12:46+00:00",
        "updated_at": "2017-09-06T12:12:46+00:00",
        "href": "https://api.billby.com/v2/accounts/BIG001"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/accounts?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/accounts?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all accounts.

HTTP Request

GET https://api.billby.com/v2/accounts

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
account_name - Filter the results by account, ie account name
status - Filter the results by status, either 'OPEN' or 'CLOSED'
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
code Unique identifier code string(50)
currency Nested currency reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
country Nested country reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
tax Nested tax reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
account_name Account name string(40)
first_name Contact first name string(40)
last_name Contact last name string(40)
full_name Contact full name string(80)
email Email address string(40)
phone Phone number string(40)
address First line of address string(100)
address_2 Second line of address string(100)
city Address city/town/suburb string(40)
state Address state/region/province string(40)
postcode Address postcode string(10)
terms Payment terms in days integer(2)
tax_exempt Whether tax exempt. boolean
gateway The default payment gateway. Payment method setting overrides string(40)
status Account status, 'OPEN' or 'CLOSED' string
email_reminder Whether to send email reminders boolean
email_invoice_new Whether to send new invoice emails boolean
email_invoice_overdue Whether to send overdue emails boolean
email_payment_confirmed Whether to send payment confirmed emails boolean
email_payment_failed Whether to send payment failed emails boolean
email_payment_voided Whether to send payment voided emails boolean
email_refund Whether to send refund emails boolean
pages_update_account Whether to allow access to update account hosted page boolean
pages_subscribe Whether to allow access to subscribe hosted page boolean
pages_update_subscription Whether to allow access to update subscription hosted page boolean
pages_update_payment_method Whether to allow access to update payment method hosted page boolean
pages_view_invoices Whether to allow access to view invoices hosted page boolean
pages_make_payment Whether to allow access to make payment hosted page boolean
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

Lookup Account

GET https://api.billby.com/v2/accounts/<code>

curl "https://api.billby.com/v2/accounts/BIG001"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts/BIG001")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/accounts/BIG001', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts/BIG001');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts/BIG001");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "code": "BIG001",
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "country": {
      "uuid": "AU",
      "href": "https://api.billby.com/v2/countries/AU"
    },
    "tax": {
      "code": "GST",
      "href": "https://api.billby.com/v2/taxes/GST"
    },
    "account_name": "BIG Co.",
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "email": "biggie@bigco.net",
    "phone": "03 9597 8898",
    "address": "1 Swans St",
    "address_2": "",
    "city": "Melbourne",
    "state": "Vic",
    "postcode": "3000",
    "terms": 0,
    "tax_exempt": false,
    "gateway": "STRIPE",
    "status": "OPEN",
    "email_reminder": true,
    "email_invoice_new": true,
    "email_invoice_overdue": true,
    "email_payment_confirmed": true,
    "email_payment_failed": true,
    "email_payment_voided": true,
    "email_refund": true,
    "pages_update_account": true,
    "pages_subscribe": true,
    "pages_update_subscription": true,
    "pages_update_payment_method": true,
    "pages_view_invoices": true,
    "pages_make_payment": true,
    "created_at": "2017-09-06T12:12:46+00:00",
    "updated_at": "2017-09-06T12:12:46+00:00",
    "href": "https://api.billby.com/v2/accounts/BIG001"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific account.

HTTP Request

GET https://api.billby.com/v2/accounts/<code>

URI Parameters

Parameter Description
code The unique account code of the account to retrieve

Response Body Parameters

See List Account response body parameters

Create Account

POST https://api.billby.com/v2/accounts

curl "https://api.billby.com/v2/accounts"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "account": {
      "code": "BIG001",
      "currency": {
        "uuid": "AUD"
      },
      "country": {
        "uuid": "AU"
      },
      "tax": {
        "code": "GST"
      },
      "account_name": "BIG Co.",
      "first_name": "Biggie",
      "last_name": "Smalls",
      "phone": "03 9597 8898",
      "email": "biggie@bigco.net",
      "address": "1 Swans St",
      "address_2": "",
      "city": "Melbourne",
      "state": "Vic",
      "postcode": "3000",
      "state": "Victoria",
      "terms": "14",
      "tax_exempt": false
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  account: {
    code: "BIG001",
    currency: {
      uuid: "AUD"
    },
    country: {
      uuid: "AU"
    },
    tax: {
      code: "GST"
    },
    account_name: "BIG Co.",
    first_name: "Biggie",
    last_name: "Smalls",
    phone: "03 9597 8898",
    email: "biggie@bigco.net",
    address: "1 Swans St",
    address_2: "",
    city: "Melbourne",
    state: "Vic",
    postcode: "3000",
    state: "Victoria",
    terms: "14",
    tax_exempt: false
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'account': {
    'code': 'BIG001',
    'currency': {
      'uuid': 'AUD'
    },
    'country': {
      'uuid': 'AU'
    },
    'tax': {
      'code': 'GST'
    },
    'account_name': 'BIG Co.',
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'phone': '03 9597 8898',
    'email': 'biggie@bigco.net',
    'currency_code': 'AUD',
    'address': '1 Swans St',
    'address_2': '',
    'city': 'Melbourne',
    'state': 'Vic',
    'postcode': '3000',
    'state': 'Victoria',
    'terms': '14',
    'tax_exempt': false
  }
}

response = requests.post('https://api.billby.com/v2/accounts', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "account" => [
    "code" => "BIG001",
    "currency" => [
      "uuid" => "AUD"
    ],
    "country" => [
      "uuid": "AU"
    ],
    "tax" => [
      "code" => "GST"
    ],
    "account_name" => "BIG Co.",
    "first_name" => "Biggie",
    "last_name" => "Smalls",
    "phone" => "03 9597 8898",
    "email" => "biggie@bigco.net",
    "currency_code" => "AUD",
    "address" => "1 Swans St",
    "address_2" => "",
    "city" => "Melbourne",
    "state" => "Vic",
    "postcode" => "3000",
    "state" => "Victoria",
    "terms" => "14",
    "tax_exempt" => false
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'account': {
    'code': 'BIG001',
    'currency': {
      'uuid': 'AUD'
    },
    'country': {
      'uuid': 'AU'
    },
    'tax': {
      'code': 'GST'
    },
    'account_name': 'BIG Co.',
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'phone': '03 9597 8898',
    'email': 'biggie@bigco.net',
    'currency_code': 'AUD',
    'address': '1 Swans St',
    'address_2': '',
    'city': 'Melbourne',
    'state': 'Vic',
    'postcode': '3000',
    'country': {
      'uuid': 'AU'
    },
    'state': 'Victoria',
    'terms': '14',
    'tax_exempt': false
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "code": "BIG001",
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "country": {
      "uuid": "AU",
      "href": "https://api.billby.com/v2/countries/AU"
    },
    "tax": {
      "code": "GST",
      "href": "https://api.billby.com/v2/taxes/GST"
    },
    "account_name": "BIG Co.",
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "email": "biggie@bigco.net",
    "phone": "03 9597 8898",
    "address": "1 Swans St",
    "address_2": "",
    "city": "Melbourne",
    "state": "Vic",
    "postcode": "3000",
    "terms": 0,
    "tax_exempt": false,
    "gateway": "STRIPE",
    "status": "OPEN",
    "email_reminder": true,
    "email_invoice_new": true,
    "email_invoice_overdue": true,
    "email_payment_confirmed": true,
    "email_payment_failed": true,
    "email_payment_voided": true,
    "email_refund": true,
    "pages_update_account": true,
    "pages_subscribe": true,
    "pages_update_subscription": true,
    "pages_update_payment_method": true,
    "pages_view_invoices": true,
    "pages_make_payment": true,
    "created_at": "2017-09-06T12:12:46+00:00",
    "updated_at": "2017-09-06T12:12:46+00:00",
    "href": "https://api.billby.com/v2/accounts/BIG001"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint creates a new account. See Body Parameters for required parameters.

HTTP Request

POST https://api.billby.com/v2/accounts

Body Parameters

Parameter Description Type Required
code Unique identifier code string(50)
currency Nested currency reference object
      uuid Unique identifier string(50)
country Nested country reference object
      uuid Unique identifier string(50)
account_name Account name string(40)
first_name Contact first name string(40)
last_name Contact last name string(40)
email Email address string(40)
phone Phone number string(40)
address First line of address string(100)
address_2 Second line of address string(100)
city Address city/town/suburb string(40)
state Address state/region/province string(40)
postcode Address postcode string(10)
terms Payment terms in days integer(2)
tax_exempt Whether tax exempt. boolean
gateway The default payment gateway. Payment method setting overrides. ‘STRIPE’, ‘SECURE_PAY’, ‘PAYPAL’, ‘EWAY’, or ‘AUTHORIZE_NET’ string(40)
email_reminder Whether to send email reminders boolean
email_invoice_new Whether to send new invoice emails boolean
email_invoice_overdue Whether to send overdue emails boolean
email_payment_confirmed Whether to send payment confirmed emails boolean
email_payment_failed Whether to send payment failed emails boolean
email_payment_voided Whether to send payment voided emails boolean
email_refund Whether to send refund emails boolean
pages_update_account Whether to allow access to update account hosted page boolean
pages_subscribe Whether to allow access to subscribe hosted page boolean
pages_update_subscription Whether to allow access to update subscription hosted page boolean
pages_update_payment_method Whether to allow access to update payment method hosted page boolean
pages_view_invoices Whether to allow access to view invoices hosted page boolean
pages_make_payment Whether to allow access to make payment hosted page boolean

Update Account

PUT https://api.billby.com/v2/accounts/<code>

curl "https://api.billby.com/v2/accounts/BIG001"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "account": {
      "code": "BIG001",
      "first_name": "Andrew",
      "last_name": "Myers",
      "email": "andrew@bigco.net"
    }
  }'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts/BIG001")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  account: {
    code: "BIG001",
    first_name: "Andrew",
    last_name: "Myers",
    email: "andrew@bigco.net",
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'account': {
    'code': 'BIG001',
    'first_name': 'Andrew',
    'last_name': 'Myers',
    'email': 'andrew@bigco.net',
  }
}

response = requests.put('https://api.billby.com/v2/accounts/BIG001', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "account" => [
    "code" => "BIG001",
    "first_name" => "Andrew",
    "last_name" => "Myers",
    "email" => "andrew@bigco.net",
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts/BIG001');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts/BIG001");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
  'account': {
    'code': 'BIG001',
    'first_name': 'Andrew',
    'last_name': 'Myers',
    'email': 'andrew@bigco.net',
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "code": "BIG001",
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "country": {
      "uuid": "AU",
      "href": "https://api.billby.com/v2/countries/AU"
    },
    "tax": {
      "code": "GST",
      "href": "https://api.billby.com/v2/taxes/GST"
    },
    "account_name": "BIG Co.",
    "first_name": "Andrew",
    "last_name": "Myers",
    "full_name": "Andrew Myers",
    "email": "andrew@bigco.net",
    "phone": "03 9597 8898",
    "address": "1 Swans St",
    "address_2": "",
    "city": "Melbourne",
    "state": "Vic",
    "postcode": "3000",
    "terms": 0,
    "tax_exempt": false,
    "gateway": "STRIPE",
    "status": "OPEN",
    "email_reminder": true,
    "email_invoice_new": true,
    "email_invoice_overdue": true,
    "email_payment_confirmed": true,
    "email_payment_failed": true,
    "email_payment_voided": true,
    "email_refund": true,
    "pages_update_account": true,
    "pages_subscribe": true,
    "pages_update_subscription": true,
    "pages_update_payment_method": true,
    "pages_view_invoices": true,
    "pages_make_payment": true,
    "created_at": "2017-09-06T12:12:46+00:00",
    "updated_at": "2017-09-11T18:12:46+00:00",
    "href": "https://api.billby.com/v2/accounts/BIG001"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint updates an existing account. See Body Parameters for required parameters.

HTTP Request

PUT https://api.billby.com/v2/accounts/<code>

URI Parameters

Parameter Description
code The unique account code of the account to update

Body Parameters

Parameter Description Type Required
code Unique identifier code string(50)
country Nested country reference object
      uuid Unique identifier string(50)
account_name Account name string(40)
first_name Contact first name string(40)
last_name Contact last name string(40)
email Email address string(40)
phone Phone number string(40)
address First line of address string(100)
address_2 Second line of address string(100)
city Address city/town/suburb string(40)
state Address state/region/province string(40)
postcode Address postcode string(10)
terms Payment terms in days integer(2)
tax_exempt Whether tax exempt. boolean
gateway The default payment gateway. Payment method setting overrides. ‘STRIPE’, ‘SECURE_PAY’, ‘PAYPAL’, ‘EWAY’, or ‘AUTHORIZE_NET’ string(40)
email_reminder Whether to send email reminders boolean
email_invoice_new Whether to send new invoice emails boolean
email_invoice_overdue Whether to send overdue emails boolean
email_payment_confirmed Whether to send payment confirmed emails boolean
email_payment_failed Whether to send payment failed emails boolean
email_payment_voided Whether to send payment voided emails boolean
email_refund Whether to send refund emails boolean
pages_update_account Whether to allow access to update account hosted page boolean
pages_subscribe Whether to allow access to subscribe hosted page boolean
pages_update_subscription Whether to allow access to update subscription hosted page boolean
pages_update_payment_method Whether to allow access to update payment method hosted page boolean
pages_view_invoices Whether to allow access to view invoices hosted page boolean
pages_make_payment Whether to allow access to make payment hosted page boolean

Signup an Account

POST https://api.billby.com/v2/accounts/signup

curl "http://api.billby.com/v2/accounts/signup"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "account": {
      "code": "BIG001",
      "currency": {
        "uuid": "AUD"
      },
      "country": {
        "uuid": "AU"
      },
      "tax": {
        "code": "GST"
      },
      "account_name": "BIG Co.",
      "first_name": "Biggie",
      "last_name": "Smalls",
      "phone": "03 9597 8898",
      "email": "biggie@bigco.net",
      "address": "1 Swans St",
      "address_2": "",
      "city": "Melbourne",
      "state": "Vic",
      "postcode": "3000",
      "state": "Victoria",
      "terms": "14",
      "tax_exempt": false,
    },
    "subscription": {
      "account": {
        "code": "BIG001"
      },
      "product": {
        "code":"BG_VOIP_GLD"
      },
      "trial_days": 10,
      "subscription_add_ons": [{
        "add_on": {
          "code":"BG_PS"
        },
        "coupon_code": "10OFFWINTER",
        "quantity": 1
      }],
      "coupon_code": "15OFFGOLD",
      "quantity": 3,
      "po_number": "PO6767",
      "payment_method": {
        "first_name": "Biggie",
        "last_name": "Smalls",
        "company": "Biggie Smalls Co.",
        "phone": "040000000",
        "company_number": "51 824 753 556",
        "address": "1 Smith St",
        "address_2": "",
        "city": "Mont Albert",
        "postcode": "3145",
        "country": {
          "uuid": "AU"
        },
        "state": "Victoria",
        "type": "CREDIT_CARD",
        "card": "4242424242424242",
        "card_month": "12",
        "card_year": "2017",
        "card_cvv": "121",
        "gateway": "STRIPE"
      },
      "future_start_date": "2017-09-14T00:00:00+00:00"
    }
  }'
require 'net/http'
require 'uri'

uri = URI.parse("http://api.billby.com/v2/accounts/signup")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  account: {
    code: "BIG001",
    currency: {
      uuid: "AUD"
    },
    country: {
      uuid: "AU"
    },
    tax: {
      code: "GST"
    },
    account_name: "BIG Co.",
    first_name: "Biggie",
    last_name: "Smalls",
    phone: "03 9597 8898",
    email: "biggie@bigco.net",
    address: "1 Swans St",
    address_2: "",
    city: "Melbourne",
    state: "Vic",
    postcode: "3000",
    state: "Victoria",
    terms: "14",
    tax_exempt: false
  },
  subscription: {
    account: {
      code: "BIG001"
    },
    product: {
      code:"BG_VOIP_GLD"
    },
    trial_days: 10,
    subscription_add_ons: [{
      add_on: {
        code:"BG_PS"
      },
      coupon_code: "10OFFWINTER",
      quantity: 1
    }],
    coupon_code: "15OFFGOLD",
    quantity: 3,
    po_number: "PO6767",
    payment_method: {
      first_name: "Biggie",
      last_name: "Smalls",
      company: "Biggie Smalls Co.",
      phone: "040000000",
      company_number: "51 824 753 556",
      address: "1 Smith St",
      address_2: "",
      city: "Mont Albert",
      postcode: "3145",
      country: {
        uuid: "AU"
      },
      state: "Victoria",
      type: "CREDIT_CARD",
      card: "4242424242424242",
      card_month: "12",
      card_year: "2017",
      card_cvv: "121",
      gateway: "STRIPE"
    },
    future_start_date: "2017-09-14T00:00:00+00:00"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'account': {
    'code': 'BIG001',
    'currency': {
      'uuid': 'AUD'
    },
    'country': {
      'uuid': 'AU'
    },
    'tax': {
      'code': 'GST'
    },
    'account_name': 'BIG Co.',
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'phone': '03 9597 8898',
    'email': 'biggie@bigco.net',
    'currency_code': 'AUD',
    'address': '1 Swans St',
    'address_2': '',
    'city': 'Melbourne',
    'state': 'Vic',
    'postcode': '3000',
    'state': 'Victoria',
    'terms': '14',
    'tax_exempt': false
  },
  'subscription': {
    'account' : {
      'code': 'BIG001'
    },
    'product': {
      'code':'BG_VOIP_GLD'
    },
    'trial_days': 10,
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_PS'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 1
    }],
    'coupon_code': '15OFFGOLD',
    'quantity': 3,
    'po_number': 'PO6767',
    'payment_method': {
      'first_name' : 'Biggie',
      'last_name' : 'Smalls',
      'company' : 'Biggie Smalls Co.',
      'phone' : '040000000',
      'company_number' : '51 824 753 556',
      'address' : '1 Smith St',
      'address_2' : '',
      'city' : 'Mont Albert',
      'postcode' : '3145',
      'country': {
        'uuid': 'AU'
      },
      'state' : 'Victoria',
      'type' : 'CREDIT_CARD',
      'card' : '4242424242424242',
      'card_month' : '12',
      'card_year' : '2017',
      'card_cvv' : '121',
      'gateway' : 'STRIPE'
    },
    'future_start_date': '2017-09-14T00:00:00+00:00'
  }
}

response = requests.post('http://api.billby.com/v2/accounts/signup', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "account" => [
    "code" => "BIG001",
    "currency" => [
      "uuid" => "AUD"
    ],
    "country" => [
      "uuid": "AU"
    ],
    "tax" => [
      "code" => "GST"
    ],
    "account_name" => "BIG Co.",
    "first_name" => "Biggie",
    "last_name" => "Smalls",
    "phone" => "03 9597 8898",
    "email" => "biggie@bigco.net",
    "currency_code" => "AUD",
    "address" => "1 Swans St",
    "address_2" => "",
    "city" => "Melbourne",
    "state" => "Vic",
    "postcode" => "3000",
    "state" => "Victoria",
    "terms" => "14",
    "tax_exempt" => false
  ],
  "subscription" => [
    "account" => [
      "code" => "BIG001"
    ],
    "product" => [
      "code" => "BG_VOIP_GLD"
    ],
    "trial_days" => 10,
    "subscription_add_ons" => [[
      "add_on" => [
        "code" => "BG_PS"
      ],
      "coupon_code" => "10OFFWINTER",
      "quantity" => 1
    ]],
    "coupon_code" => "15OFFGOLD",
    "quantity" => 3,
    "po_number" => "PO6767",
    "payment_method" => [
      "first_name" => "Biggie",
      "last_name" => "Smalls",
      "company" => "Biggie Smalls Co.",
      "phone" => "040000000",
      "company_number" => "51 824 753 556",
      "address" => "1 Smith St",
      "address_2" => "",
      "city" => "Mont Albert",
      "postcode" => "3145",
      "country" => [
          "uuid" => "AU"
      ],
      "state" => "Victoria",
      "type" => "CREDIT_CARD",
      "card" => "4242424242424242",
      "card_month" => "12",
      "card_year" => "2017",
      "card_cvv" => "121",
      "gateway" => "STRIPE"
    ],
    "future_start_date" => "2017-09-14T00:00:00+00:00"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://api.billby.com/v2/accounts/signup');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("http://api.billby.com/v2/accounts/signup");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'account': {
    'code': 'BIG001',
    'currency': {
      'uuid': 'AUD'
    },
    'country': {
      'uuid': 'AU'
    },
    'tax': {
      'code': 'GST'
    },
    'account_name': 'BIG Co.',
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'phone': '03 9597 8898',
    'email': 'biggie@bigco.net',
    'currency_code': 'AUD',
    'address': '1 Swans St',
    'address_2': '',
    'city': 'Melbourne',
    'state': 'Vic',
    'postcode': '3000',
    'country': {
      'uuid': 'AU'
    },
    'state': 'Victoria',
    'terms': '14',
    'tax_exempt': false
  },
  'subscription': {
    'account' : {
      'code': 'BIG001'
    },
    'product': {
      'code':'BG_VOIP_GLD'
    },
    'trial_days': 10,
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_PS'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 1
    }],
    'coupon_code': '15OFFGOLD',
    'quantity': 3,
    'po_number': 'PO6767',
    'payment_method': {
      'first_name' : 'Biggie',
      'last_name' : 'Smalls',
      'company' : 'Biggie Smalls Co.',
      'phone' : '040000000',
      'company_number' : '51 824 753 556',
      'address' : '1 Smith St',
      'address_2' : '',
      'city' : 'Mont Albert',
      'postcode' : '3145',
      'country': {
        'uuid': 'AU'
      },
      'state' : 'Victoria',
      'type' : 'CREDIT_CARD',
      'card' : '4242424242424242',
      'card_month' : '12',
      'card_year' : '2017',
      'card_cvv' : '121',
      'gateway' : 'STRIPE'
    },
    'future_start_date': '2017-09-05T00:00:00+00:00'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body (returns the subscription)

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": "2017-12-15T00:00:00+00:00",
        "status": "PENDING"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 0,
      "component_tax_amount": 1.8181,
      "component_total_amount": 20.0000,
      "status": "ACTIVE",
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-14T23:56:54+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": "2017-12-15T00:00:00+00:00",
      "status": "PENDING"
    }],
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 0,
    "component_tax_amount": 10.9091,
    "component_total_amount": 120.0000,
    "total_amount": 140.0000,
    "setup_fee": 70.0000,
    "status": "PAYING",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "trial_start_date": "2017-09-05T00:00:00+00:00",
    "trial_end_date": "2017-09-15T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "2017-09-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint creates a new account with a subscription in one request.

Note, the response returns the subscription, not the account.

HTTP Request

POST http://api.billby.com/v2/accounts/signup

Body Parameters

See Create Account body parameters and Create Subscription body parameters for required parameters.

Close Account

DELETE https://api.billby.com/v2/accounts/<code>/close

curl "https://api.billby.com/v2/accounts/BIG001/close"
  -X DELETE
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts/BIG001/close")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.delete('https://api.billby.com/v2/accounts/BIG001/close', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts/BIG001/close');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts/BIG001/close");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestMethod("DELETE");
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "code": "BIG001",
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "country": {
      "uuid": "AU",
      "href": "https://api.billby.com/v2/countries/AU"
    },
    "tax": {
      "code": "GST",
      "href": "https://api.billby.com/v2/taxes/GST"
    },
    "account_name": "BIG Co.",
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "email": "biggie@bigco.net",
    "phone": "03 9597 8898",
    "address": "1 Swans St",
    "address_2": "",
    "city": "Melbourne",
    "state": "Vic",
    "postcode": "3000",
    "terms": 0,
    "tax_exempt": false,
    "gateway": "STRIPE",
    "status": "CLOSED",
    "email_reminder": true,
    "email_invoice_new": true,
    "email_invoice_overdue": true,
    "email_payment_confirmed": true,
    "email_payment_failed": true,
    "email_payment_voided": true,
    "email_refund": true,
    "pages_update_account": true,
    "pages_subscribe": true,
    "pages_update_subscription": true,
    "pages_update_payment_method": true,
    "pages_view_invoices": true,
    "pages_make_payment": true,
    "created_at": "2017-09-06T12:12:46+00:00",
    "updated_at": "2017-09-11T14:12:46+00:00",
    "href": "https://api.billby.com/v2/accounts/BIG001"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint closes an account. Note, you may only close accounts that have no live subscriptions. To close an account with live subscriptions, you must first terminate the subscriptions.

HTTP Request

DELETE https://api.billby.com/v2/accounts/<code>/close

URI Parameters

Parameter Description
code The unique account code of the account to close

Re-Open Account

PUT https://api.billby.com/v2/accounts/<code>/reopen

curl "https://api.billby.com/v2/accounts/BIG001/reopen"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/accounts/BIG001/reopen")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

response = requests.put('https://api.billby.com/v2/accounts/BIG001/reopen', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/accounts/BIG001/reopen');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/accounts/BIG001/reopen");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestMethod("PUT");
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "code": "BIG001",
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "country": {
      "uuid": "AU",
      "href": "https://api.billby.com/v2/countries/AU"
    },
    "tax": {
      "code": "GST",
      "href": "https://api.billby.com/v2/taxes/GST"
    },
    "account_name": "BIG Co.",
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "email": "biggie@bigco.net",
    "phone": "03 9597 8898",
    "address": "1 Swans St",
    "address_2": "",
    "city": "Melbourne",
    "state": "Vic",
    "postcode": "3000",
    "terms": 0,
    "tax_exempt": false,
    "gateway": "STRIPE",
    "status": "OPEN",
    "email_reminder": true,
    "email_invoice_new": true,
    "email_invoice_overdue": true,
    "email_payment_confirmed": true,
    "email_payment_failed": true,
    "email_payment_voided": true,
    "email_refund": true,
    "pages_update_account": true,
    "pages_subscribe": true,
    "pages_update_subscription": true,
    "pages_update_payment_method": true,
    "pages_view_invoices": true,
    "pages_make_payment": true,
    "created_at": "2017-09-06T12:12:46+00:00",
    "updated_at": "2017-10-07T14:15:22+00:00",
    "href": "https://api.billby.com/v2/accounts/BIG001"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint re-opens a closed account. Note, the request includes an empty body.

HTTP Request

PUT https://api.billby.com/v2/accounts/<code>/re-open

URI Parameters

Parameter Description
code The unique code of the account to re-open

Activities

Overview

Activities represent logged account and subscription events.

URL https://api.billby.com/v2/activities
Methods GET

List Activities

GET https://api.billby.com/v2/activities

curl "https://api.billby.com/v2/activities"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/activities")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/activities', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/activities');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/activities");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "activities": [
      {
        "account": {
          "code": "BIG001",
          "href": "http://api.billby.com.local/v2/accounts/BIG001"
        },
        "subscription": null,
        "subscription_add_on": null,
        "user": null,
        "type": "ACCOUNT_NEW",
        "description": "Account created",
        "subscription_status": null,
        "subscription_add_on_status": null,
        "quantity_change": null,
        "created_at": "2017-08-28T06:04:15+00:00"
      },
      {
        "account": {
          "code": "BIG001",
          "href": "http://api.billby.com.local/v2/accounts/BIG001"
        },
        "subscription": {
          "uuid": "1724baeb2328de20c63f54e6c411e761",
          "href": "http://api.billby.com.local/v2/subscriptions/1724baeb2328de20c63f54e6c411e761"
        },
        "subscription_add_on": null,
        "user": "Hosted Pages",
        "type": "SUBSCRIPTION_NEW",
        "description": "Monthly paying subscription added",
        "subscription_status": "PAYING",
        "subscription_add_on_status": null,
        "quantity_change": 2,
        "created_at": "2017-08-31T00:19:53+00:00"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/activities?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/activities?page=1"
      }
    },
    "_meta": {
      "total_count": 2,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all activities.

HTTP Request

GET https://api.billby.com/v2/activities

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
date_from - Filter the results by a range, returning activities from this date
date_to - Filter the results by a range, returning activities to this date
account_code - Filter the results by account using the account's code
subscription_uuid - Filter the results by subscription using the subscription's uuid
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
account Nested account reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
subscription Nested subscription reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
subscription_add_on Nested subscription add-on reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
user User full name string
type Type of activity. See Activity Types string
description Description string
subscription_status Status of description at time of event string
subscription_add_on_status Status of subscription add-on at time of event string
quantity_change Change in quantity on the component (including creation and cancellation) double
created_at Date resource created datetime

Sortable attribute
Expandable nested attribute

Activity Types

Activities are one of the following types:

Add-Ons

Overview

An add-on represent additional components that may be added to subscriptions and represent upsold features or additional line items that are charged alongside the subscription.

URL https://api.billby.com/v2/add-ons
Methods GET

List Add-Ons

GET https://api.billby.com/v2/add-ons

curl "https://api.billby.com/v2/add-ons"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/add-ons")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/add-ons', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/add-ons');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/add-ons");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "add_ons": [
      {
        "code": "BG_PS",
        "billing_cycle": {
          "code": "MONTHLY",
          "href": "http://api.billby.com/v2/billing-cycle/MONTHLY"
        },
        "is_digital": false,
        "is_deleted": false,
        "accounting_code": "200",
        "name": "Platinum Support",
        "invoice_name": "Platinum Support",
        "description": "",
        "uom": "User",
        "repeat": null,
        "includes_tax": false,
        "price_model": "PER_UNIT",
        "price_array": {
          "AUD": [
            20.0000
          ],
          "GBP": [
            12.0000
          ]
        },
        "created_at": "2017-08-24T01:22:19+00:00",
        "updated_at": "2017-08-24T01:22:19+00:00",
        "href": "http://api.billby.com/v2/add-on/BG_PS"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/add-ons?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/add-ons?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all add-ons.

HTTP Request

GET https://api.billby.com/v2/add-ons

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
code Unique identifier code string(50)
billing_cycle Nested billing cycle reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
is_digital Digital add-on boolean
is_deleted Whether deleted boolean
accounting_code Accounting code for syncing to accounting package string (100)
name Add-on name string
invoice_name Add-on invoice name string
description Add-on description string
uom Unit of measure string
repeat Number of billing cycles add-on persists integer
includes_tax Whether price_array is tax inclusive boolean
price_model Price model, 'FLAT_FEE', 'PER_UNIT', 'VOLUME', 'TIERED', 'STAIRSTEP' string
price_array Represents pricing of the add-on as json representation array
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

See Subscription Price Array. Add-On price arrays are further indexed by currency.
Sortable attribute
Expandable nested attribute

Lookup Add-On

GET https://api.billby.com/v2/add-ons/<code>

curl "https://api.billby.com/v2/add-ons/BG_PS"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/add-ons/BG_PS")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/add-ons/BG_PS', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/add-ons/BG_PS');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/add-ons/BG_PS");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    {
      "code": "BG_PS",
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "http://api.billby.com/v2/billing-cycle/MONTHLY"
      },
      "is_digital": false,
      "is_deleted": false,
      "accounting_code": "200",
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "uom": "User",
      "repeat": null,
      "includes_tax": false,
      "price_model": "PER_UNIT",
      "price_array": {
        "AUD": [
          20.0000
        ],
        "GBP": [
          12.0000
        ]
      },
      "created_at": "2017-08-24T01:22:19+00:00",
      "updated_at": "2017-08-24T01:22:19+00:00",
      "href": "http://api.billby.com/v2/add-on/BG_PS"
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific add-on.

HTTP Request

GET https://api.billby.com/v2/add-ons/<code>

URI Parameters

Parameter Description
code The unique add-on code of the add-on to retrieve

Response Body Parameters

See List Add-Ons response body parameters

Billing Cycles

Overview

Billing Cycles represent a renewing period for billing.

URL https://api.billby.com/v2/billing-cycles
Methods GET

List Billing Cycles

GET https://api.billby.com/v2/billing-cycles

curl "https://api.billby.com/v2/billing-cycles"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/billing-cycles")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/billing-cycles', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/billing-cycles');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/billing-cycles");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "billing_cycles": [
      {
        "code": "MONTHLY",
        "is_deleted": false,
        "name": "Monthly",
        "period": "MONTH",
        "frequency": 1,
        "reminder_days": null,
        "created_at": "2017-04-03T05:59:06+00:00",
        "updated_at": "2017-04-03T05:59:06+00:00",
        "href": "http://api.billby.com/v2/billing-cycle/MONTHLY"
      },
      {
        "code": "ANNUALLY",
        "is_deleted": false,
        "name": "Annually",
        "period": "YEAR",
        "frequency": 1,
        "reminder_days": 15,
        "created_at": "2017-04-03T05:59:06+00:00",
        "updated_at": "2017-04-03T05:59:06+00:00",
        "href": "http://api.billby.com/v2/billing-cycle/ANNUALLY"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/billing-cycles?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/billing-cycles?page=1"
      }
    },
    "_meta": {
      "total_count": 2,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all billing cycles.

HTTP Request

GET https://api.billby.com/v2/billing-cycles

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
sort - Sort the results by sortable attribute

Response Body Parameters

Parameter Description Type         
code Unique identifier code string(50)
name Name string (50)
period The period unit, 'DAY', 'WEEK', 'MONTH', 'ANNUAL' string
frequency The number of billing periods in a cycle integer
reminder_days Number of days to send reminder before invoice integer
is_deleted Whether deleted boolean
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

Lookup Billing Cycle

GET https://api.billby.com/v2/billing-cycles/<code>

curl "https://api.billby.com/v2/billing-cycles/MONTHLY"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/billing-cycles/MONTHLY")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/billing-cycles/MONTHLY', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/billing-cycles/MONTHLY');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/billing-cycles/MONTHLY");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "code": "MONTHLY",
    "is_deleted": false,
    "name": "Monthly",
    "period": "MONTH",
    "frequency": 1,
    "reminder_days": null,
    "created_at": "2017-04-03T05:59:06+00:00",
    "updated_at": "2017-04-03T05:59:06+00:00",
    "href": "http://api.billby.com/v2/billing-cycle/MONTHLY"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific billing cycle.

HTTP Request

GET https://api.billby.com/v2/billing-cycles/<code>

URI Parameters

Parameter Description
code The unique billing cycle code of the billing cycle to retrieve

Response Body Parameters

See List Billing Cycles response body parameters

Countries

Overview

Countries are used throughout the API.

URL https://api.billby.com/v2/countries
Methods GET

List Countries

GET https://api.billby.com/v2/countries

curl "https://api.billby.com/v2/countries"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/countries")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/countries', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/countries');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/countries");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "countries": [
      {
        "uuid": "AD",
        "name": "Andorra",
        "states": null,
        "href": "http://api.billby.com/v2/country/AD"
      },
      {
        "uuid": "AE",
        "name": "United Arab Emirates",
        "states": [
          "'Ajman",
          "Abu Zaby (Abu Dhabi)",
          "Al Fujayrah",
          "Ash Shariqah (Sharjah)",
          "Dubayy (Dubai)",
          "Ra's al Khaymah",
          "Umm al Qaywayn"
        ],
        "href": "http://api.billby.com/v2/country/AE"
      },
      {
        "uuid": "AF",
        "name": "Afghanistan",
        "states": [
          "Badakhshan",
          "Badghis",
          "Baghlan",
          "Balkh",
          "Bamian",
          "Farah",
          "Faryab",
          "Ghazni",
          "Ghowr",
          "Helmand",
          "Herat",
          "Jowzjan",
          "Kabol",
          "Kandahar",
          "Kapisa",
          "Konar",
          "Kondoz",
          "Laghman",
          "Lowgar",
          "Nangarhar",
          "Nimruz",
          "Oruzgan",
          "Paktia",
          "Paktika",
          "Parvan",
          "Samangan",
          "Sar-e Pol",
          "Takhar",
          "Vardak",
          "Zabol"
        ],
        "href": "http://api.billby.com/v2/country/AF"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/countries?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/countries?page=1"
      }
    },
    "_meta": {
      "total_count": 5,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all countries.

HTTP Request

GET https://api.billby.com/v2/countries

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
sort - Sort the results by sortable attribute

Response Body Parameters

Parameter Description Type         
uuid Unique identifier string(50)
name Name string
states Array of states/regions/provinces. array
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

Lookup Country

GET https://api.billby.com/v2/countries/<uuid>

curl "https://api.billby.com/v2/countries/AU"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/countries/AU")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/countries/AU', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/countries/AU');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/countries/AU");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "AU",
    "name": "Australia",
    "states": [
      "Australian Capital Territory",
      "New South Wales",
      "Northern Territory",
      "Queensland",
      "South Australia",
      "Tasmania",
      "Victoria",
      "Western Australia"
    ],
    "href": "http://api.billby.com/v2/country/AU"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific country.

HTTP Request

GET https://api.billby.com/v2/countries/&lt;uuid&gt;

URI Parameters

Parameter Description
uuid The unique identifer of the country to retrieve

Response Body Parameters

See List Countries response body parameters

Coupons

Overview

Coupons represent available discounts that can be redeemed on subscriptions.

URL https://api.billby.com/v2/coupons
Methods GET

List Coupons

GET https://api.billby.com/v2/coupons

curl "https://api.billby.com/v2/coupons"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/coupons")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/coupons', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/coupons');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/coupons");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "coupons": [
      {
        "code": "10OFFWINTER",
        "currency": null,
        "name": "Winter Discount 10% (Monthly)",
        "invoice_name": "Winter Discount 10%",
        "type": "PERCENTAGE",
        "discount_value": "10.0000",
        "for_all" : false,
        "products": [
          "BG_VOIP_GLD",
          "BG_VOIP"
        ],
        "add_ons": [
          "BG_SU",
          "BG_PS"
        ],
        "duration": null,
        "expiry": "2020-12-31T09:59:59+00:00",
        "max_redemption": null,
        "is_pages": true,
        "status": "ACTIVE",
        "created_at": "2017-02-14T23:56:54+00:00",
        "updated_at": "2017-02-14T23:56:54+00:00",
        "href": "http://api.billby.com/v2/coupon/10OFFWINTER"
      },
      {
        "code": "15OFFGOLD",
        "currency": null,

        "name": "Discount 15% (Monthly)",
        "invoice_name": "Gold Discount",
        "type": "PERCENTAGE",
        "discount_value": "15.0000",
        "for_all" : false,
        "products": [
          "BG_VOIP_GLD",
          "BG_VOIP"
        ],
        "add_ons": [
          "BG_SU",
          "BG_PS"
        ],
        "duration": null,
        "expiry": "2020-12-31T09:59:59+00:00",
        "max_redemption": null,
        "is_pages": true,
        "status": "ACTIVE",
        "created_at": "2017-02-14T23:56:54+00:00",
        "updated_at": "2017-02-14T23:56:54+00:00",
        "href": "http://api.billby.com/v2/coupon/15OFFGOLD"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/coupons?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/coupons?page=1"
      }
    },
    "_meta": {
      "total_count": 2,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all coupons.

HTTP Request

GET https://api.billby.com/v2/coupons

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
code Unique identifier code string(50)
currency Nested currency reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
name Name string
invoice_name Invoice name string
type Type of discount, ie 'PERCENTAGE' string
discount_value Value of discount double
for_all Whether coupon is eligible for all products and add-ons boolean
products Product codes of eligible products array
add_ons Add-on codes of eligible add-ons array
duration Number of cycles that the coupon will be in effect. If null, forever integer
expiry Coupon expiry; coupon will no longer be available after this date datetime
max_redemption Max no. redemption of the coupons across subscriptions integer
is_pages Whether this coupon can be redeemed by hosted page users boolean
status Coupon status, 'DISABLED', 'ACTIVE', 'EXPIRED' string
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

Lookup Coupon

GET https://api.billby.com/v2/coupons/<code>

curl "https://api.billby.com/v2/coupons/10OFFWINTER"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/coupons/10OFFWINTER")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/coupons/10OFFWINTER', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/coupons/10OFFWINTER');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/coupons/10OFFWINTER");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "code": "10OFFWINTER",
    "currency": null,
    "name": "Winter Discount 10% (Monthly)",
    "invoice_name": "Winter Discount 10%",
    "type": "PERCENTAGE",
    "discount_value": "10.0000",
    "for_all": false,
    "products": [
      "BG_VOIP_GLD",
      "BG_VOIP"
    ],
    "add_ons": [
      "BG_SU",
      "BG_PS"
    ],
    "duration": null,
    "expiry": "2020-12-31T09:59:59+00:00",
    "max_redemption": null,
    "is_pages": true,
    "status": "ACTIVE",
    "created_at": "2017-02-14T23:56:54+00:00",
    "updated_at": "2017-02-14T23:56:54+00:00",
    "href": "http://api.billby.com/v2/coupon/10OFFWINTER"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific coupon.

HTTP Request

GET https://api.billby.com/v2/coupons/<code>

URI Parameters

Parameter Description
code The unique coupon code of the coupon to retrieve

Response Body Parameters

See List Coupons response body parameters

Currencies

Overview

Currencies are used throughout the API.

URL https://api.billby.com/v2/currencies
Methods GET

List Currencies

GET https://api.billby.com/v2/currencies

curl "https://api.billby.com/v2/currencies"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/currencies")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/currencies', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/currencies');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/currencies");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "currencies": [
      {
        "uuid": "AUD",
        "is_enabled": true,
        "name": "Australia Dollar",
        "sign": "$",
        "href": "http://api.billby.com/v2/currency/AUD"
      },
      {
        "uuid": "GBP",
        "is_enabled": true,
        "name": "United Kingdom Pound",
        "sign": "£",
        "href": "http://api.billby.com/v2/currency/GBP"
      },
      {
        "uuid": "USD",
        "is_enabled": false,
        "name": "United States Dollar",
        "sign": "$",
        "href": "http://api.billby.com/v2/currency/USD"
      }
    ],
    "_links": {
      "self": {
        "href": "http://api.billby.com/v2/currencies?page=1"
      }
    },
    "_meta": {
      "total_count": 3,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all currencies.

HTTP Request

GET https://api.billby.com/v2/currencies

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
sort - Sort the results by sortable attribute

Response Body Parameters

Parameter Description Type         
uuid Unique identifier string(50)
is_enabled Whether enabled boolean
name Name string
sign The currency symbol string
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

Lookup Currency

GET https://api.billby.com/v2/currencies/<uuid>

curl "https://api.billby.com/v2/currencies/AUD"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/currencies/AUD")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/currencies/AUD', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/currencies/AUD');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/currencies/AUD");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "AUD",
    "is_enabled": true,
    "name": "Australia Dollar",
    "sign": "$",
    "href": "http://api.billby.com/v2/currency/AUD"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific currency.

HTTP Request

GET https://api.billby.com/v2/currencies/&lt;uuid&gt;

URI Parameters

Parameter Description
uuid The uid of the currency to retrieve

Response Body Parameters

See List Currencies response body parameters

Invoices

Overview

Invoices represent an itemised bill for subscription and manual charges and credits, the total charge, and the terms.

URL https://api.billby.com/v2/invoices
Methods GET PUT

List Invoices

GET https://api.billby.com/v2/invoices

curl "https://api.billby.com/v2/invoices"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/invoices")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/invoices', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/invoices');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/invoices");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "invoices": [
      {
        "uuid": "11e78229299ea044747400b547c08759",
        "account": {
          "code": "BIG001",
          "href": "http://api.billby.com/v2/account/BIG001"
        },
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
        },
        "currency": {
          "uuid": "AUD",
          "href": "https://api.billby.com/v2/currency/AUD"
        },
        "payment_method": {
          "description": "Manual Payment",
          "type": "MANUAL",
          "gateway": "STRIPE",
          "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
        },
        "invoice_number": "19323",
        "po_number": null,
        "terms": 14,
        "amount_base": 129.09,
        "amount_discount": 0,
        "amount_subtotal": 129.09,
        "amount_tax": 12.91,
        "amount_total": 142,
        "amount_paid": 0,
        "amount_due": 142,
        "status": "OPEN",
        "refund_to": null,
        "line_items": [
          {
            "subscription": {
              "uuid": "6792edeef7c511e68e520299a9bf9b51",
              "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
            },
            "subscription_add_on": null,
            "type": "CHARGE",
            "amount_base": 109.09,
            "amount_discount": 0,
            "amount_subtotal": 109.09,
            "amount_tax": 10.91,
            "amount_total": 120,
            "tax_name": "GST",
            "tax_rate": "10.0000",
            "quantity": "3.00",
            "description": "VOIP Gold Subscription",
            "accounting_code": "200",
            "start_date": "2017-08-24T01:49:31+00:00",
            "end_date": "2017-08-24T01:49:31+00:00",
            "available_date": null,
            "created_at": "2017-08-24T01:49:31+00:00",
            "updated_at": "2017-08-24T01:49:31+00:00",
            "is_refunded": false
          },
          {
            "subscription": {
              "uuid": "6792edeef7c511e68e520299a9bf9b51",
              "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
            },
            "subscription_add_on": {
              "uuid": "e7aeb0c6791b3876886e113fe6c42361",
              "href": "https://api.billby.com/v2/subscription-add-on/e7aeb0c6791b3876886e113fe6c42361"
            },
            "type": "CHARGE",
            "amount_base": 20,
            "amount_discount": 0,
            "amount_subtotal": 20,
            "amount_tax": 2,
            "amount_total": 22,
            "tax_name": "GST",
            "tax_rate": "10.0000",
            "quantity": "1.00",
            "description": "Platinum Support",
            "accounting_code": "200",
            "start_date": "2017-08-24T01:49:31+00:00",
            "end_date": "2017-08-24T01:49:31+00:00",
            "available_date": null,
            "created_at": "2017-08-24T01:49:31+00:00",
            "updated_at": "2017-08-24T01:49:31+00:00",
            "is_refunded": false
          }
        ],
        "date_due": "2017-09-07T01:49:31+00:00",
        "accounting_uri": "https://go.xero.com/organisationlogin/default.aspx?shortcode=!LS4-A&redirecturl=/AccountsReceivable/View.aspx?InvoiceID=d111c8fb-71aa-477a-9dd2-4d9253c29b2a",
        "created_at": "2017-08-24T01:49:31+00:00",
        "updated_at": "2017-08-24T01:49:31+00:00",
        "href": "https://api.billby.com/v2/invoice/11e78229299ea044747400b547c08759"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/invoices?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/invoices?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all invoices.

HTTP Request

GET https://api.billby.com/v2/invoices

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
date_from - Filter the results by a range, returning invoices from this date
date_to - Filter the results by a range, returning invoices to this date
account_code - Filter the results by account using the account's code
invoice_number - Filter the results by invoice_number
status - Filter the results by status
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
uuid Unique identifier string(50)
account Nested account reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
subscription Nested subscription reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
currency Nested currency reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
payment_method Nested payment method reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
invoice_number Invoice number string
po_number Purchase order number string
terms Terms in days integer
amount_base Amount before tax and discounts double
amount_discount Discount amount double
amount_subtotal Amount before tax after discount double
amount_tax Tax amount double
amount_total Total amount double
amount_paid Amount paid double
amount_due Amount due double
status Status, 'PENDING', 'OPEN', 'PAID', 'VOID', 'REFUNDED' string
refund_to Nested invoice reference of invoice refunded to object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
line_items Charges/Credits Collection
      subscription Nested subscription reference object
            code Unique identifier code string(50)
            href link representing the URL to the resource string
      subscription_add_on Nested subscription_add_on reference object
            code Unique identifier code string(50)
            href link representing the URL to the resource string
      type 'CHARGE' or 'CREDIT' string
      amount_base Amount before tax and discounts double
      amount_discount Discount amount double
      amount_subtotal Amount before tax after discount double
      amount_tax Tax amount double
      amount_total Total amount double
      tax_name Tax name string
      tax_rate Tax rate^ double
      quantity Quantity double
      description Description string
      accounting_code Accounting code for syncing to accounting package string(100)
      start_date Start date datetime
      end_date End date datetime
      available_date Date charge available for payment processing datetime
      is_refunded Whether charge was refunded boolean
      created_at Date resource created datetime
      updated_at Date resource updated datetime
date_due Date invoice due datetime
accounting_uri Accounting package invoice uri string
created_at Date resource created datetime
created_at Date resource created datetime
href Link representing the URL to the resource string

^ Note, actual Tax's tax rate may have changed since charge created. Charge's tax_rate parameter actual applied rate.
Sortable attribute
Expandable nested attribute

Lookup Invoice

GET https://api.billby.com/v2/invoices/<uuid>

curl "https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "11e78229299ea044747400b547c08759",
    "account": {
      "code": "BIG001",
      "href": "http://api.billby.com/v2/account/BIG001"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
    },
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currency/AUD"
    },
    "payment_method": {
      "description": "Manual Payment",
      "type": "MANUAL",
      "gateway": "STRIPE",
      "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "invoice_number": "19323",
    "po_number": null,
    "terms": 14,
    "amount_base": 129.09,
    "amount_discount": 0,
    "amount_subtotal": 129.09,
    "amount_tax": 12.91,
    "amount_total": 142,
    "amount_paid": 0,
    "amount_due": 142,
    "status": "OPEN",
    "refund_to": null,
    "line_items": [
      {
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
        },
        "subscription_add_on": null,
        "type": "CHARGE",
        "amount_base": 109.09,
        "amount_discount": 0,
        "amount_subtotal": 109.09,
        "amount_tax": 10.91,
        "amount_total": 120,
        "tax_name": "GST",
        "tax_rate": "10.0000",
        "quantity": "3.00",
        "description": "VOIP Gold Subscription",
        "accounting_code": "200",
        "start_date": "2017-08-24T01:49:31+00:00",
        "end_date": "2017-08-24T01:49:31+00:00",
        "available_date": null,
        "created_at": "2017-08-24T01:49:31+00:00",
        "updated_at": "2017-08-24T01:49:31+00:00",
        "is_refunded": false
      },
      {
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
        },
        "subscription_add_on": {
          "uuid": "e7aeb0c6791b3876886e113fe6c42361",
          "href": "https://api.billby.com/v2/subscription-add-on/e7aeb0c6791b3876886e113fe6c42361"
        },
        "type": "CHARGE",
        "amount_base": 20,
        "amount_discount": 0,
        "amount_subtotal": 20,
        "amount_tax": 2,
        "amount_total": 22,
        "tax_name": "GST",
        "tax_rate": "10.0000",
        "quantity": "1.00",
        "description": "Platinum Support",
        "accounting_code": "200",
        "start_date": "2017-08-24T01:49:31+00:00",
        "end_date": "2017-08-24T01:49:31+00:00",
        "available_date": null,
        "created_at": "2017-08-24T01:49:31+00:00",
        "updated_at": "2017-08-24T01:49:31+00:00",
        "is_refunded": false
      }
    ],
    "date_due": "2017-09-07T01:49:31+00:00",
    "accounting_uri": "https://go.xero.com/organisationlogin/default.aspx?shortcode=!LS4-A&redirecturl=/AccountsReceivable/View.aspx?InvoiceID=d111c8fb-71aa-477a-9dd2-4d9253c29b2a",
    "created_at": "2017-08-24T01:49:31+00:00",
    "updated_at": "2017-08-24T01:49:31+00:00",
    "href": "https://api.billby.com/v2/invoice/11e78229299ea044747400b547c08759"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific invoice.

HTTP Request

GET https://api.billby.com/v2/invoices/<uuid>

URI Parameters

Parameter Description
uuid The unique identifier of the invoice to retrieve

Response Body Parameters

See List Invoices response body parameters

Void Invoice

PUT https://api.billby.com/v2/invoices/<uuid>/void

curl "https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/void"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/void")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

response = requests.put('https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/void', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/void');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/void");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "11e78229299ea044747400b547c08759",
    "account": {
      "code": "BIG001",
      "href": "http://api.billby.com/v2/account/BIG001"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
    },
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currency/AUD"
    },
    "payment_method": {
      "description": "Manual Payment",
      "type": "MANUAL",
      "gateway": "STRIPE",
      "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "invoice_number": "19323",
    "po_number": null,
    "terms": 14,
    "amount_base": 129.09,
    "amount_discount": 0,
    "amount_subtotal": 129.09,
    "amount_tax": 12.91,
    "amount_total": 142,
    "amount_paid": 0,
    "amount_due": 142,
    "status": "VOID",
    "refund_to": null,
    "line_items": [
      {
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
        },
        "subscription_add_on": null,
        "type": "CHARGE",
        "amount_base": 109.09,
        "amount_discount": 0,
        "amount_subtotal": 109.09,
        "amount_tax": 10.91,
        "amount_total": 120,
        "tax_name": "GST",
        "tax_rate": "10.0000",
        "quantity": "3.00",
        "description": "VOIP Gold Subscription",
        "accounting_code": "200",
        "start_date": "2017-08-24T01:49:31+00:00",
        "end_date": "2017-08-24T01:49:31+00:00",
        "available_date": null,
        "created_at": "2017-08-24T01:49:31+00:00",
        "updated_at": "2017-08-24T01:49:31+00:00",
        "is_refunded": false
      },
      {
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51"
        },
        "subscription_add_on": {
          "uuid": "e7aeb0c6791b3876886e113fe6c42361",
          "href": "https://api.billby.com/v2/subscription-add-on/e7aeb0c6791b3876886e113fe6c42361"
        },
        "type": "CHARGE",
        "amount_base": 20,
        "amount_discount": 0,
        "amount_subtotal": 20,
        "amount_tax": 2,
        "amount_total": 22,
        "tax_name": "GST",
        "tax_rate": "10.0000",
        "quantity": "1.00",
        "description": "Platinum Support",
        "accounting_code": "200",
        "start_date": "2017-08-24T01:49:31+00:00",
        "end_date": "2017-08-24T01:49:31+00:00",
        "available_date": null,
        "created_at": "2017-08-24T01:49:31+00:00",
        "updated_at": "2017-08-24T01:49:31+00:00",
        "is_refunded": false
      }
    ],
    "date_due": "2017-09-07T01:49:31+00:00",
    "accounting_uri": "https://go.xero.com/organisationlogin/default.aspx?shortcode=!LS4-A&redirecturl=/AccountsReceivable/View.aspx?InvoiceID=d111c8fb-71aa-477a-9dd2-4d9253c29b2a",
    "created_at": "2017-08-24T01:49:31+00:00",
    "updated_at": "2017-09-26T11:42:55+00:00",
    "href": "https://api.billby.com/v2/invoice/11e78229299ea044747400b547c08759"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint voids an invoice. Only invoices without payments (successful transactions) may be voided.

HTTP Request

PUT https://api.billby.com/v2/invoices/<uuid>/void

URI Parameters

Parameter Description
uuid The uuid of the invoice to void

Body Parameters

n/a

Record Offline Payment

POST http://api.billby.com/v2/invoices/<uuid>/transactions/record-payment

curl "http://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/transactions/record-payment"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
  "transaction": {
    "type": "CREDIT_CARD",
    "amount": 1,
    "reference": "986-655",
    "date": "2017-07-28T00:02:17+00:00",
    "send_confirmation": true
  }
}'
require 'net/http'
require 'uri'

uri = URI.parse("http://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/transactions/record-payment")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  transaction: {
    type: "CREDIT_CARD",
    amount: 1,
    reference: "986-655",
    date: "2017-07-28T00:02:17+00:00",
    send_confirmation: true
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'transaction': {
    'type': 'CREDIT_CARD',
    'amount': 1,
    'reference': '986-655',
    'date': '2017-07-28T00:02:17+00:00',
    'send_confirmation': true
  }
}

response = requests.post('http://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/transactions/record-payment', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "transaction" => [
    "type" => "CREDIT_CARD",
    "amount" => 1,
    "reference" => "986-655",
    "date" => "2017-07-28T00:02:17+00:00",
    "send_confirmation" => true
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/transactions/record-payment');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("http://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759/transactions/record-payment");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'transaction': {
    'type': 'CREDIT_CARD',
    'amount': 1,
    'reference': '986-655',
    'date': '2017-07-28T00:02:17+00:00',
    'send_confirmation': true
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "uuid": "011e73ba3c91ebb903f851a59666fcbe",
    "account": {
      "code": "BIG001",
      "href": "http://api.billby.com/v2/accounts/BIG001"
    },
    "subscription": null,
    "invoice": {
      "uuid": "11e78229299ea044747400b547c08759",
      "href": "http://api.billby.com/v2/invoices/11e78229299ea044747400b547c08759"
    },
    "payment_method": null,
    "currency": {
      "uuid": "AUD",
      "href": "http://api.billby.com/v2/currencies/AUD"
    },
    "amount": 1,
    "reference": "986-655",
    "response_code": null,
    "response_message": "Offline Payment created via API",
    "status": "SUCCESS",
    "date": "2017-07-28T00:02:17+00:00",
    "type": "CREDIT_CARD",
    "gateway_transaction_token": null,
    "accounting_uri": "https://go.xero.com/organisationlogin/default.aspx?shortcode=!LS4-A&redirecturl=/Bank/ViewTransaction.aspx?bankTransactionID=d111c8fb-71aa-477a-9dd2-4d9253c29b2a",
    "created_at": "2017-09-05T02:17:21+00:00",
    "href": "http://api.billby.com/v2/transactions/011e73ba3c91ebb903f851a59666fcbe"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint records an offline payment on an invoice. A transaction will be created, but no payment will be processed. See Body Parameters for required parameters.

HTTP Request

POST http://api.billby.com/v2/invoices/<uuid>/transactions/record-payment

URI Parameters

Parameter Description
uuid The uuid of the invoice to record payment towards

Body Parameters

Parameter Description Type Required
type The payment method type, 'BANK', 'CREDIT_CARD', 'CHECK', 'EFT', 'MANUAL', 'MONEY_ORDER', 'OTHER', 'GATEWAY_TOKEN', 'PAYPAL' string
amount The amount double
reference A reference, e.g. cheque or receipt number double
date Date of transaction datetime
send_confirmation Whether to send confirmation email (invoice) boolean

Payment Methods

Overview

Payment Methods describe a subscription's method of payment and hold associated billing details. Payment methods belong to a subscription, and a subscription can only have one payment method.

URL https://api.billby.com/v2/subscriptions/<uuid>/payment-method
Methods GET POST PUT

Lookup Payment Method

GET https://api.billby.com/v2/subscriptions/<uuid>/payment-method

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "company": "Company",
    "company_number": "51 824 753 556",
    "address": "1 Smith St",
    "address_2": "",
    "city": "Mont Albert",
    "state": "Victoria",
    "postcode": "3145",
    "country": {
      "uuid": "AU",
      "href": "http://api.billby.com/v2/countries/AU"
    },
    "phone": "040000000",
    "email": "accounts@bigco.net"
    "brand": "VISA",
    "is_deleted": false,
    "description": "Visa ••••4242 Exp. 12/17",
    "type": "CREDIT_CARD",
    "card_mask": "••••4242",
    "card_month": 12,
    "card_year": 2017,
    "gateway_token": "cus_BIdQIOWp1dXIlK",
    "gateway": "STRIPE",
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "http://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "created_at": "2017-08-29T05:20:33+00:00",
    "updated_at": "2017-08-29T05:22:17+00:00",
    "href": "http://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves the subscription's payment method.

HTTP Request

GET https://api.billby.com/v2/subscriptions/<uuid>/payment-method

URI Parameters

Parameter Description
uuid The uuid of the subscription

Response Body Parameters

Parameter Description Type
first_name Contact first name string(40)
last_name Contact last name string(40)
full_name Contact full name string(80)
company Company name string(80)
company_number Company number string(80)
address First line of address string(100)
address_2 Second line of address string(100)
city Address city/town/suburb string(40)
state Address state/region/province string(40)
postcode Address postcode string(10)
country Nested country reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
phone Phone number string(40)
email Email address for invoices string(40)
brand Card brand string(40)
is_deleted Whether deleted boolean
description Description string(40)
type Payment method type. 'CREDIT_CARD', 'MANUAL', 'GATEWAY_TOKEN' string
card_mask Card mask string
card_month Card expiry month integer
card_year Card expiry year integer
gateway_token Payment gateway token string(40)
gateway The associated payment gateway string(40)
subscription Nested subscription reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

Add Payment Method

POST https://api.billby.com/v2/subscriptions/<uuid>/payment-method

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "payment_method": {
      "first_name": "Biggie",
      "last_name": "Smalls",
      "company": "Biggie Smalls Co.",
      "phone": "040000000",
      "company_number": "51 824 753 556",
      "address": "1 Smith St",
      "address_2": "",
      "city": "Mont Albert",
      "postcode": "3145",
      "country": {
        "uuid": "AU"
      },
      "state": "Victoria",
      "type": "CREDIT_CARD",
      "card": "4242424242424242",
      "card_month": "12",
      "card_year": "2017",
      "card_cvv": "121",
      "gateway": "STRIPE"
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  payment_method: {
      first_name: "Biggie",
      last_name: "Smalls",
      company: "Biggie Smalls Co.",
      phone: "040000000",
      company_number: "51 824 753 556",
      address: "1 Smith St",
      address_2: "",
      city: "Mont Albert",
      postcode: "3145",
      country: {
        uuid: "AU"
      }, 
      state: "Victoria",
      type: "CREDIT_CARD",
      card: "4242424242424242",
      card_month: "12",
      card_year: "2017",
      card_cvv: "121",
      gateway: "STRIPE"
    }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'payment_method': {
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'company': 'Biggie Smalls Co.',
    'phone': '040000000',
    'company_number': '51 824 753 556',
    'address': '1 Smith St',
    'address_2': '',
    'city': 'Mont Albert',
    'postcode': '3145',
    'country': {
      'uuid': 'AU'
    },
    'state': 'Victoria',
    'type': 'CREDIT_CARD',
    'card': '4242424242424242',
    'card_month': '12',
    'card_year': '2017',
    'card_cvv': '121',
    'gateway': 'STRIPE'
  }
}

response = requests.post('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "payment_method" => [
    "first_name" => "Biggie",
    "last_name" => "Smalls",
    "company" => "Biggie Smalls Co.",
    "phone" => "040000000",
    "company_number" => "51 824 753 556",
    "address" => "1 Smith St",
    "address_2" => "",
    "city" => "Mont Albert",
    "postcode" => "3145",
    "country" => [
      "uuid" => "AU"
    ],
    "state" => "Victoria",
    "type" => "CREDIT_CARD",
    "card" => "4242424242424242",
    "card_month" => "12",
    "card_year" => "2017",
    "card_cvv" => "121",
    "gateway" => "STRIPE"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'payment_method': {
    'first_name': 'Biggie',
    'last_name': 'Smalls',
    'company': 'Biggie Smalls Co.',
    'phone': '040000000',
    'company_number': '51 824 753 556',
    'address': '1 Smith St',
    'address_2': '',
    'city': 'Mont Albert',
    'postcode': '3145',
    'country': {
      'uuid': 'AU'
    },
    'state': 'Victoria',
    'type': 'CREDIT_CARD',
    'card': '4242424242424242',
    'card_month': '12',
    'card_year': '2017',
    'card_cvv': '121',
    'gateway': 'STRIPE'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "first_name": "Biggie",
    "last_name": "Smalls",
    "full_name": "Biggie Smalls",
    "company": "Company",
    "company_number": "51 824 753 556",
    "address": "1 Smith St",
    "address_2": "",
    "city": "Mont Albert",
    "state": "Victoria",
    "postcode": "3145",
    "country": {
      "uuid": "AU",
      "href": "http://api.billby.com/v2/countries/AU"
    },
    "phone": "040000000",
    "brand": "VISA",
    "is_deleted": false,
    "description": "Visa ••••4242 Exp. 12/17",
    "type": "CREDIT_CARD",
    "card_mask": "••••4242",
    "card_month": 12,
    "card_year": 2017,
    "gateway_token": "cus_BIdQIOWp1dXIlK",
    "gateway": "STRIPE",
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "http://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "created_at": "2017-08-29T05:20:33+00:00",
    "updated_at": "2017-08-29T05:22:17+00:00",
    "href": "http://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint creates a payment method on an account. You may also use this to change the subscription's payment method. If this the first payment method on a trial subscription, the subscription will be converted.

See Body Parameters for required parameters.

HTTP Request

POST https://api.billby.com/v2/subscriptions/<uuid>/payment-method

URI Parameters

Parameter Description
uuid The uuid of the subscription

Body Parameters

Parameter Description Type Required
first_name Contact first name string(40)
last_name Contact last name string(40)
company Company name string(80)
company_number Company number string(80)
address First line of address string(100)
address_2 Second line of address string(100)
city Address city/town/suburb string(40)
state Address state/region/province string(40)
postcode Address postcode string(10)
country Nested country reference object
      uuid Unique identifier string(50)
phone Phone number string(40)
type Payment method type. 'CREDIT_CARD', 'MANUAL', 'GATEWAY_TOKEN' string
card Card number string
card_month Card expiry month integer
card_year Card expiry year integer
card_cvv Card CVV number integer
gateway_token Payment gateway token string(40)
gateway The associated payment gateway. 'STRIPE', 'SECURE_PAY', 'PAYPAL', 'EWAY', or 'AUTHORIZE_NET' string
subscription Nested subscription reference object
      uuid Unique identifier string(50)

Update Payment Method

PUT https://api.billby.com/v2/subscriptions/<uuid>/payment-method

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "payment_method": {
      "first_name": "Jane",
      "last_name": "Brown"
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  payment_method: {
      first_name: "Jane",
      last_name: "Brown"
    }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'payment_method': {
    'first_name': 'Jane',
    'last_name': 'Brown',
  }
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "payment_method" => [
    "first_name" => "Jane",
    "last_name" => "Brown",
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
  'payment_method': {
    'first_name': 'Jane',
    'last_name': 'Brown',
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "first_name": "Jane",
    "last_name": "Brown",
    "full_name": "Jane Brown",
    "company": "Company",
    "company_number": "51 824 753 556",
    "address": "1 Smith St",
    "address_2": "",
    "city": "Mont Albert",
    "state": "Victoria",
    "postcode": "3145",
    "country": {
      "uuid": "AU",
      "href": "http://api.billby.com/v2/countries/AU"
    },
    "phone": "040000000",
    "brand": "VISA",
    "is_deleted": false,
    "description": "Visa ••••4242 Exp. 12/17",
    "type": "CREDIT_CARD",
    "card_mask": "••••4242",
    "card_month": 12,
    "card_year": 2017,
    "gateway_token": "cus_BIdQIOWp1dXIlK",
    "gateway": "STRIPE",
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "http://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "created_at": "2017-08-29T05:20:33+00:00",
    "updated_at": "2017-08-29T05:22:17+00:00",
    "href": "http://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/payment-method"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint updates a payment method on a subscription.

See Body Parameters for required parameters.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>/payment-method

URI Parameters

Parameter Description
uuid The uuid of the subscription

Body Parameters

Parameter Description Type Required
first_name Contact first name string(40)
last_name Contact last name string(40)
company Company name string(80)
company_number Company number string(80)
address First line of address string(100)
address_2 Second line of address string(100)
city Address city/town/suburb string(40)
state Address state/region/province string(40)
postcode Address postcode string(10)
country Nested country reference object
      uuid Unique identifier string(50)
phone Phone number string(40)
gateway_token Payment gateway token string(40)
subscription Nested subscription reference object
      uuid Unique identifier string(50)

Products

Overview

An product represents the service or plan that a customer subscribes to. They describe the product and its base prices, billing frequency and trial period.

URL https://api.billby.com/v2/products
Methods GET

List Products

GET https://api.billby.com/v2/products

curl "https://api.billby.com/v2/products"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/products")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/products', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/products');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/products");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "products": [
      {
        "code": "BG_VOIP_GLD",
        "billing_cycle": {
          "code": "MONTHLY",
          "href": "https://api.billby.com/v2/billing-cycle/MONTHLY"
        },
        "is_digital": false,
        "is_deleted": false,
        "is_pages_save_card": true,
        "accounting_code": "200",
        "accounting_code_setup_fee": "210",
        "name": "VOIP Gold (Monthly)",
        "invoice_name": "VOIP Gold Subscription",
        "description": "VOIP for Gold Members.",
        "uom": "User",
        "repeat": null,
        "trial_days": 15,
        "prorate_up": "UP_PRORATE_NOW",
        "prorate_down": "DOWN_PRORATE_NOW",
        "includes_tax": true,
        "price_model": "PER_UNIT",
        "price_array": {
          "AUD": [
            40
          ],
          "GBP": [
            25
          ]
        },
        "setup_fee": {
          "AUD": 70.0000,
          "GBP": 30.0000
        }
        "custom_fields": [
          {
            "key": "Area",
            "default_value": ""
          }
        ],
        "created_at": "2017-08-24T01:19:18+00:00",
        "updated_at": "2017-08-24T01:19:18+00:00",
        "href": "https://api.billby.com/v2/product/BG_VOIP_GLD"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/products?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/products?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all products.

HTTP Request

GET https://api.billby.com/v2/products

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
code Unique identifier code string(50)
billing_cycle Nested billing cycle reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
is_digital Digital product boolean
is_deleted Whether deleted boolean
is_pages_save_card When making payment, hosted page user's card will be automatically stored for future payments. boolean
accounting_code Accounting code for syncing to accounting package string (100)
accounting_code_setup_fee Setup fee accounting code for syncing to accounting package string (100)
name Product name string
invoice_name Product invoice name string
description Product description string
uom Unit of measure string
repeat Number of billing cycles product persists integer
trial_days Number of trial days integer
prorate_up The default upgrade proration scheme. 'UP_PRORATE_AT_RENEWAL', 'UP_PRORATE_NOW', 'UP_FULL_AT_RENEWAL', 'UP_FULL_NOW' or 'UP_NO_COST' string
prorate_down The default downgrade proration scheme. 'PRORATION_DOWN_PRORATE_NOW', 'PRORATION_DOWN_PRORATE_AT_RENEWAL' or 'PRORATION_DOWN_NO_PRORATE' string
includes_tax Whether prices are tax inclusive boolean
price_model Price model, 'FLAT_FEE', 'PER_UNIT', 'VOLUME', 'TIERED', 'STAIRSTEP' string
price_array Represents pricing of the product as json representation array
setup_fee Setup fees by currency array
custom_fields Custom fields collection
      key Key string(50)
      default_value Default value string(50)
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

See Subscription Price Array. Product price arrays are further indexed by currency.
Sortable attribute
Expandable nested attribute

Lookup Product

GET https://api.billby.com/v2/products/<code>

curl "https://api.billby.com/v2/products/BG_VOIP_GLD"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/products/BG_VOIP_GLD")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/products/BG_VOIP_GLD', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/products/BG_VOIP_GLD');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/products/BG_VOIP_GLD");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "code": "BG_VOIP_GLD",
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing-cycle/MONTHLY"
    },
    "is_digital": false,
    "is_deleted": false,
    "is_pages_save_card": true,
    "accounting_code": "200",
    "accounting_code_setup_fee": "210",
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "uom": "User",
    "repeat": null,
    "trial_days": 15,
    "prorate_up": "UP_PRORATE_NOW",
    "prorate_down": "DOWN_PRORATE_NOW",
    "includes_tax": true,
    "price_model": "PER_UNIT",
    "price_array": {
      "AUD": [
        40
      ],
      "GBP": [
        25
      ]
    },
    "setup_fee": {
      "AUD": 70.0000,
      "GBP": 30.0000
    }
    "custom_fields": [
      {
        "key": "Area",
        "default_value": ""
      }
    ],
    "created_at": "2017-08-24T01:19:18+00:00",
    "updated_at": "2017-08-24T01:19:18+00:00",
    "href": "https://api.billby.com/v2/product/BG_VOIP_GLD"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific product.

HTTP Request

GET https://api.billby.com/v2/products/<code>

URI Parameters

Parameter Description
code The unique product code of the product to retrieve

Response Body Parameters

See List Products response body parameters

Redeemed Coupons

Overview

A redeemed coupon represents a coupon as redeemed on a subscription or subscription add-on.

URL (subscription) https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons
URL (subscription add-on) https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons
Methods GET POST DELETE

List Subscription Redeemed Coupons

GET https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "redeemed_coupons": [
      {
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-10-15T11:57:53+00:00",
        "end_date": "2017-12-15T11:57:53+00:00",
        "status": "ACTIVE",
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
        },
        "created_at": "2017-06-14T23:56:54+00:00",
        "updated_at": "2017-06-14T23:56:54+00:00",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER"

      },
      {
       "coupon": {
          "code": "15OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/15OFFWINTER"
        },
        "start_date": "2017-10-15T11:57:53+00:00",
        "end_date": "2017-12-15T11:57:53+00:00",
        "status": "ACTIVE",
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
        },
        "created_at": "2017-06-14T23:56:54+00:00",
        "updated_at": "2017-06-14T23:56:54+00:00",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/15OFFWINTER"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons?page=1"
      }
    },
    "_meta": {
      "total_count": 2,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all redeemed coupons on a subscription. To retrieve the redeemed coupons on a subscription add-on see List Subscription Add-On Redeemed Coupons

HTTP Request

GET https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons

URI Parameters

Parameter Description
uuid The uuid of the subscription

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
coupon Nested coupon reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
start_date Start date datetime
end_date End date datetime
status DELETED, ACTIVE, EXPIRED, or PENDING string
subscription Nested subscription reference. object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

List Subscription Add-On Redeemed Coupons

GET https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons

curl "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "redeemed_coupons": [
      {
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-10-15T11:57:53+00:00",
        "end_date": "2017-12-15T11:57:53+00:00",
        "status": "ACTIVE",
        "subscription_add_on": {
          "uuid": "cdbad5ca8c5711e7aeb0c63fe6c42361",
          "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361"
        },
        "created_at": "2017-06-14T23:56:54+00:00",
        "updated_at": "2017-06-14T23:56:54+00:00",
        "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/10OFFWINTER"

      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons?page=1"
      }
    },
    "_meta": {
      "total_count": 2,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all redeemed coupons on a subscription add-on. To retrieve the redeemed coupons on a subscription see List Subscription Redeemed Coupons

HTTP Request

GET https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons

URI Parameters

Parameter Description
uuid The uuid of the subscription add-on

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type
coupon Nested coupon reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
start_date Start date datetime
end_date End date datetime
status DELETED, ACTIVE, EXPIRED, or PENDING string
subscription_add_on Nested subscription add-on reference. object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

Sortable attribute
Expandable nested attribute

Lookup Subscription Redeemed Coupon

GET https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons/<code>

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "coupon": {
      "code": "10OFFWINTER",
      "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
    },
    "start_date": "2017-10-15T11:57:53+00:00",
    "end_date": "2017-12-15T11:57:53+00:00",
    "status": "ACTIVE",
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00",
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a redeemed coupon on a subscription. To retrieve a redeemed coupon on a subscription add-on see Lookup Subscription Add-On Redeemed Coupon

HTTP Request

GET https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons

URI Parameters

Parameter Description
uuid The uuid of the subscription
code The coupon code of the coupon redeemed on the subscription

Response Body Parameters

See List Subscription Redeemed Coupons response body parameters

Lookup Subscription Add-On Redeemed Coupon

GET https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons/<code>

curl "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "coupon": {
      "code": "10OFFWINTER",
      "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
    },
    "start_date": "2017-10-15T11:57:53+00:00",
    "end_date": "2017-12-15T11:57:53+00:00",
    "status": "ACTIVE",
    "subscription_add_on": {
      "uuid": "cdbad5ca8c5711e7aeb0c63fe6c42361",
      "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361"
    },
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00",
    "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a redeemed coupon on a subscription add-on. To retrieve a redeemed coupon on a subscription see Lookup Subscription Redeemed Coupon

HTTP Request

GET https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons

URI Parameters

Parameter Description
uuid The uuid of the subscription add-on
code The coupon code of the coupon redeemed on the subscription add-on

Response Body Parameters

See List Subscription Add-On Redeemed Coupons response body parameters

Cancel Redeemed Coupon on Subscription

DELETE https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons/<code>

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER"
  -X DELETE
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.delete('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestMethod("DELETE");
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "coupon": {
      "code": "10OFFWINTER",
      "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
    },
    "start_date": "2017-10-15T11:57:53+00:00",
    "end_date": "2017-11-15T11:57:53+00:00",
    "status": "ACTIVE",
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-10-15T00:00:00+00:00",
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/redeemed-coupons/10OFFWINTER"

  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint cancels a redeemed coupon on a subscription. To cancel a redeemed coupon on a subscription add-on see Cancel Redeemed Coupon on Subscription Add-On

HTTP Request

DELETE https://api.billby.com/v2/subscriptions/<uuid>/redeemed-coupons/<code>

URI Parameters

Parameter Description
uuid The uuid of the subscription
code The coupon code of the coupon redeemed on the subscription.

Body Parameters

n/a

Cancel Redeemed Coupon on Subscription Add-On

DELETE https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons/<code>

curl "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/15OFFWINTER"
  -X DELETE
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.delete('https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestMethod("DELETE");
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "coupon": {
      "code": "10OFFWINTER",
      "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
    },
    "start_date": "2017-10-15T11:57:53+00:00",
    "end_date": "2017-11-15T11:57:53+00:00",
    "status": "ACTIVE",
    "subscription_add_on": {
      "uuid": "cdbad5ca8c5711e7aeb0c63fe6c42361",
      "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361"
    },
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-10-15T00:00:00+00:00",
    "href": "https://api.billby.com/v2/subscription-add-ons/cdbad5ca8c5711e7aeb0c63fe6c42361/redeemed-coupons/10OFFWINTER"

  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint cancels a redeemed coupon on a subscription add-on. To cancel a redeemed coupon on a subscription see Cancel Redeemed Coupon on Subscription

HTTP Request

DELETE https://api.billby.com/v2/subscription-add-ons/<uuid>/redeemed-coupons/<code>

URI Parameters

Parameter Description
uuid The uuid of the subscription add-on
code The coupon code of the coupon redeemed on the subscription add-on.

Body Parameters

n/a

Subscriptions

Overview

Subscriptions are created when an account signs up to a product.

URL https://api.billby.com/v2/subscriptions
Methods GET POST PUT PATCH

List Subscriptions

GET https://api.billby.com/v2/subscriptions

curl "https://api.billby.com/v2/subscriptions"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscriptions', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "account" : {
          "code": "BIG001",
          "path": "https://api.billby.com/v2/accounts/BIG001"
        },
        "product": {
          "code":"BG_VOIP_GLD",
          "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
        },
        "billing_cycle": {
          "code": "MONTHLY",
          "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
        },
        "name": "VOIP Gold (Monthly)",
        "invoice_name": "VOIP Gold Subscription",
        "description": "VOIP for Gold Members.",
        "trial_days": 30,
        "repeat": null,
        "uom": "User",
        "price_model": "PER_UNIT",
        "price_array": [
          40
        ],
        "currency": {
          "uuid": "AUD",
          "href": "https://api.billby.com/v2/currencies/AUD"
        },
        "is_digital": true,
        "includes_tax": true,
        "subscription_add_ons": [{
          "uuid": "24edec1e515d11e7a02e024d3574431f",
          "add_on": {
            "code":"BG_PS",
            "href": "https://api.billby.com/v2/add_ons/BG_PS"
          },
          "billing_cycle": {
            "code": "MONTHLY",
            "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
          },
          "subscription": {
            "uuid": "6792edeef7c511e68e520299a9bf9b51",
            "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
          },
          "name": "Platinum Support",
          "invoice_name": "Platinum Support",
          "description": "",
          "repeat": null,
          "uom": "User",
          "price_model": "PER_UNIT",
          "price_array": [
            20
          ],
          "currency": {
              "uuid": "AUD",
              "href": "http://api.billby.com/v2/currencies/AUD"
            },
          "is_digital": true,
          "includes_tax": true,
          "redeemed_coupons": [{
            "coupon": {
              "code": "10OFFWINTER",
              "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
            },
            "start_date": "2017-06-14T23:56:54+00:00",
            "end_date": "2017-09-14T23:56:54+00:00",
            "status": "ACTIVE"
          }],
          "quantity": 1,
          "component_base_amount": 18.1818,
          "component_discount_amount": 1.8182,
          "component_tax_amount": 1.636,
          "component_total_amount": 18.0000,
          "setup_fee": 0,
          "status": "ACTIVE",
          "start_date": "2017-07-30T23:36:29+00:00",
          "end_date": null,
          "is_deleted": false,
          "pending_price_change": [],
          "created_at": "2017-06-14T23:56:54+00:00",
          "updated_at": "2017-06-15T01:20:27+00:00",
          "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
        }],
        "redeemed_coupons": [{
          "coupon": {
            "code": "15OFFGOLD",
            "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
          }
          "start_date": "2017-06-14T23:56:54+00:00",
          "end_date": "2017-09-14T23:56:54+00:00",
          "status": "ACTIVE"
        }],
        "quantity": 3,
        "component_base_amount": 109.0909,
        "component_discount_amount": 16.3636,
        "component_tax_amount": 9.2727,
        "component_total_amount": 102.0000,
        "total_amount": 120.0000,
        "setup_fee": 0,
        "status": "PAYING",
        "start_date": "2017-07-30T23:36:29+00:00",
        "end_date": null,
        "trial_start_date": "2017-07-01T23:36:29+00:00",
        "trial_end_date": "2017-07-30T23:36:29+00:00",
        "suspended_date": null,
        "reminder_date": null,
        "next_billing_date": "2017-08-01T14:00:00+00:00",
        "po_number": "",
        "invoice_notes": "",
        "feedback": "",
        "satisfaction": 2,
        "cancel_reason": "",
        "suspend_reason": "",
        "cancel_date": null,
        "is_cancelled_non_payment": false,
        "is_deleted": false,
        "prebilling_terms": 0,
        "payment_method": {
          "description": "Visa 424242...242 Exp. 12/17",
          "type": "CARD",
          "gateway": "STRIPE",
          "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
        },
        "custom_fields": [
          {
            "key": "Area",
            "value": "LS1516"
          }
        ],
        "pending_price_change": [],
        "created_at": "2017-02-20T23:36:29+00:00",
        "updated_at": "2017-07-02T00:02:11+00:00"
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/subscriptions?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/subscriptions?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all subscriptions.

HTTP Request

GET https://api.billby.com/v2/subscriptions

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
product_code - Filter the results by product code
status - Filter the results by status
account_code - Filter the results by account code
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
uuid Unique identifer string
account Nested account reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
product Nested product reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
billing_cycle Nested billing cycle reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
name Product name string
invoice_name Product invoice name string
description Product description string
trial_days Trial days integer
repeat Number of billing cycles product persists integer
uom Unit of measure string
price_model Price model, 'FLAT_FEE', 'PER_UNIT', 'VOLUME', 'TIERED', 'STAIRSTEP' string
price_array Represents pricing of the product as json representation array
currency Nested currency reference object
      uuid Unique identifier string(50)
      href Link representing the URL to the resource string
is_digital Digital product boolean
includes_tax Whether price_array is tax inclusive boolean
subscription_add_ons Collection of subscription add-ons. See Subscription Add-ons collection
redeemed_coupons Collection of redeemed coupons collection
      coupon Nested coupon reference object
            code Unique identifier code string(50)
            href Link representing the URL to the resource string
      start_date Start date datetime
      end_date End date datetime
      status DELETED, ACTIVE, EXPIRED, or PENDING string
quantity Quantity double
component_base_amount The base amount for the product component double
component_discount_amount The discount amount for the product component double
component_tax_amount The tax amount for the product component double
component_total_amount The total amount for the product component double
total_amount The total amount for the whole subscription double
setup_fee The setup fee double
status IN_TRIAL, FUTURE_TRIAL, EXPIRED, PAYING, FREE, COMMITTED, SUBSCRIBED_TRIAL, SUSPENDED, NON_RENEWING, SETTLED, CANCELLED string
start_date Subscription start date (when becomes PAYING/FREE) datetime
end_date Subscription end date datetime
trial_start_date Trial start date datetime
trial_end_date Trial end date datetime
suspended_date Suspended date (most recent) datetime
next_billing_date The next billing date datetime
reminder_date Date reminder will be sent datetime
po_number Purchase Order number string
invoice_notes Invoice notes string (1000)
feedback Feedback or general notes string (1000)
satisfaction Satisfaction (1 = poor, 2 = neutral, 3 = good) integer
cancel_date Scheduled cancellation date datetime
is_cancelled_non_payment Cancelled for non-payment boolean
cancel_reason Cancellation reason string (1000)
suspend_reason Suspension reason string (1000)
is_deleted Deleted subscription boolean
prebilling_terms The prebilling terms in days integer
payment_method Nested payment method reference object
      description Description string
      type Payment method type. 'CARD', 'MANUAL', 'GATEWAY_TOKEN' string
      gateway The associated payment gateway. 'STRIPE', 'SECURE_PAY', 'PAYPAL', 'EWAY', or 'AUTHORIZE_NET' string
href Link representing the URL to the resource string
custom_fields Custom fields collection
      key Key string(50)
      value Value string(50)
pending_price_change Pending price change details array
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

^ Writable on cancel endpoint only
See Price Array
Sortable attribute
Expandable nested attribute

Price Array

For simple pricing (flat-fee or per-unit) the json represents [price], e.g. [50] represents $50 per unit.

For complex pricing (volume, tiered or stairstep), each element is an object representing a tier, with key representing upper quantity limit, and the value the associated price. The final tier may have an empty key representing no upper limit, e.g. the following shows stair step pricing:

[   {"10":50},   {"20":45},   {"30":40},   {"":35} ]

Representing:

Qty From Qty To $
1 10 50.00
11 20 45.00
21 30 40.00
31 35.00

Lookup Subscription

GET https://api.billby.com/v2/subscriptions/<uuid>

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account": {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 30,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-06-14T23:56:54+00:00",
        "end_date": "2017-09-14T23:56:54+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 1.8182,
      "component_tax_amount": 1.636,
      "component_total_amount": 18.0000,
      "status": "ACTIVE",
      "start_date": "2017-07-30T23:36:29+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-15T01:20:27+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-06-14T23:56:54+00:00",
      "end_date": "2017-09-14T23:56:54+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 3,
    "component_base_amount":109.0909,
    "component_discount_amount": 16.3636,
    "component_tax_amount": 9.2727,
    "component_total_amount": 102.0000,
    "total_amount": 120.0000,
    "setup_fee": 0,
    "status": "PAYING",
    "start_date": "2017-07-30T23:36:29+00:00",
    "end_date": null,
    "trial_start_date": "2017-07-01T23:36:29+00:00",
    "trial_end_date": "2017-07-30T23:36:29+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "2017-08-01T14:00:00+00:00",
    "po_number": "",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": 2,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-02-20T23:36:29+00:00",
    "updated_at": "2017-07-02T00:02:11+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific subscription.

HTTP Request

GET https://api.billby.com/v2/subscriptions/<uuid>

URI Parameters

Parameter Description
uuid The unique uuid of the subscription to retrieve

Response Body Parameters

See List Subscription response body parameters

Create Subscription

POST https://api.billby.com/v2/subscriptions

curl "https://api.billby.com/v2/subscriptions"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "subscription": {
      "account": {
        "code": "BIG001"
      },
      "product": {
        "code":"BG_VOIP_GLD"
      },
      "trial_days": 10,
      "subscription_add_ons": [{
        "add_on": {
          "code":"BG_PS"
        },
        "coupon_code": "10OFFWINTER",
        "quantity": 1
      }],
      "coupon_code": "15OFFGOLD",
      "quantity": 3,
      "po_number": "PO6767",
      "payment_method": {
        "first_name": "Biggie",
        "last_name": "Smalls",
        "company": "Biggie Smalls Co.",
        "phone": "040000000",
        "company_number": "51 824 753 556",
        "address": "1 Smith St",
        "address_2": "",
        "city": "Mont Albert",
        "postcode": "3145",
        "country": {
          "uuid": "AU"
        },
        "state": "Victoria",
        "type": "CREDIT_CARD",
        "card": "4242424242424242",
        "card_month": "12",
        "card_year": "2017",
        "card_cvv": "121",
        "gateway": "STRIPE"
      },
      "future_start_date": "2017-09-14T00:00:00+00:00"
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription: {
    account: {
      code: "BIG001"
    },
    product: {
      code:"BG_VOIP_GLD"
    },
    trial_days: 10,
    subscription_add_ons: [{
      add_on: {
        code:"BG_PS"
      },
      coupon_code: "10OFFWINTER",
      quantity: 1
    }],
    coupon_code: "15OFFGOLD",
    quantity: 3,
    po_number: "PO6767",
    payment_method: {
      first_name: "Biggie",
      last_name: "Smalls",
      company: "Biggie Smalls Co.",
      phone: "040000000",
      company_number: "51 824 753 556",
      address: "1 Smith St",
      address_2: "",
      city: "Mont Albert",
      postcode: "3145",
      country: {
        uuid: "AU"
      },
      state: "Victoria",
      type: "CREDIT_CARD",
      card: "4242424242424242",
      card_month: "12",
      card_year: "2017",
      card_cvv: "121",
      gateway: "STRIPE"
    },
    future_start_date: "2017-09-14T00:00:00+00:00"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription': {
    'account' : {
      'code': 'BIG001'
    },
    'product': {
      'code':'BG_VOIP_GLD'
    },
    'trial_days': 10,
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_PS'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 1
    }],
    'coupon_code': '15OFFGOLD',
    'quantity': 3,
    'po_number': 'PO6767',
    'payment_method': {
      'first_name' : 'Biggie',
      'last_name' : 'Smalls',
      'company' : 'Biggie Smalls Co.',
      'phone' : '040000000',
      'company_number' : '51 824 753 556',
      'address' : '1 Smith St',
      'address_2' : '',
      'city' : 'Mont Albert',
      'postcode' : '3145',
      'country': {
        'uuid': 'AU'
      },
      'state' : 'Victoria',
      'type' : 'CREDIT_CARD',
      'card' : '4242424242424242',
      'card_month' : '12',
      'card_year' : '2017',
      'card_cvv' : '121',
      'gateway' : 'STRIPE'
    },
    'future_start_date': '2017-09-14T00:00:00+00:00'
  }
}

response = requests.post('https://api.billby.com/v2/subscriptions', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription" => [
    "account" => [
      "code" => "BIG001"
    ],
    "product" => [
      "code" => "BG_VOIP_GLD"
    ],
    "trial_days" => 10,
    "subscription_add_ons" => [[
      "add_on" => [
        "code" => "BG_PS"
      ],
      "coupon_code" => "10OFFWINTER",
      "quantity" => 1
    ]],
    "coupon_code" => "15OFFGOLD",
    "quantity" => 3,
    "po_number" => "PO6767",
    "payment_method" => [
      "first_name" => "Biggie",
      "last_name" => "Smalls",
      "company" => "Biggie Smalls Co.",
      "phone" => "040000000",
      "company_number" => "51 824 753 556",
      "address" => "1 Smith St",
      "address_2" => "",
      "city" => "Mont Albert",
      "postcode" => "3145",
      "country": {
        "uuid": "AU"
      },
      "state" => "Victoria",
      "type" => "CREDIT_CARD",
      "card" => "4242424242424242",
      "card_month" => "12",
      "card_year" => "2017",
      "card_cvv" => "121",
      "gateway" => "STRIPE"
    ],
    "future_start_date" => "2017-09-14T00:00:00+00:00"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'subscription': {
    'account' : {
      'code': 'BIG001'
    },
    'product': {
      'code':'BG_VOIP_GLD'
    },
    'trial_days': 10,
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_PS'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 1
    }],
    'coupon_code': '15OFFGOLD',
    'quantity': 3,
    'po_number': 'PO6767',
    'payment_method': {
      'first_name' : 'Biggie',
      'last_name' : 'Smalls',
      'company' : 'Biggie Smalls Co.',
      'phone' : '040000000',
      'company_number' : '51 824 753 556',
      'address' : '1 Smith St',
      'address_2' : '',
      'city' : 'Mont Albert',
      'postcode' : '3145',
      'country': {
        'uuid': 'AU'
      },
      'state' : 'Victoria',
      'type' : 'CREDIT_CARD',
      'card' : '4242424242424242',
      'card_month' : '12',
      'card_year' : '2017',
      'card_cvv' : '121',
      'gateway' : 'STRIPE'
    },
    'future_start_date': '2017-09-05T00:00:00+00:00'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": "2017-12-15T00:00:00+00:00",
        "status": "PENDING"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 0,
      "component_tax_amount": 1.8181,
      "component_total_amount": 20.0000,
      "status": "ACTIVE",
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-14T23:56:54+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": "2017-12-15T00:00:00+00:00",
      "status": "PENDING"
    }],
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 0,
    "component_tax_amount": 10.9091,
    "component_total_amount": 120.0000,
    "total_amount": 140.0000,
    "setup_fee": 0,
    "status": "PAYING",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "trial_start_date": "2017-09-05T00:00:00+00:00",
    "trial_end_date": "2017-09-15T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "2017-09-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint creates a new subscription on an account. See Body Parameters for required parameters.

By default, the subscription will start immediately (if the subscription has a trial, it will commence now). Pass a future_start_date parameter to schedule the subscription for to start in the future. Subscriptions cannot be backdated.

HTTP Request

POST https://api.billby.com/v2/subscriptions

Body Parameters

Parameter Description Type Required
account Nested account reference object
      code Unique identifier code string(50)
product Nested product reference object
      code Unique identifier code string(50)
trial_days Trial days integer
subscription_add_ons Collection of subscription add-ons. collection
      add-on Nested add-on reference object
            code Unique identifier code string(50)
      quantity Quantity double
      coupon_code Comma delimited string of coupon codes to apply to add-on string
quantity Quantity double
coupon_code Comma delimited string of coupon codes to apply string
po_number Purchase Order number string
invoice_notes Invoice notes string (1000)
feedback Feedback or general notes string (1000)
prebilling_terms The prebilling terms in days integer
payment_method Nested payment method. See Add Subscription Payment Method object
custom_fields Collection of custom fields collection
      key Key string(50)
      value Value string(50)
future_start_date To start the subscription/trial at a future date, provide this date. This is the absolute start date (the trial, if it has one, will start on this date) datetime

Update Subscription

PUT https://api.billby.com/v2/subscriptions/<uuid>

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "subscription_add_ons": [{
        "add_on": {
          "code":"BG_SU"
        },
        "coupon_code": "10OFFWINTER",
        "quantity": 4
      },{
        "uuid": "c511e68e6792edeef7520299a9bf9b51",
        "quantity": 1
      }],
      "quantity": 4,
      "prorate_up": "UP_PRORATE_NOW"
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription: {
    uuid: "6792edeef7c511e68e520299a9bf9b51",
    subscription_add_ons: [{
      add_on: {
        code:"BG_SU"
      },
      coupon_code: "10OFFWINTER",
      quantity: 4
    },{
        uuid: "c511e68e6792edeef7520299a9bf9b51",
        quantity: 1
    }],
    quantity: 4,
    prorate_up: "UP_PRORATE_NOW"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription': {
      'uuid': '6792edeef7c511e68e520299a9bf9b51',
      'subscription_add_ons': [{
        'add_on': {
          'code':'BG_SU'
        },
        'coupon_code': '10OFFWINTER',
        'quantity': 4
      },{
        'uuid': 'c511e68e6792edeef7520299a9bf9b51',
        'quantity': 1
      }],
      'quantity': 4,
      'prorate_up': 'UP_PRORATE_NOW'
    }
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription" => [
    "uuid" => "6792edeef7c511e68e520299a9bf9b51",
    "subscription_add_ons" => [[
      "add_on" => [
        "code" => "BG_SU"
      ],
      "coupon_code" => "10OFFWINTER",
      "quantity" => 4
    ],[
      "uuid" => "c511e68e6792edeef7520299a9bf9b51",
      "quantity" => 1
    ]],
    "quantity" => 4,
    "prorate_up" => "UP_PRORATE_NOW"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
 'subscription': {
    'uuid': '6792edeef7c511e68e520299a9bf9b51',
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_SU'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 4
    },{
      'uuid': 'c511e68e6792edeef7520299a9bf9b51',
      'quantity': 1
    }],
    'quantity': 4,
    'prorate_up': 'UP_PRORATE_NOW'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "c511e68e6792edeef7520299a9bf9b51",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 0,
      "component_tax_amount": 1.8181,
      "component_total_amount": 20.0000,
      "status": "ACTIVE",
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-10-15T11:57:53+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    },{
      "uuid": "4d35724edec1e515d11e7a02e024431f",
      "add_on": {
        "code":"BG_SU",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Supercharge",
      "invoice_name": "Supercharge",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        30
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-10-15T11:57:53+00:00",
        "end_date": "2017-10-15T11:57:53+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 4,
      "component_base_amount": 109.0909,
      "component_discount_amount": 10.9091,
      "component_tax_amount": 9.8182,
      "component_total_amount": 108.0000,
      "status": "ACTIVE",
      "start_date": "2017-10-15T11:57:53+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-10-15T11:57:53+00:00",
      "updated_at": "2017-10-15T11:57:53+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/4d35724edec1e515d11e7a02e024431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": "2017-12-15T00:00:00+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 4,
    "component_base_amount": 145.4545,
    "component_discount_amount": 21.8182,
    "component_tax_amount": 12.3636,
    "component_total_amount": 136.0000,
    "total_amount": 264.0000,
    "setup_fee": 0,
    "status": "PAYING",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "trial_start_date": "2017-09-05T00:00:00+00:00",
    "trial_end_date": "2017-09-15T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "2017-09-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-10-15T11:57:53+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint updates a subscription. See Body Parameters for required parameters. To cancel, suspend, or settle, see the appropriate endpoint.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>

URI Parameters

Parameter Description
uuid The uuid of the subscription to update

Body Parameters

Parameter Description Type Required
uuid Unique identifier
trial_days Trial days. Only if subscription still in trial. integer
subscription_add_ons Collection of subscription add-ons. collection
      uuid Unique identifier. If updating an add-on, include the uuid else the add-on will be considered a new line.
      add-on Nested add-on reference. Required if a new add-on. object
            code Unique identifier code. Required if a new add-on. string(50)
      quantity Quantity double
      coupon_code Comma delimited string of coupon codes to apply to the add-on string
      status For cancelling only. 'CANCELLED' string
coupon_code Comma delimited string of coupon codes to apply string
quantity Quantity double
po_number Purchase Order number string
invoice_notes Invoice notes string (1000)
feedback Feedback or general notes string (1000)
prebilling_terms The prebilling terms in days integer
payment_method Nested payment method. See Add Subscription Payment Method object
custom_fields Collection of custom fields collection
      key Key string(50)
      value Value string(50)
prorate_up Override the default upgrade proration scheme. 'UP_PRORATE_AT_RENEWAL', 'UP_PRORATE_NOW', 'UP_FULL_AT_RENEWAL', 'UP_FULL_NOW' or 'UP_NO_COST' string
prorate_down Override the default downgrade proration scheme. 'PRORATION_DOWN_PRORATE_NOW', 'PRORATION_DOWN_PRORATE_AT_RENEWAL' or 'PRORATION_DOWN_NO_PRORATE' string

Preview New Subscription

POST https://api.billby.com/v2/subscriptions/preview

curl "https://api.billby.com/v2/subscriptions/preview"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "subscription": {
      "account": {
        "code": "BIG001"
      },
      "product": {
        "code":"BG_VOIP_GLD"
      },
      "trial_days": 10,
      "subscription_add_ons": [{
        "add_on": {
          "code":"BG_PS"
        },
        "coupon_code": "10OFFWINTER",
        "quantity": 1
      }],
      "coupon_code": "15OFFGOLD",
      "quantity": 3,
      "po_number": "PO6767",
      "payment_method": {
        "first_name": "Biggie",
        "last_name": "Smalls",
        "company": "Biggie Smalls Co.",
        "phone": "040000000",
        "company_number": "51 824 753 556",
        "address": "1 Smith St",
        "address_2": "",
        "city": "Mont Albert",
        "postcode": "3145",
        "country": {
          "uuid": "AU"
        },
        "state": "Victoria",
        "type": "CREDIT_CARD",
        "card": "4242424242424242",
        "card_month": "12",
        "card_year": "2017",
        "card_cvv": "121",
        "gateway": "STRIPE"
      },
      "future_start_date": "2017-09-14T00:00:00+00:00"
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/preview")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription: {
    account: {
      code: "BIG001"
    },
    product: {
      code:"BG_VOIP_GLD"
    },
    trial_days: 10,
    subscription_add_ons: [{
      add_on: {
        code:"BG_PS"
      },
      coupon_code: "10OFFWINTER",
      quantity: 1
    }],
    coupon_code: "15OFFGOLD",
    quantity: 3,
    po_number: "PO6767",
    payment_method: {
      first_name: "Biggie",
      last_name: "Smalls",
      company: "Biggie Smalls Co.",
      phone: "040000000",
      company_number: "51 824 753 556",
      address: "1 Smith St",
      address_2: "",
      city: "Mont Albert",
      postcode: "3145",
      country: {
        uuid: "AU"
      },
      state: "Victoria",
      type: "CREDIT_CARD",
      card: "4242424242424242",
      card_month: "12",
      card_year: "2017",
      card_cvv: "121",
      gateway: "STRIPE"
    },
    future_start_date: "2017-09-14T00:00:00+00:00"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription': {
    'account' : {
      'code': 'BIG001'
    },
    'product': {
      'code':'BG_VOIP_GLD'
    },
    'trial_days': 10,
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_PS'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 1
    }],
    'coupon_code': '15OFFGOLD',
    'quantity': 3,
    'po_number': 'PO6767',
    'payment_method': {
      'first_name' : 'Biggie',
      'last_name' : 'Smalls',
      'company' : 'Biggie Smalls Co.',
      'phone' : '040000000',
      'company_number' : '51 824 753 556',
      'address' : '1 Smith St',
      'address_2' : '',
      'city' : 'Mont Albert',
      'postcode' : '3145',
      'country': {
        'uuid': 'AU'
      },
      'state' : 'Victoria',
      'type' : 'CREDIT_CARD',
      'card' : '4242424242424242',
      'card_month' : '12',
      'card_year' : '2017',
      'card_cvv' : '121',
      'gateway' : 'STRIPE'
    },
    'future_start_date': '2017-09-14T00:00:00+00:00'
  }
}

response = requests.post('https://api.billby.com/v2/subscriptions/preview', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription" => [
    "account" => [
      "code" => "BIG001"
    ],
    "product" => [
      "code" => "BG_VOIP_GLD"
    ],
    "trial_days" => 10,
    "subscription_add_ons" => [[
      "add_on" => [
        "code" => "BG_PS"
      ],
      "coupon_code" => "10OFFWINTER",
      "quantity" => 1
    ]],
    "coupon_code" => "15OFFGOLD",
    "quantity" => 3,
    "po_number" => "PO6767",
    "payment_method" => [
      "first_name" => "Biggie",
      "last_name" => "Smalls",
      "company" => "Biggie Smalls Co.",
      "phone" => "040000000",
      "company_number" => "51 824 753 556",
      "address" => "1 Smith St",
      "address_2" => "",
      "city" => "Mont Albert",
      "postcode" => "3145",
      "country" => [
        "uuid" => "AU"
      ],
      "state" => "Victoria",
      "type" => "CREDIT_CARD",
      "card" => "4242424242424242",
      "card_month" => "12",
      "card_year" => "2017",
      "card_cvv" => "121",
      "gateway" => "STRIPE"
    ],
    "future_start_date" => "2017-09-14T00:00:00+00:00"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/preview');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/preview");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'subscription': {
    'account' : {
      'code': 'BIG001'
    },
    'product': {
      'code':'BG_VOIP_GLD'
    },
    'trial_days': 10,
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_PS'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 1
    }],
    'coupon_code': '15OFFGOLD',
    'quantity': 3,
    'po_number': 'PO6767',
    'payment_method': {
      'first_name' : 'Biggie',
      'last_name' : 'Smalls',
      'company' : 'Biggie Smalls Co.',
      'phone' : '040000000',
      'company_number' : '51 824 753 556',
      'address' : '1 Smith St',
      'address_2' : '',
      'city' : 'Mont Albert',
      'postcode' : '3145',
      'country': {
        'uuid': 'AU'
      },
      'state' : 'Victoria',
      'type' : 'CREDIT_CARD',
      'card' : '4242424242424242',
      'card_month' : '12',
      'card_year' : '2017',
      'card_cvv' : '121',
      'gateway' : 'STRIPE'
    },
    'future_start_date': '2017-09-05T00:00:00+00:00'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "",
      "add_on": {
        "code":"BG_PS",
        "href": ""
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "",
        "href": ""
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": "2017-12-15T00:00:00+00:00",
        "status": "PENDING"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 1.8182,
      "component_tax_amount": 1.636,
      "component_total_amount": 18.0000,
      "status": "ACTIVE",
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-14T23:56:54+00:00",
      "href": ""
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": "2017-12-15T00:00:00+00:00",
      "status": "PENDING"
    }],
    "quantity": 3,
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 16.3636,
    "component_tax_amount": 9.2727,
    "component_total_amount": 102.0000,
    "total_amount": 120.0000,
    "setup_fee": 0,
    "status": "SUBSCRIBED_TRIAL",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "trial_start_date": "2017-09-05T00:00:00+00:00",
    "trial_end_date": "2017-09-15T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "2017-09-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": ""
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00"
    "href": ""
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint previews a new subscription. This can be used to see the result of creating a subscription without committing or posting an invoice. See Create Subscription Body Parameters for required parameters.

HTTP Request

POST https://api.billby.com/v2/subscriptions/preview

Body Parameters

See Create Subscription Body Parameters.

Preview Subscription Update

PUT https://api.billby.com/v2/subscriptions/<uuid>/preview

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/preview"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "subscription_add_ons": [{
        "add_on": {
          "code":"BG_SU"
        },
        "coupon_code": "10OFFWINTER",
        "quantity": 4
      },{
        "uuid": "c511e68e6792edeef7520299a9bf9b51",
        "quantity": 1
      }],
      "quantity": 4,
      "prorate_up": "UP_PRORATE_NOW"
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/preview")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription: {
    uuid: "6792edeef7c511e68e520299a9bf9b51",
    subscription_add_ons: [{
      add_on: {
        code:"BG_SU"
      },
      coupon_code: "10OFFWINTER",
      quantity: 4
    },{
        uuid: "c511e68e6792edeef7520299a9bf9b51",
        quantity: 1
    }],
    quantity: 4,
    prorate_up: "UP_PRORATE_NOW"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription': {
      'uuid': '6792edeef7c511e68e520299a9bf9b51',
      'subscription_add_ons': [{
        'add_on': {
          'code':'BG_SU'
        },
        'coupon_code': '10OFFWINTER',
        'quantity': 4
      },{
        'uuid': 'c511e68e6792edeef7520299a9bf9b51',
        'quantity': 1
      }],
      'quantity': 4,
      'prorate_up': 'UP_PRORATE_NOW'
    }
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/preview', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription" => [
    "uuid" => "6792edeef7c511e68e520299a9bf9b51",
    "subscription_add_ons" => [[
      "add_on" => [
        "code" => "BG_SU"
      ],
      "coupon_code" => "10OFFWINTER",
      "quantity" => 4
    ],[
      "uuid" => "c511e68e6792edeef7520299a9bf9b51",
      "quantity" => 1
    ]],
    "quantity" => 4,
    "prorate_up" => "UP_PRORATE_NOW"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/preview');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/preview");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
 'subscription': {
    'uuid': '6792edeef7c511e68e520299a9bf9b51',
    'subscription_add_ons': [{
      'add_on': {
        'code':'BG_SU'
      },
      'coupon_code': '10OFFWINTER',
      'quantity': 4
    },{
      'uuid': 'c511e68e6792edeef7520299a9bf9b51',
      'quantity': 1
    }],
    'quantity': 4,
    'prorate_up': 'UP_PRORATE_NOW'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "c511e68e6792edeef7520299a9bf9b51",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 0,
      "component_tax_amount": 1.8181,
      "component_total_amount": 20.0000,
      "status": "ACTIVE",
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-10-15T11:57:53+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    },{
      "uuid": "",
      "add_on": {
        "code":"BG_SU",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Supercharge",
      "invoice_name": "Supercharge",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        30
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-10-15T11:57:53+00:00",
        "end_date": "2017-10-15T11:57:53+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 4,
      "component_base_amount": 109.0909,
      "component_discount_amount": 10.9091,
      "component_tax_amount": 9.8182,
      "component_total_amount": 108.0000,
      "status": "ACTIVE",
      "start_date": "2017-10-15T11:57:53+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-10-15T11:57:53+00:00",
      "updated_at": "2017-10-15T11:57:53+00:00",
      "href": ""
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-09-15T00:00:00+00:00",
      "end_date": "2017-12-15T00:00:00+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 4,
    "component_base_amount": 145.4545,
    "component_discount_amount": 21.8182,
    "component_tax_amount": 12.3636,
    "component_total_amount": 136.0000,
    "total_amount": 264.0000,
    "setup_fee": 0,
    "status": "PAYING",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "trial_start_date": "2017-09-05T00:00:00+00:00",
    "trial_end_date": "2017-09-15T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "2017-09-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-10-15T11:57:53+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint previews a subscription update. This can be used to see the result of updating a subscription without committing or posting an invoice. See Update Subscription Body Parameters for required parameters.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>/preview

URI Parameters

Parameter Description
uuid The uuid of the subscription to preview

Body Parameters

See Update Subscription Body Parameters.

Cancel Subscription

PUT https://api.billby.com/v2/subscriptions/<uuid>/cancel

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/cancel"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "cancel_date": "2017-10-14T00:00:00+00:00",
      "cancel_reason": "User no longer happy with service."
    }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/cancel")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription: {
    uuid: "6792edeef7c511e68e520299a9bf9b51",
    cancel_date: "2017-10-14T00:00:00+00:00",
    cancel_reason: "User no longer happy with service."
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription': {
    'uuid': '6792edeef7c511e68e520299a9bf9b51',
    'cancel_date': '2017-10-14T00:00:00+00:00' ,
    'cancel_reason': 'User no longer happy with service.'
  }
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/cancel', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription" => [
    "uuid" => "6792edeef7c511e68e520299a9bf9b51",
    "cancel_date" => "2017-10-14T00:00:00+00:00",
    "cancel_reason" => "User no longer happy with service.",
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/cancel');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/cancel");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
 'subscription': {
      'uuid': '6792edeef7c511e68e520299a9bf9b51',
      'cancel_date': '2017-10-14T00:00:00+00:00',
      'cancel_reason': 'User no longer happy with service.'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-06-14T23:56:54+00:00",
        "end_date": "2017-10-14T00:00:00+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 1.8182,
      "component_tax_amount": 1.636,
      "component_total_amount": 18.0000,
      "status": "ACTIVE",
      "start_date": "2017-07-30T23:36:29+00:00",
      "end_date": "2017-10-14T00:00:00+00:00",
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-15T01:20:27+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-03-14T00:00:00+00:00",
      "end_date": "2017-10-14T00:00:00+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 16.3636,
    "component_tax_amount": 9.2727,
    "component_total_amount": 102.0000,
    "total_amount": 120.0000,
    "setup_fee": 0,
    "status": "NON_RENEWING",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": "2017-10-14T00:00:00+00:00",
    "trial_start_date": "2017-02-14T00:00:00+00:00",
    "trial_end_date": "2017-03-14T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "User no longer happy with service.",
    "suspend_reason": "",
    "cancel_date": "2017-10-14T00:00:00+00:00",
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-02-14T00:00:00+00:00",
    "updated_at": "2017-09-15T11:57:53+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint cancels a subscription. Subscriptions are cancelled immediately unless a cancel_date parameter set to an arbitrary future date is provided.

Only renewing subscriptions (PAYING, SUSPENDED, or FREE) can be scheduled for cancellation. The subscription will remains in it's current status until the final billing cycle when it becomes NON_RENEWING, unless the cancel date selected is in the current renewal period in which case it will become NON_RENEWING immediately. See Body Parameters for additional parameters.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>/cancel

URI Parameters

Parameter Description
uuid The uuid of the subscription to update

Body Parameters

Parameter Description Type Required
uuid Unique identifier
cancel_date Future cancellation date. Renewing subscriptions only. If not provided, the subscription will be cancelled immediately. datetime
cancel_reason The cancellation reason string
is_cancelled_non_payment Set to true if cancelling for non-payment boolean

Settle Subscription

PUT https://api.billby.com/v2/subscriptions/<uuid>/settle

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/settle"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/settle")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/settle', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/settle');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/settle");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-06-14T23:56:54+00:00",
        "end_date": "2017-10-14T00:00:00+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 1.8182,
      "component_tax_amount": 1.636,
      "component_total_amount": 18.0000,
      "status": "SETTLED",
      "start_date": "2017-07-30T23:36:29+00:00",
      "end_date": "2017-10-14T00:00:00+00:00",
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-15T01:20:27+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-03-14T00:00:00+00:00",
      "end_date": "2017-09-15T11:57:53+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 16.3636,
    "component_tax_amount": 9.2727,
    "component_total_amount": 102.0000,
    "total_amount": 120.0000,
    "setup_fee": 0,
    "status": "SETTLED",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": "2017-09-15T11:57:53+00:00",
    "trial_start_date": "2017-02-14T00:00:00+00:00",
    "trial_end_date": "2017-03-14T00:00:00+00:00",
    "suspended_date": null,
    "reminder_date": null,
    "next_billing_date": "",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-02-14T00:00:00+00:00",
    "updated_at": "2017-09-15T11:57:53+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint settles a subscription. Subscriptions are settled immediately. Settling the subscription will generate charges for all remaining billing cycles, and payments will be processed.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>/settle

URI Parameters

Parameter Description
uuid The uuid of the subscription to settle

Body Parameters

n/a

Suspend Subscription

PUT https://api.billby.com/v2/subscriptions/<uuid>/suspend

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/suspend"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "suspend_reason": "Problem with manual payment."
    }
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/suspend")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription: {
    uuid: "6792edeef7c511e68e520299a9bf9b51",
    suspend_reason: "Problem with manual payment."
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription': {
    'uuid': '6792edeef7c511e68e520299a9bf9b51',
    'suspend_reason': 'Problem with manual payment.'
  }
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/suspend', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription" => [
    "uuid" => "6792edeef7c511e68e520299a9bf9b51",
    "suspend_reason" => "Problem with manual payment.",
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/suspend');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/suspend");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
 'subscription': {
      'uuid': '6792edeef7c511e68e520299a9bf9b51',
      'suspend_reason': 'Problem with manual payment.'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-06-14T23:56:54+00:00",
        "end_date": "2017-09-14T23:56:54+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 1.8182,
      "component_tax_amount": 1.636,
      "component_total_amount": 18.0000,
      "status": "ACTIVE",
      "start_date": "2017-07-30T23:36:29+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-15T01:20:27+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-03-14T00:00:00+00:00",
      "end_date": "2017-09-15T11:57:53+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 16.3636,
    "component_tax_amount": 9.2727,
    "component_total_amount": 102.0000,
    "total_amount": 120.0000,
    "setup_fee": 0,
    "status": "SUSPENDED",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": "",
    "trial_start_date": "2017-02-14T00:00:00+00:00",
    "trial_end_date": "2017-03-14T00:00:00+00:00",
    "suspended_date": "2017-09-15T11:57:53+00:00",
    "reminder_date": null,
    "next_billing_date": "2017-10-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-02-14T00:00:00+00:00",
    "updated_at": "2017-09-15T11:57:53+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint suspend a subscription. Subscriptions are suspended immediately. Suspending has no effect on billing cycle or end dates, and the subscription will continue to be billed. A Suspended subscription may be re-activated.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>/suspend

URI Parameters

Parameter Description
uuid The uuid of the subscription to suspend

Body Parameters

Parameter Description Type Required
uuid Unique identifier
suspend_reason The suspension reason string

Re-Activate Subscription

PUT https://api.billby.com/v2/subscriptions/<uuid>/reactivate

curl "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/reactivate"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/reactivate")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

response = requests.put('https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/reactivate', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/reactivate');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51/reactivate");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": "success": true,
  "data": {
    "uuid": "6792edeef7c511e68e520299a9bf9b51",
    "account" : {
      "code": "BIG001",
      "path": "https://api.billby.com/v2/accounts/BIG001"
    },
    "product": {
      "code":"BG_VOIP_GLD",
      "href": "https://api.billby.com/v2/products/BG_VOIP_GLD"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "name": "VOIP Gold (Monthly)",
    "invoice_name": "VOIP Gold Subscription",
    "description": "VOIP for Gold Members.",
    "trial_days": 10,
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      40
    ],
    "currency": {
      "uuid": "AUD",
      "href": "https://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "subscription_add_ons": [{
      "uuid": "24edec1e515d11e7a02e024d3574431f",
      "add_on": {
        "code":"BG_PS",
        "href": "https://api.billby.com/v2/add_ons/BG_PS"
      },
      "billing_cycle": {
        "code": "MONTHLY",
        "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
      },
      "subscription": {
        "uuid": "6792edeef7c511e68e520299a9bf9b51",
        "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
      },
      "name": "Platinum Support",
      "invoice_name": "Platinum Support",
      "description": "",
      "repeat": null,
      "uom": "User",
      "price_model": "PER_UNIT",
      "price_array": [
        20
      ],
      "currency": {
        "uuid": "AUD",
        "href": "http://api.billby.com/v2/currencies/AUD"
      },
      "is_digital": true,
      "includes_tax": true,
      "redeemed_coupons": [{
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-06-14T23:56:54+00:00",
        "end_date": "2017-09-14T23:56:54+00:00",
        "status": "ACTIVE"
      }],
      "quantity": 1,
      "component_base_amount": 18.1818,
      "component_discount_amount": 1.8182,
      "component_tax_amount": 1.636,
      "component_total_amount": 18.0000,
      "status": "ACTIVE",
      "start_date": "2017-07-30T23:36:29+00:00",
      "end_date": null,
      "is_deleted": false,
      "pending_price_change": [],
      "created_at": "2017-06-14T23:56:54+00:00",
      "updated_at": "2017-06-15T01:20:27+00:00",
      "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
    }],
    "redeemed_coupons": [{
      "coupon": {
        "code": "15OFFGOLD",
        "href": "https://api.billby.com/v2/coupons/15OFFGOLD"
      }
      "start_date": "2017-03-14T00:00:00+00:00",
      "end_date": "2017-09-15T11:57:53+00:00",
      "status": "ACTIVE"
    }],
    "quantity": 3,
    "component_base_amount": 109.0909,
    "component_discount_amount": 16.3636,
    "component_tax_amount": 9.2727,
    "component_total_amount": 102.0000,
    "total_amount": 120.0000,
    "setup_fee": 0,
    "status": "PAYING",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": "",
    "trial_start_date": "2017-02-14T00:00:00+00:00",
    "trial_end_date": "2017-03-14T00:00:00+00:00",
    "suspended_date": "",
    "reminder_date": null,
    "next_billing_date": "2017-10-15T00:00:00+00:00",
    "po_number": "PO6767",
    "invoice_notes": "",
    "feedback": "",
    "satisfaction": null,
    "cancel_reason": "",
    "suspend_reason": "",
    "cancel_date": null,
    "is_cancelled_non_payment": false,
    "is_deleted": false,
    "prebilling_terms": 0,
    "payment_method": {
      "description": "Visa 424242...242 Exp. 12/17",
      "type": "CARD",
      "gateway": "STRIPE",
      "href": "http://api.billby.com/v2/subscription/6792edeef7c511e68e520299a9bf9b51/payment-method"
    },
    "custom_fields": [
      {
        "key": "Area",
        "value": "LS1516"
      }
    ],
    "pending_price_change": [],
    "created_at": "2017-02-14T00:00:00+00:00",
    "updated_at": "2017-09-15T11:57:53+00:00"
    "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint re-activates a suspended subscription.

HTTP Request

PUT https://api.billby.com/v2/subscriptions/<uuid>/reactivate

URI Parameters

Parameter Description
uuid The uuid of the subscription to re-activate

Body Parameters

n/a

Subscription Add-Ons

Overview

A subscription add-on represents an add-on applied or purchased on a subscription in the same way as a product is 'applied' to a subscription.

URL https://api.billby.com/v2/subscription-add-ons
Methods GET POST PUT DELETE

List Subscription Add-Ons

GET https://api.billby.com/v2/subscription-add-ons

curl "https://api.billby.com/v2/subscription-add-ons"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscription-add-ons', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "subscription_add_ons": [
      {
        "uuid": "24edec1e515d11e7a02e024d3574431f",
        "add_on": {
          "code": "BG_PS",
          "href": "https://api.billby.com/v2/add_ons/BG_PS"
        },
        "billing_cycle": {
          "code": "MONTHLY",
          "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
        },
        "subscription": {
          "uuid": "6792edeef7c511e68e520299a9bf9b51",
          "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
        },
        "name": "Platinum Support",
        "invoice_name": "Platinum Support",
        "description": "",
        "repeat": null,
        "uom": "User",
        "price_model": "PER_UNIT",
        "price_array": [
          20
        ],
        "currency": {
          "uuid": "AUD",
          "href": "http://api.billby.com/v2/currencies/AUD"
        },
        "is_digital": true,
        "includes_tax": true,
        "redeemed_coupons": [
          {
            "coupon": {
              "code": "10OFFWINTER",
              "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
            },
            "start_date": "2017-09-15T00:00:00+00:00",
            "end_date": "2017-12-15T00:00:00+00:00",
            "status": "PENDING"
          }
        ],
        "quantity": 1,
        "component_base_amount": 18.1818,
        "component_discount_amount": 0,
        "component_tax_amount": 1.8181,
        "component_total_amount": 20.0000,
        "status": "ACTIVE",
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": null,
        "is_deleted": false,
        "pending_price_change": [],
        "created_at": "2017-06-14T23:56:54+00:00",
        "updated_at": "2017-06-14T23:56:54+00:00",
        "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/subscription-add-ons?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/subscription-add-ons?page=1"
      }
    },
    "_meta": {
      "total_count": 1,
      "page_count": 1,
      "current_page": 1,
      "page_size": 20
    }
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves all subscription-add-ons.

HTTP Request

GET https://api.billby.com/v2/subscription-add-ons

Query Parameters

Parameter Default Description
page 1 Returns the indicated page
page_size 20 Modify the number of results per page
add_on_code - Filter the results by add-on code
status - Filter the results by status
sort - Sort the results by sortable attribute
expand - Expand expandable nested attribute

Response Body Parameters

Parameter Description Type         
uuid Unique identifier string(50)
add_on Nested add-on reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
billing_cycle Nested billing cycle reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
subscription Nested subscription reference object
      code Unique identifier code string(50)
      href Link representing the URL to the resource string
name Add-on name string
invoice_name Add-on invoice name string
description Add-on description string
repeat Number of billing cycles add-on persists integer
uom Unit of measure string
price_model Price model, 'FLAT_FEE', 'PER_UNIT', 'VOLUME', 'TIERED', 'STAIRSTEP' string
price_array Represents pricing of the add-on as json representation array
is_digital Digital product boolean
includes_tax Whether price_array is tax inclusive boolean
redeemed_coupons Collection of redeemed coupons collection
      coupon Nested coupon reference object
            code Unique identifier code string(50)
            href Link representing the URL to the resource string
      start_date Start date datetime
      end_date End date datetime
      status DELETED, ACTIVE, EXPIRED, or PENDING string
quantity Quantity double
component_base_amount The base amount for the product component double
component_discount_amount The discount amount for the product component double
component_tax_amount The tax amount for the product component double
component_total_amount The total amount for the product component double
status ACTIVE, CANCELLED, SETTLED string
start_date Start date datetime
end_date End date datetime
is_deleted Whether deleted boolean
pending_price_change Pending price change details array
created_at Date resource created datetime
updated_at Date resource updated datetime
href Link representing the URL to the resource string

See Price Array
Sortable attribute
Expandable nested attribute

Lookup Subscription Add-On

GET https://api.billby.com/v2/subscription-add-ons/<uuid>

curl "https://api.billby.com/v2/subscription-add-ons/e011e7bfeced96d82021111b1d805b0b"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/e011e7bfeced96d82021111b1d805b0b")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/subscription-add-ons/e011e7bfeced96d82021111b1d805b0b', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/e011e7bfeced96d82021111b1d805b0b');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/e011e7bfeced96d82021111b1d805b0b");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "add_on": {
      "code": "BG_PS",
      "href": "https://api.billby.com/v2/add_ons/BG_PS"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "name": "Platinum Support",
    "invoice_name": "Platinum Support",
    "description": "",
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      20
    ],
    "currency": {
      "uuid": "AUD",
      "href": "http://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "redeemed_coupons": [
      {
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": "2017-12-15T00:00:00+00:00",
        "status": "PENDING"
      }
    ],
    "quantity": 1,
    "component_base_amount": 18.1818,
    "component_discount_amount": 0,
    "component_tax_amount": 1.8181,
    "component_total_amount": 20.0000,
    "status": "ACTIVE",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "is_deleted": false,
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00",
    "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint retrieves a specific subscription add-on.

HTTP Request

GET https://api.billby.com/v2/subscription-add-ons/<uuid>

URI Parameters

Parameter Description
uuid The unique subscription add-on code of the subscription add-on to retrieve

Response Body Parameters

See List Subscription Add-Ons response body parameters

Create Subscription Add-On

POST https://api.billby.com/v2/subscription-add-ons

curl "https://api.billby.com/v2/subscription-add-ons"
  -X POST
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
  "subscription_add_on": {
    "subscription" : {
      "uuid": "6792edeef7c511e68e520299a9bf9b51"
    },
    "add_on": {
      "code":"BG_PS"
    },
    "coupon_code": "10OFFWINTER",
    "quantity": 1
  }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription_add_on: {
    subscription : {
      uuid: "6792edeef7c511e68e520299a9bf9b51"
    },
    add_on: {
      code:"BG_PS"
    },
    coupon_code: "10OFFWINTER",
    quantity: 1
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription_add_on': {
    'subscription' : {
      'uuid': '6792edeef7c511e68e520299a9bf9b51'
    },
    'add_on': {
      'code':'BG_PS'
    },
    'coupon_code': '10OFFWINTER',
    'quantity': 1
  }
}

response = requests.post('https://api.billby.com/v2/subscription-add-ons', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription_add_on" => [
    "subscription"  => [
      "uuid" => "6792edeef7c511e68e520299a9bf9b51"
    ],
    "add_on" => [
      "code" =>"BG_PS"
    ],
    "coupon_code" => "10OFFWINTER",
    "quantity" => 1
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("POST");
httpConnection.connect();

String data = "{
  'subscription_add_on': {
    'subscription' : {
      'uuid': '6792edeef7c511e68e520299a9bf9b51'
    },
    'add_on': {
      'code':'BG_PS'
    },
    'coupon_code': '10OFFWINTER',
    'quantity': 1
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "add_on": {
      "code": "BG_PS",
      "href": "https://api.billby.com/v2/add_ons/BG_PS"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "name": "Platinum Support",
    "invoice_name": "Platinum Support",
    "description": "",
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      20
    ],
    "currency": {
      "uuid": "AUD",
      "href": "http://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "redeemed_coupons": [
      {
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": "2017-12-15T00:00:00+00:00",
        "status": "PENDING"
      }
    ],
    "quantity": 1,
    "component_base_amount": 18.1818,
    "component_discount_amount": 0,
    "component_tax_amount": 1.8181,
    "component_total_amount": 20.0000,
    "status": "ACTIVE",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": null,
    "is_deleted": false,
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-06-14T23:56:54+00:00",
    "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint adds a new subscription add-on on a subscription. See Body Parameters for required parameters.

The subscription add-on will be applied immediately.

HTTP Request

POST https://api.billby.com/v2/subscription-add-ons

Body Parameters

Parameter Description Type Required
subscription Nested subscription reference object
      uuid Unique identifier string(50)
add_on Nested add-on reference object
      code Unique identifier code string(50)
quantity Quantity double
coupon_code Comma delimited string of coupon codes to apply string

Update Subscription Add-On

PUT https://api.billby.com/v2/subscription-add-ons/<uuid>

curl "https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
  "subscription_add_on": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "quantity": 5,
    "delete_coupons": "10OFFWINTER"
  }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription_add_on: {
    uuid: "24edec1e515d11e7a02e024d3574431f",
    quantity: 5,
    delete_coupons: "10OFFWINTER"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription_add_on': {
    'uuid': '24edec1e515d11e7a02e024d3574431f',
    'quantity': 5,
    'delete_coupons': '10OFFWINTER'
  }
}

response = requests.put('https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription_add_on" => [
    "uuid" => "24edec1e515d11e7a02e024d3574431f",
    "quantity" => 5,
    "delete_coupons" => "10OFFWINTER"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
  'subscription_add_on': {
    'uuid': '24edec1e515d11e7a02e024d3574431f',
    'quantity': 5,
    'delete_coupons': '10OFFWINTER'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "add_on": {
      "code": "BG_PS",
      "href": "https://api.billby.com/v2/add_ons/BG_PS"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "name": "Platinum Support",
    "invoice_name": "Platinum Support",
    "description": "",
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      20
    ],
    "currency": {
      "uuid": "AUD",
      "href": "http://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "redeemed_coupons": [],
    "quantity": 5,
    "component_base_amount": 90.9091,
    "component_discount_amount": 0,
    "component_tax_amount": 9.0909,
    "component_total_amount": 100.0000,
    "status": "ACTIVE",
    "start_date": "2017-07-15T00:00:00+00:00",
    "end_date": null,
    "is_deleted": false,
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-11-14T23:56:54+00:00",
    "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint updates subscription add-on on a subscription. See Body Parameters for required parameters.

HTTP Request

PUT https://api.billby.com/v2/subscription-add-ons/<uuid>

Body Parameters

Parameter Description Type Required
uuid Unique identifier string(50)
quantity Quantity double
coupon_code Comma delimited string of coupon codes to apply string
delete_coupons Comma delimited string of coupon codes to delete from the add-on string

Preview Subscription Add-On Update

PUT https://api.billby.com/v2/subscription-add-ons/<uuid&gt/preview;

curl "https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f/preview"
  -X PUT
  -H "Authorization: Basic encoded_token"
  -H "Content-type: application/json; charset=utf-8"
  -d '{
  "subscription_add_on": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "quantity": 5,
    "delete_coupons": "10OFFWINTER"
  }
}'
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f/preview")
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Basic encoded_token"
request["Content-type"] = "application/json; charset=utf-8"
request.body = {
  subscription_add_on: {
    uuid: "24edec1e515d11e7a02e024d3574431f",
    quantity: 5,
    delete_coupons: "10OFFWINTER"
  }
}

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
    'Content-type': 'application/json; charset=utf-8'
}

data = {
  'subscription_add_on': {
    'uuid': '24edec1e515d11e7a02e024d3574431f',
    'quantity': 5,
    'delete_coupons': '10OFFWINTER'
  }
}

response = requests.put('https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f/preview', headers=headers, data=data)
$headers = [
    'Authorization: Basic encoded_token',
    'Content-type: application/json; charset=utf-8'
];

$data = [
  "subscription_add_on" => [
    "uuid" => "24edec1e515d11e7a02e024d3574431f",
    "quantity" => 5,
    "delete_coupons" => "10OFFWINTER"
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f/preview');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f/preview");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
httpConnection.setRequestProperty("Content-type", "application/json; charset=utf-8");
httpConnection.setRequestMethod("PUT");
httpConnection.connect();

String data = "{
  'subscription_add_on': {
    'uuid': '24edec1e515d11e7a02e024d3574431f',
    'quantity': 5,
    'delete_coupons': '10OFFWINTER'
  }
}";

OutputStreamWriter outputStreamReader = new OutputStreamWriter(httpConnection.getOutputStream());
outputStreamReader.write(data);

outputStreamReader.close();

Response body

{
  "success": true,
  "data": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "add_on": {
      "code": "BG_PS",
      "href": "https://api.billby.com/v2/add_ons/BG_PS"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "name": "Platinum Support",
    "invoice_name": "Platinum Support",
    "description": "",
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      20
    ],
    "currency": {
      "uuid": "AUD",
      "href": "http://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "redeemed_coupons": [],
    "quantity": 5,
    "component_base_amount": 90.9091,
    "component_discount_amount": 0,
    "component_tax_amount": 9.0909,
    "component_total_amount": 100.0000,
    "status": "ACTIVE",
    "start_date": "2017-07-15T00:00:00+00:00",
    "end_date": null,
    "is_deleted": false,
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-11-14T23:56:54+00:00",
    "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint previews a subscription add-on update. This can be used to see the result of updating a subscription add-on without committing or posting an invoice. See Update Subscription Add-On Body Parameters for required parameters.

HTTP Request

PUT https://api.billby.com/v2/subscription-add-ons/<uuid>/preview

Body Parameters

See Update Subscription Add-On Body Parameters.

Cancel Subscription Add-On

DELETE https://api.billby.com/v2/subscription-add-ons/<uuid>

curl "https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f"
  -X DELETE
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.delete('https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/subscription-add-ons/24edec1e515d11e7a02e024d3574431f");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestMethod("DELETE");
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "uuid": "24edec1e515d11e7a02e024d3574431f",
    "add_on": {
      "code": "BG_PS",
      "href": "https://api.billby.com/v2/add_ons/BG_PS"
    },
    "billing_cycle": {
      "code": "MONTHLY",
      "href": "https://api.billby.com/v2/billing_cycles/MONTHLY"
    },
    "subscription": {
      "uuid": "6792edeef7c511e68e520299a9bf9b51",
      "href": "https://api.billby.com/v2/subscriptions/6792edeef7c511e68e520299a9bf9b51"
    },
    "name": "Platinum Support",
    "invoice_name": "Platinum Support",
    "description": "",
    "repeat": null,
    "uom": "User",
    "price_model": "PER_UNIT",
    "price_array": [
      20
    ],
    "currency": {
      "uuid": "AUD",
      "href": "http://api.billby.com/v2/currencies/AUD"
    },
    "is_digital": true,
    "includes_tax": true,
    "redeemed_coupons": [
      {
        "coupon": {
          "code": "10OFFWINTER",
          "href": "https://api.billby.com/v2/coupons/10OFFWINTER"
        },
        "start_date": "2017-09-15T00:00:00+00:00",
        "end_date": "2017-10-15T00:00:00+00:00",
        "status": "EXPIRED"
      }
    ],
    "quantity": 1,
    "component_base_amount": 18.1818,
    "component_discount_amount": 0,
    "component_tax_amount": 1.8181,
    "component_total_amount": 20.0000,
    "status": "CANCELLED",
    "start_date": "2017-09-15T00:00:00+00:00",
    "end_date": "2017-10-15T00:00:00+00:00",
    "is_deleted": false,
    "pending_price_change": [],
    "created_at": "2017-06-14T23:56:54+00:00",
    "updated_at": "2017-10-15T00:00:00+00:00",
    "href": "https://api.billby.com/v2/subscription_add_ons/24edec1e515d11e7a02e024d3574431f"
  }
}

Make sure to replace encoded_token with your base64 encoded API key.

This endpoint cancels a subscription add-on. You may also cancel a subscription add-on by including the status parameter CANCELLED on the subscription add-on when updating a subscription.

HTTP Request

DELETE https://api.billby.com/v2/subscription-add-ons/<uuid>

URI Parameters

Parameter Description
uuid The uuid of the subscription add-on to cancel

Body Parameters

n/a

Taxes

Overview

A tax describes tax rate and other configuration.

URL https://api.billby.com/v2/taxes
Methods GET

List Taxes

GET https://api.billby.com/v2/taxes

curl "https://api.billby.com/v2/taxes"
  -H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'

uri = URI.parse("https://api.billby.com/v2/taxes")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Basic encoded_token"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'Authorization': 'Basic encoded_token',
}

response = requests.get('https://api.billby.com/v2/taxes', headers=headers)
$headers = [
    'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/taxes');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;

URL url = new URL("https://api.billby.com/v2/taxes");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");

InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());

Response body

{
  "success": true,
  "data": {
    "taxes": [
      {
        "code": "GST",
        "country": {
          "uuid": "AU",
          "href": "https://api.billby.com/v2/country/AU"
        },
        "state": null,
        "is_compound": false,
        "is_digital_tax": true,
        "name": "Goods and Services Tax",
        "invoice_name": "GST",
        "tax_rate": "10.00",
        "accounting_code": "GST",
        "created_at": "2017-04-03T05:59:06+00:00",
        "updated_at": "2017-04-03T05:59:06+00:00",
        "href": "https://api.billby.com/v2/tax/GST"
      },
      {
        "code": "GB_STANDARD",
        "country": {
          "uuid": "GB",
          "href": "https://api.billby.com/v2/country/GB"
        },
        "state": null,
        "is_compound": false,
        "is_digital_tax": true,
        "name": "VAT (GB Standard)",
        "invoice_name": "VAT",
        "tax_rate": "20.00",
        "accounting_code": "GB_STANDARD",
        "created_at": "2017-04-03T05:59:06+00:00",
        "updated_at": "2017-04-03T05:59:06+00:00",
        "href": "https://api.billby.com/v2/tax/GB_STANDARD"
      },
    ],
    "_links": {
      "self": {
        "href": "https://api.billby.com/v2/taxes?page=1"
      },
      "last": {
        "href": "https://api.billby.com/v2/taxes?page=1"
      }
    },
    "_meta":