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.

POST /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 STATUS field 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 MESSAGE field