Balance Endpoint
Retrieve the current balance and usage statistics for your account. This endpoint is free to use and does not deduct from your balance.
/API/v2/balance.php
Cost: Free (no balance deduction)
Rate Limit: 60 requests per minute
Authentication
This endpoint requires Bearer token authentication. Include your API key in the Authorization header.
curl -X POST https://developers.labelscheap.com/API/v2/balance.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Requested-With: XMLHttpRequest" \
-d "{}"
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://developers.labelscheap.com/API/v2/balance.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer YOUR_API_KEY',
'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
import requests
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
'X-Requested-With': 'XMLHttpRequest'
}
response = requests.post(
'https://developers.labelscheap.com/API/v2/balance.php',
headers=headers,
json={}
)
data = response.json()
fetch('https://developers.labelscheap.com/API/v2/balance.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
'X-Requested-With': 'XMLHttpRequest'
},
body: JSON.stringify({})
})
.then(response => response.json())
.then(data => console.log(data));
Request
This endpoint accepts a POST request with an empty JSON body. No parameters are required.
Headers
| Header | Required | Description |
|---|---|---|
Content-Type |
Yes | Must be application/json |
Authorization |
Yes | Bearer token with your API key |
X-Requested-With |
Yes | Must be XMLHttpRequest |
Request Body
{}
Response
The response includes your current balance, used balance, and currency information.
Success Response
{
"STATUS": "success",
"MESSAGE": "Balance retrieved successfully",
"CODE": "200",
"DATA": {
"current_balance": "48.25",
"used_balance": "-23851.77",
"currency": "USD"
},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Response Fields
| Field | Type | Description |
|---|---|---|
STATUS |
string | Always "success" for successful requests |
MESSAGE |
string | Human-readable success message |
CODE |
string | HTTP status code as string |
DATA.current_balance |
string | Current available balance in USD |
DATA.used_balance |
string | Total amount used from account (negative value) |
DATA.currency |
string | Currency code (always "USD") |
TIMESTAMP |
string | ISO 8601 timestamp of the response |
Code Examples
Here are complete examples for different programming languages:
<?php
class LabelsCheapAPI {
private $apiKey;
private $baseUrl = 'https://developers.labelscheap.com/API/v2/';
public function __construct($apiKey) {
$this->apiKey = $apiKey;
}
public function getBalance() {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->baseUrl . 'balance.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $this->apiKey,
'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
throw new Exception('cURL error: ' . curl_error($ch));
}
$data = json_decode($response, true);
if ($data === null) {
throw new Exception('Invalid JSON response');
}
return $data;
}
}
// Usage
try {
$api = new LabelsCheapAPI('YOUR_API_KEY');
$balance = $api->getBalance();
if ($balance['STATUS'] === 'success') {
echo "Current Balance: $" . $balance['DATA']['current_balance'] . "\n";
echo "Used Balance: $" . $balance['DATA']['used_balance'] . "\n";
echo "Currency: " . $balance['DATA']['currency'] . "\n";
} else {
echo "Error: " . $balance['MESSAGE'] . "\n";
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>
import requests
import json
class LabelsCheapAPI:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://developers.labelscheap.com/API/v2/'
self.headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {api_key}',
'X-Requested-With': 'XMLHttpRequest'
}
def get_balance(self):
try:
response = requests.post(
f'{self.base_url}balance.php',
headers=self.headers,
json={},
timeout=30
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
raise Exception(f'Request failed: {str(e)}')
except json.JSONDecodeError as e:
raise Exception(f'Invalid JSON response: {str(e)}')
# Usage
try:
api = LabelsCheapAPI('YOUR_API_KEY')
balance = api.get_balance()
if balance['STATUS'] == 'success':
print(f"Current Balance: ${balance['DATA']['current_balance']}")
print(f"Used Balance: ${balance['DATA']['used_balance']}")
print(f"Currency: {balance['DATA']['currency']}")
else:
print(f"Error: {balance['MESSAGE']}")
except Exception as e:
print(f"Error: {str(e)}")
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
public class LabelsCheapAPI
{
private readonly string _apiKey;
private readonly string _baseUrl = "https://developers.labelscheap.com/API/v2/";
private readonly HttpClient _httpClient;
public LabelsCheapAPI(string apiKey)
{
_apiKey = apiKey;
_httpClient = new HttpClient();
_httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
_httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest");
}
public async Task GetBalanceAsync()
{
try
{
var content = new StringContent("{}", Encoding.UTF8, "application/json");
var response = await _httpClient.PostAsync($"{_baseUrl}balance.php", content);
response.EnsureSuccessStatusCode();
var responseContent = await response.Content.ReadAsStringAsync();
return JsonConvert.DeserializeObject(responseContent);
}
catch (HttpRequestException ex)
{
throw new Exception($"Request failed: {ex.Message}");
}
catch (JsonException ex)
{
throw new Exception($"Invalid JSON response: {ex.Message}");
}
}
}
// Usage
public class Program
{
public static async Task Main()
{
try
{
var api = new LabelsCheapAPI("YOUR_API_KEY");
var balance = await api.GetBalanceAsync();
if (balance.STATUS == "success")
{
Console.WriteLine($"Current Balance: ${balance.DATA.current_balance}");
Console.WriteLine($"Used Balance: ${balance.DATA.used_balance}");
Console.WriteLine($"Currency: {balance.DATA.currency}");
}
else
{
Console.WriteLine($"Error: {balance.MESSAGE}");
}
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}
Imports System
Imports System.Net.Http
Imports System.Text
Imports System.Threading.Tasks
Imports Newtonsoft.Json
Public Class LabelsCheapAPI
Private ReadOnly _apiKey As String
Private ReadOnly _baseUrl As String = "https://developers.labelscheap.com/API/v2/"
Private ReadOnly _httpClient As HttpClient
Public Sub New(apiKey As String)
_apiKey = apiKey
_httpClient = New HttpClient()
_httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}")
_httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest")
End Sub
Public Async Function GetBalanceAsync() As Task(Of Object)
Try
Dim content As New StringContent("{}", Encoding.UTF8, "application/json")
Dim response = Await _httpClient.PostAsync($"{_baseUrl}balance.php", content)
response.EnsureSuccessStatusCode()
Dim responseContent = Await response.Content.ReadAsStringAsync()
Return JsonConvert.DeserializeObject(responseContent)
Catch ex As HttpRequestException
Throw New Exception($"Request failed: {ex.Message}")
Catch ex As JsonException
Throw New Exception($"Invalid JSON response: {ex.Message}")
End Try
End Function
End Class
' Usage
Public Class Program
Public Shared Async Function Main() As Task
Try
Dim api As New LabelsCheapAPI("YOUR_API_KEY")
Dim balance = Await api.GetBalanceAsync()
If balance.STATUS = "success" Then
Console.WriteLine($"Current Balance: ${balance.DATA.current_balance}")
Console.WriteLine($"Used Balance: ${balance.DATA.used_balance}")
Console.WriteLine($"Currency: {balance.DATA.currency}")
Else
Console.WriteLine($"Error: {balance.MESSAGE}")
End If
Catch ex As Exception
Console.WriteLine($"Error: {ex.Message}")
End Try
End Function
End Class
import React, { useState, useEffect } from 'react';
const LabelsCheapAPI = () => {
const [balance, setBalance] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://developers.labelscheap.com/API/v2/';
const getBalance = async () => {
setLoading(true);
setError(null);
try {
const response = await fetch(`${BASE_URL}balance.php`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`,
'X-Requested-With': 'XMLHttpRequest'
},
body: JSON.stringify({})
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
setBalance(data);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
};
useEffect(() => {
getBalance();
}, []);
if (loading) return Loading balance...;
if (error) return Error: {error};
return (
{balance && balance.STATUS === 'success' ? (
Account Balance
Current Balance: ${balance.DATA.current_balance}
Used Balance: ${balance.DATA.used_balance}
Currency: {balance.DATA.currency}
) : (
Error: {balance?.MESSAGE}
)}
);
};
export default LabelsCheapAPI;
const axios = require('axios');
class LabelsCheapAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://developers.labelscheap.com/API/v2/';
this.headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
'X-Requested-With': 'XMLHttpRequest'
};
}
async getBalance() {
try {
const response = await axios.post(
`${this.baseUrl}balance.php`,
{},
{
headers: this.headers,
timeout: 30000
}
);
return response.data;
} catch (error) {
if (error.response) {
throw new Error(`HTTP ${error.response.status}: ${error.response.data?.MESSAGE || error.message}`);
} else if (error.request) {
throw new Error('No response received from server');
} else {
throw new Error(`Request failed: ${error.message}`);
}
}
}
}
// Usage
async function main() {
try {
const api = new LabelsCheapAPI('YOUR_API_KEY');
const balance = await api.getBalance();
if (balance.STATUS === 'success') {
console.log(`Current Balance: $${balance.DATA.current_balance}`);
console.log(`Used Balance: $${balance.DATA.used_balance}`);
console.log(`Currency: ${balance.DATA.currency}`);
} else {
console.log(`Error: ${balance.MESSAGE}`);
}
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
main();
Request Tester
Test the balance endpoint with your API key:
Common Error Responses
Here are the most common error responses you might encounter:
Authentication Error (401)
{
"STATUS": "error",
"MESSAGE": "Authentication failed: Invalid or missing API key.",
"CODE": "1002",
"HTTP_STATUS": 401,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Rate Limit Exceeded (429)
{
"STATUS": "error",
"MESSAGE": "Rate limit exceeded. Please try again later.",
"CODE": "1010",
"HTTP_STATUS": 429,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Invalid Request Format (400)
{
"STATUS": "error",
"MESSAGE": "Direct access not allowed",
"CODE": "403",
"HTTP_STATUS": 403,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Error Handling Best Practices
- Always check the
STATUSfield in the response - Handle rate limiting by implementing exponential backoff
- Log error codes for debugging purposes
- Implement retry logic for transient errors (5xx status codes)
- Display user-friendly error messages based on the
MESSAGEfield