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:
- Sign up to Billby for a free account.
- 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_keywith 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_tokenwith 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 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_tokenwith 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_tokenwith 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 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_tokenwith 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 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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:
- ACCOUNT_NEW
- ACCOUNT_OPEN
- ACCOUNT_CLOSE
- ACCOUNT_EDIT
- PAYMENT_METHOD_NEW
- PAYMENT_METHOD_EDIT
- PAYMENT_METHOD_DELETE
- SUBSCRIPTION_NEW
- SUBSCRIPTION_EDIT_PRICE
- SUBSCRIPTION_EDIT_DETAILS
- SUBSCRIPTION_CANCEL
- SUBSCRIPTION_CANCEL_NON_PAYMENT
- SUBSCRIPTION_FUTURE_CANCELLATION
- SUBSCRIPTION_STATUS_CHANGE
- SUBSCRIPTION_SETTLE
- SUBSCRIPTION_TRIAL_CONVERT
- SUBCRIPTION_PAYMENT_METHOD_ADDED
- SUBSCRIPTION_EDIT_QUANTITY_UPGRADE
- SUBSCRIPTION_EDIT_QUANTITY_DOWNGRADE
- SUBSCRIPTION_ADD_ON_NEW
- SUBSCRIPTION_ADD_ON_EDIT_PRICE
- SUBSCRIPTION_ADD_ON_EDIT_DETAILS
- SUBSCRIPTION_ADD_ON_CANCEL
- SUBSCRIPTION_ADD_ON_SETTLE
- SUBSCRIPTION_ADD_ON_EDIT_QUANTITY_UPGRADE
- SUBSCRIPTION_ADD_ON_EDIT_QUANTITY_DOWNGRADE
- CHARGE_NEW
- CHARGE_EDIT
- CHARGE_DELETE
- CREDIT_NEW
- CREDIT_EDIT
- CREDIT_DELETE
- INVOICE_EMAIL_FAILED
- ACCOUNTING_API_ERROR
- ACCOUNTING_API_UNAUTHORIZED
- ACCOUNTING_API_SYNC_SUCCESS
- SUBSCRIPTION_COUPON_STATUS_NEW
- SUBSCRIPTION_COUPON_STATUS_ACTIVE
- SUBSCRIPTION_COUPON_STATUS_EXPIRED
- SUBSCRIPTION_COUPON_STATUS_DELETED
- SUBSCRIPTION_ADD_ON_COUPON_STATUS_NEW
- SUBSCRIPTION_ADD_ON_COUPON_STATUS_ACTIVE
- SUBSCRIPTION_ADD_ON_COUPON_STATUS_EXPIRED
- SUBSCRIPTION_ADD_ON_COUPON_STATUS_DELETED
- COMMENT
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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith your base64 encoded API key.
This endpoint retrieves a specific country.
HTTP Request
GET https://api.billby.com/v2/countries/<uuid>
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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith your base64 encoded API key.
This endpoint retrieves a specific currency.
HTTP Request
GET https://api.billby.com/v2/currencies/<uuid>
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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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_tokenwith 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>/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_tokenwith 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_tokenwith 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": {
"total_count": 1,
"page_count": 1,
"current_page": 1,
"page_size": 20
}
}
}
Make sure to replace
encoded_tokenwith your base64 encoded API key.
This endpoint retrieves all taxes.
HTTP Request
GET https://api.billby.com/v2/taxes
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) | |
| country | Nested country reference | object | |
| uuid | Unique identifier | string(50) | |
| href | Link representing the URL to the resource | string | |
| state | State/region/province | string | |
| is_compound | Whether compound tax | boolean | |
| is_digital_tax | Whether this tax is (also) applicable to digital products/add-ons | boolean | |
| name | name | string | |
| invoice_name | Invoice name | string | |
| tax_rate | Tax rate as percentage, e.g. 10.00 for 10% | double | |
| accounting_code | Accounting code for syncing to accounting package | string (100) | |
| created_at | Date resource created | datetime | |
| updated_at | Date resource updated | datetime | |
| href | Link representing the URL to the resource | string |
Lookup tax
GET https://api.billby.com/v2/taxes/<code>
curl "https://api.billby.com/v2/taxes/GST"
-H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'
uri = URI.parse("https://api.billby.com/v2/taxes/GST")
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/GST', headers=headers)
$headers = [
'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/taxes/GST');
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/GST");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());
Response body
{
"success": true,
"data": {
"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"
}
}
Make sure to replace
encoded_tokenwith your base64 encoded API key.
This endpoint retrieves a specific tax.
HTTP Request
GET https://api.billby.com/v2/taxes/<code>
URI Parameters
| Parameter | Description |
|---|---|
| code | The unique tax code of the tax to retrieve |
Response Body Parameters
See List Taxes response body parameters
Transactions
Overview
An transaction represents payments and are generated whenever Billby processes a payment.
| URL | https://api.billby.com/v2/transactions |
| Methods | GET |
List Transactions
GET https://api.billby.com/v2/transactions
curl "https://api.billby.com/v2/transactions"
-H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'
uri = URI.parse("https://api.billby.com/v2/transactions")
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/transactions', headers=headers)
$headers = [
'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/transactions');
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/transactions");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());
Response body
{
"success": true,
"data": {
"transactions": [
{
"uuid": "ffe6c4211e7aeb0211e88ab972c63361",
"account": {
"code": "BIG001",
"href": "https://api.billby.com/v2/account/BIG001"
},
"subscription": null,
"invoice": {
"uuid": "11e78229299ea044747400b547c08759",
"href": "https://api.billby.com/v2/invoice/11e78229299ea044747400b547c08759"
},
"payment_method": null,
"currency": {
"uuid": "AUD",
"href": "https://api.billby.com/v2/currency/AUD"
},
"amount": 100,
"exchange_rate": null,
"reference": "96332 020 201 50321 3125",
"response_code": null,
"response_message": "Offline Payment created by John Smith",
"status": "SUCCESS",
"date": "2017-08-24T02:21:47+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-08-24T02:21:47+00:00",
"href": "https://api.billby.com/v2/transaction/ffe6c4211e7aeb0211e88ab972c63361"
}
],
"_links": {
"self": {
"href": "https://api.billby.com/v2/transactions?page=1"
},
"last": {
"href": "https://api.billby.com/v2/transactions?page=1"
}
},
"_meta": {
"total_count": 1,
"page_count": 1,
"current_page": 1,
"page_size": 20
}
}
}
Make sure to replace
encoded_tokenwith your base64 encoded API key.
This endpoint retrieves all transactions.
HTTP Request
GET https://api.billby.com/v2/transactions
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Returns the indicated page |
| page_size | 20 | Modify the number of results per page |
| account_code | - | Filter the results by account using account's code |
| subscription_uuid | - | Filter the results by a subscription, using subscription's uuid |
| invoice_uuid | - | Filter the results by invoice using invoice's uuid |
| invoice_number | - | Filter the results by invoice using invoice's invoice_number |
| status | - | Filter 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 | |
| invoice | Nested invoice reference | object | |
| uuid | Unique identifier | string(50) | |
| href | Link representing the URL to the resource | string | |
| subscription | Nested subscription reference | object | |
| uuid | Unique identifier | string(50) | |
| href | Link Link representing the URL to the resource | string | |
| 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 | |
| currency | Nested currency reference | object | |
| uuid | Unique identifier | string(50) | |
| href | Link representing the URL to the resource | string | |
| amount | Amount | double | |
| exchange_rate | Exchange rate (filled by payment gateway) | double | |
| reference | Payment response reference | string | |
| response_code | Payment response code | string | |
| response_message | Payment reponse message | string | |
| status | Status, 'SUCCESS', or 'FAILED' | string | |
| date | Date of transaction | datetime | |
| type | The payment method type | string | |
| gateway_transaction_token | Gateway transaction token | string | |
| accounting_uri | Accounting package invoice uri | string | |
| created_at | Date resource created | datetime | |
| href | Link representing the URL to the resource | string |
Sortable attribute
Expandable nested attribute
Lookup transaction
GET https://api.billby.com/v2/transactions/<uuid>
curl "https://api.billby.com/v2/transactions/48087511e782292995637a5ea0447479"
-H "Authorization: Basic encoded_token"
require 'net/http'
require 'uri'
uri = URI.parse("https://api.billby.com/v2/transactions/48087511e782292995637a5ea0447479")
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/transactions/48087511e782292995637a5ea0447479', headers=headers)
$headers = [
'Authorization: Basic encoded_token',
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.billby.com/v2/transactions/48087511e782292995637a5ea0447479');
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/transactions/48087511e782292995637a5ea0447479");
URLConnection httpConnection = url.openConnection();
httpConnection.setRequestProperty("Authorization", "Basic encoded_token");
InputStreamReader inputStreamReader = new InputStreamReader(httpConnection.getInputStream());
Response body
{
"success": true,
"data": {
"uuid": "ffe6c4211e7aeb0211e88ab972c63361",
"account": {
"code": "BIG001",
"href": "https://api.billby.com/v2/account/BIG001"
},
"subscription": null,
"invoice": {
"uuid": "11e78229299ea044747400b547c08759",
"href": "https://api.billby.com/v2/invoice/11e78229299ea044747400b547c08759"
},
"payment_method": null,
"currency": {
"uuid": "AUD",
"href": "https://api.billby.com/v2/currency/AUD"
},
"amount": 100,
"exchange_rate": null,
"reference": "96332 020 201 50321 3125",
"response_code": null,
"response_message": "Offline Payment created by John Smith",
"status": "SUCCESS",
"date": "2017-08-24T02:21:47+00:00",
"gateway_transaction_token": null,
"type": "CREDIT_CARD",
"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-08-24T02:21:47+00:00",
"href": "https://api.billby.com/v2/transaction/ffe6c4211e7aeb0211e88ab972c63361"
}
}
Make sure to replace
encoded_tokenwith your base64 encoded API key.
This endpoint retrieves a specific transaction.
HTTP Request
GET https://api.billby.com/v2/transactions/<uuid>
URI Parameters
| Parameter | Description |
|---|---|
| uuid | The unique identifier of the transaction to retrieve |