The price books, pricing and products API lets integrators list and maintain price books, look up a customer's default service pricing, and read the product catalogue.
All endpoints are relative to https://billing.pracbill.com.au/api/:tokenid/....
GET /:tokenid/priceBooks/get/page/:pageReturn a paged list of price books (id and name).
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
page |
integer | Yes | Page number to return. |
Request
curl --location --request GET 'https://billing.pracbill.com.au/api/9742f34b-f83a-4ab6-a375-dbfe8e2ddd0a/priceBooks/get/page/1'
Response (success)
{
"results": [
{
"id": 226,
"name": "Wholesaler Price Book",
},
{
"id": 1124,
"name": "Reseller Price Book",
],
"page_number": "1",
"total_pages": 1
}
GET /:tokenid/priceBooks/get/:idReturn further details about a price book, including its items.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
id |
integer | Yes | Price book ID. |
Request
curl --location --request GET 'https://billing.pracbill.com.au/api/892f86d5-da86-4e98-9343-1976a375/priceBooks/get/226'
Response (success)
{
"success": true,
"priceBook": {
"id": 226,
"name": "Wholesaler Price Book",
"date_created": "2017-12-05 08:32:10",
"date_modified": "2017-12-05 08:32:10",
"user_created": 50,
"user_modified": 50,
"items": [
{
"override": 1,
"name": "Service Number 1",
"ratecode": "SERV1",
"list_price": 10,
"adjustment": 5,
"id": 110,
"related_type": "service"
},
{
"override": 0,
"name": "Product Number 1",
"ratecode": "PROD1",
"list_price": 100,
"adjustment": 75,
"id": 140,
"related_type": "product"
}
]
}
}
Response (error)
{"success":false,"description":"priceBook not found"}
Pricing amounts are listed ex tax in dollars, i.e. 10c = 0.10.
| Field | Type | Notes |
|---|---|---|
related_id |
integer | ID of related type (either the product ID or the service ID). |
name |
string | Name of product or service. |
ratecode |
string | The internal code of the product or service. |
list_price |
float | The default price of the product or service. |
related_type |
enum (string) | Either "service" or "product". |
adjustment |
float | If override = 0 then the adjustment is a percentage adjustment of the list price. e.g. adjustment = 75 and list_price = 50 means the calculated price for the product or service will be 75% of 50 = 37.50. If override = 1 then the adjustment is a direct flat price. e.g. adjustment = 5 and list_price = 10 means the calculated price of the product or service = 5. |
POST /:tokenid/priceBooks/postCreate or update a price book. Post a JSON object. The only required field is related_id in the items array; the rest of the fields in the post are optional, and default values will be used if nothing is passed in.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
name |
string | No | Price book name. |
id |
integer | No | Price book ID to update. Omit to create a new price book. |
items |
array | No | Price book items (see below). |
items[].related_id |
integer | Yes | Product ID or service ID. |
items[].adjustment |
float | No | Percentage (override = 0) or flat price (override = 1). See item fields above. |
items[].override |
integer | No | 0 = percentage adjustment, 1 = flat price. |
items[].related_type |
string | No | "service" or "product". |
Request
curl --location --request POST 'https://billing.pracbill.com.au/api/bf8c6695-4e75-458a-ab27-93103358b08f/priceBooks/post' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Mad Test Book",
"id": 23,
"items": [
{
"related_id": 129,
"adjustment": 10,
"override": 1,
"related_type": "service"
},
{
"related_id": 130,
"adjustment": 20,
"override": 0,
"related_type": "service"
},
{
"related_id": 40421,
"adjustment": 30,
"override": 1,
"related_type": "product"
},
{
"related_id": 54457,
"adjustment": 40,
"override": 0,
"related_type": "product"
}
]
}'
Response (success)
{
"success": true,
"id": 130
}
Response (error)
{
"success": false,
"message": "The requested data was empty ignoring"
}
This error message occurs from one of the following conditions:
GET /:tokenid/customer/get/servicePricing/:cidGet the default pricing for all services for a customer.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
cid |
integer | Yes | Customer ID. |
Request
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/customer/get/servicePricing/1234',
type: 'GET',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success":'sucess',
"prices": [
{
"service_type_id": "555",
"name": "SIP Trunk",
"price": "20.0000",
"default_price": false
},
{
"service_type_id": "556",
"name": "Number Range",
"price": "59.0000",
"default_price": true
}
]
}
Response (error)
{
"success": "false",
"message":"unable to retrieve customer",
}
GET /:tokenid/products/get/page/:pageReturn a paged list of products.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
page |
integer | Yes | Page number to return. |
Request
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/products/get/page/1',
type: 'GET',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"results": [
{
"pid": "123",
"title": "Cool Product",
"partnumber": "COOLP",
"ex_tax_amount": "15.0000",
"category_name": "Product Group"
},
],
"page_number": "1",
"total_pages": 1
}
GET /:tokenid/product/get/:idReturn further details about a product.
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenid |
string | Yes | Your API access token. |
id |
integer | Yes | Product ID (pid). |
Request
$.ajax({
url: '/api/892f86d5-da86-4e98-9343-1976a375/product/get/123',
type: 'GET',
contentType: 'application/json',
success: function( response ) {
console.log(response);
}
});
Response (success)
{
"success": true,
"products": {
'pid': 123,
'partnumber': 'COOLP',
'description': 'This is our coolest product that we sell',
'ex_tax_amount': 90,
'inc_tax_amount': 99,
'cost': 80,
'vid': 321,
'vpartnumber': 'COOLEST-P',
'taxrate_id': 222,
'taxrate': 10,
'catid': 111,
'manufacturer': 'Awesome Business',
'model': 'Cool1',
'title': 'Cool Product',
'accounting_account': 0,
'hazmatcode': ''
}
}
Response (error)
{"success":false,"description":"products not found"}
| Field | Type | Notes |
|---|---|---|
pid |
integer | ID of product. |
partnumber |
string | Internal product code / part number. |
description |
string | Long description of item. |
ex_tax_amount |
decimal | Ex tax sell price. |
inc_tax_amount |
decimal | Inc tax sell price. |
cost |
decimal | Ex tax buy price. |
vid |
integer | Vendor ID. |
vpartnumber |
string | Vendor part number. |
taxrate_id |
integer | ID of the tax rate. |
taxrate |
decimal | The stored % amount in whole units for tax, e.g. 10% = 10. |
catid |
integer | Product category ID. |
manufacturer |
string | Manufacturer name. |
model |
string | Model name. |
title |
string | The short description of item. |
accounting_account |
integer | Which accounting account this is related to (only if accounting enabled). |
hazmat_code |
string | Code for hazardous materials. |
Related: Getting started with the API, API overview, Customers API, Services API, External sales and orders API.