REST API v1

CloudBill Pro provides a REST API that lets you integrate with external systems, build mobile apps, or automate workflows.

Base URL

https://yourdomain.com/api/v1/{resource}

Authentication

All requests (except GET /api/v1/status) require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Or pass it as a query parameter:

GET /api/v1/services?api_token=YOUR_API_TOKEN

API tokens are generated per-client in the admin panel under Clients → Edit → API Token.

Rate Limiting

The API allows 60 requests per minute per IP by default (configurable in Settings). When exceeded, you'll receive:

{ "error": "Rate limit exceeded", "code": 429 }

Endpoints

GET /api/v1/status

Public health check — no auth required.

{ "status": "ok", "version": "1.0", "time": "2024-01-15T12:00:00+00:00" }

GET /api/v1/profile

Get the authenticated client's profile.

{
  "id": 42,
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "[email protected]",
  "phone": "+1-555-1234",
  "company": "Acme Corp",
  "country": "US",
  "created_at": "2024-01-01 10:00:00"
}

PUT /api/v1/profile

Update profile fields. Send JSON body with any of: first_name, last_name, phone, company, address1, city, state, postcode, country.

GET /api/v1/services

List all services for the authenticated client.

{
  "data": [
    { "id": 1, "product_name": "Business Hosting", "domain": "mysite.com", "status": "active", "next_due_date": "2024-02-01" }
  ],
  "count": 1
}

GET /api/v1/services/{id}

Get a specific service with full details.

GET /api/v1/domains

List all domains for the authenticated client.

GET /api/v1/invoices

Paginated list of invoices. Supports ?page=1&limit=20.

GET /api/v1/invoices/{id}

Get a specific invoice with line items.

GET /api/v1/tickets

List all tickets for the authenticated client.

POST /api/v1/tickets

Create a new support ticket.

// Request body:
{
  "subject": "Need help with DNS settings",
  "message": "I'm trying to set up a CNAME record...",
  "department_id": 2,
  "priority_id": 2
}

// Response (201):
{ "success": true, "ticket_id": 15, "ticket_number": "TKT-A3F7B2C1" }

GET /api/v1/tickets/{id}

Get a ticket with all replies.

GET /api/v1/knowledgebase

Search knowledgebase. Supports ?q=search+term&category=3.

GET /api/v1/announcements

List recent announcements (max 20).

Error Responses

HTTP Code	Meaning
200	Success
201	Created
400	Bad request / validation error
401	Authentication required or invalid token
403	Forbidden (accessing another client's resource)
404	Resource not found
422	Unprocessable entity (missing required field)
429	Rate limit exceeded

Example: cURL

# Get services
curl -H "Authorization: Bearer abc123token" \
  https://billing.yourdomain.com/api/v1/services

# Create a ticket
curl -X POST \
  -H "Authorization: Bearer abc123token" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Help needed","message":"I need assistance with...","department_id":1}' \
  https://billing.yourdomain.com/api/v1/tickets

Example: PHP

$token = 'YOUR_API_TOKEN';
$ch = curl_init('https://billing.yourdomain.com/api/v1/services');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer {$token}"],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response['data'] as $service) {
    echo "{$service['product_name']} — {$service['status']}\n";
}