Billing & Projects API

The Lineserve Billing & Projects API allows you to manage your account billing, projects, and usage programmatically.

Base URL

https://api.lineserve.com/v1

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Account Management

Get Account Information

Retrieve your account details and settings.

Endpoint: GET /account

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account

Example Response:

{
  "account": {
    "id": "acc_123456",
    "email": "user@example.com",
    "name": "John Doe",
    "company": "Acme Corp",
    "status": "active",
    "created_at": "2024-01-01T00:00:00Z",
    "verified": true,
    "currency": "USD",
    "timezone": "Africa/Nairobi"
  }
}

Update Account Information

Update your account details.

Endpoint: PUT /account

Parameters:

name (optional): Account holder name
company (optional): Company name
timezone (optional): Account timezone

Example Request:

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "company": "New Company Ltd",
    "timezone": "Africa/Lagos"
  }' \
  https://api.lineserve.com/v1/account

Billing Management

Get Wallet Balances

Retrieve wallet balances for all currencies.

Endpoint: GET /account/wallets

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/wallets

Example Response:

{
  "wallets": [
    {
      "currency": "USD",
      "available_balance": 150.75,
      "pending_balance": 25.00,
      "reserved_balance": 50.00,
      "total_balance": 225.75
    },
    {
      "currency": "KES",
      "available_balance": 15000.00,
      "pending_balance": 0.00,
      "reserved_balance": 5000.00,
      "total_balance": 20000.00
    }
  ]
}

Add Funds to Wallet

Add funds to your wallet using a payment method.

Endpoint: POST /account/wallets/topup

Parameters:

amount (required): Amount to add
currency (required): Currency code
payment_method (required): Payment method ID

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "payment_method": "pm_123456"
  }' \
  https://api.lineserve.com/v1/account/wallets/topup

Get Billing History

Retrieve billing history and transactions.

Endpoint: GET /account/billing/history

Parameters:

from_date (optional): Start date (ISO 8601 format)
to_date (optional): End date (ISO 8601 format)
type (optional): Transaction type (charge, payment, refund)
page (optional): Page number
per_page (optional): Results per page

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/account/billing/history?from_date=2024-01-01&to_date=2024-01-31"

Example Response:

{
  "transactions": [
    {
      "id": "txn_123456",
      "type": "charge",
      "amount": 25.50,
      "currency": "USD",
      "description": "VPS usage - January 2024",
      "status": "completed",
      "created_at": "2024-01-15T10:30:00Z",
      "service": "compute",
      "resource_id": "vps_789012"
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "per_page": 25,
    "pages": 2
  }
}

Get Current Usage

Get current month usage across all services.

Endpoint: GET /account/usage

Parameters:

service (optional): Filter by service (compute, storage, messaging)
detailed (optional): Include detailed breakdown

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/account/usage?detailed=true"

Example Response:

{
  "usage": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "total_cost": 125.75,
    "currency": "USD",
    "services": {
      "compute": {
        "cost": 80.00,
        "resources": [
          {
            "type": "vps",
            "id": "vps_123456",
            "name": "web-server",
            "cost": 50.00,
            "hours": 744
          }
        ]
      },
      "storage": {
        "cost": 25.75,
        "resources": [
          {
            "type": "object_storage",
            "bucket": "my-app-storage",
            "cost": 15.00,
            "storage_gb": 100,
            "bandwidth_gb": 50
          }
        ]
      },
      "messaging": {
        "cost": 20.00,
        "messages_sent": 400,
        "cost_per_message": 0.05
      }
    }
  }
}

Payment Methods

List Payment Methods

Get a list of saved payment methods.

Endpoint: GET /account/payment-methods

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/payment-methods

Example Response:

{
  "payment_methods": [
    {
      "id": "pm_123456",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2025,
      "is_default": true,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Add Payment Method

Add a new payment method to your account.

Endpoint: POST /account/payment-methods

Parameters:

type (required): Payment method type (card, bank_account)
token (required): Payment method token from frontend
set_default (optional): Set as default payment method

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "token": "tok_123456789",
    "set_default": true
  }' \
  https://api.lineserve.com/v1/account/payment-methods

Delete Payment Method

Remove a payment method from your account.

Endpoint: DELETE /account/payment-methods/{payment_method_id}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/payment-methods/pm_123456

Invoices

List Invoices

Get a list of invoices for your account.

Endpoint: GET /account/invoices

Parameters:

status (optional): Filter by status (paid, pending, overdue)
from_date (optional): Start date
to_date (optional): End date

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/account/invoices?status=paid"

Example Response:

{
  "invoices": [
    {
      "id": "inv_123456",
      "number": "INV-2024-001",
      "status": "paid",
      "amount": 125.75,
      "currency": "USD",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "due_date": "2024-02-15T00:00:00Z",
      "paid_at": "2024-02-10T15:30:00Z",
      "created_at": "2024-02-01T00:00:00Z"
    }
  ]
}

Get Invoice Details

Get detailed information about a specific invoice.

Endpoint: GET /account/invoices/{invoice_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/invoices/inv_123456

Download Invoice PDF

Download an invoice as a PDF file.

Endpoint: GET /account/invoices/{invoice_id}/pdf

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/invoices/inv_123456/pdf \
  -o invoice.pdf

Projects

List Projects

Get a list of all projects in your account.

Endpoint: GET /projects

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/projects

Example Response:

{
  "projects": [
    {
      "id": "proj_123456",
      "name": "Production Environment",
      "description": "Main production infrastructure",
      "status": "active",
      "region": "nairobi",
      "created_at": "2024-01-01T00:00:00Z",
      "resource_count": 15,
      "monthly_cost": 250.00,
      "currency": "USD"
    }
  ]
}

Create Project

Create a new project to organize your resources.

Endpoint: POST /projects

Parameters:

name (required): Project name
description (optional): Project description
region (optional): Default region for resources
budget_limit (optional): Monthly budget limit

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging Environment",
    "description": "Testing and staging infrastructure",
    "region": "nairobi",
    "budget_limit": 100.00
  }' \
  https://api.lineserve.com/v1/projects

Get Project Details

Get detailed information about a specific project.

Endpoint: GET /projects/{project_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/projects/proj_123456

Update Project

Update project information and settings.

Endpoint: PUT /projects/{project_id}

Parameters:

name (optional): Project name
description (optional): Project description
budget_limit (optional): Monthly budget limit

Example Request:

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "budget_limit": 150.00
  }' \
  https://api.lineserve.com/v1/projects/proj_123456

Delete Project

Delete a project and all its resources.

Endpoint: DELETE /projects/{project_id}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/projects/proj_123456

Get Project Resources

List all resources within a project.

Endpoint: GET /projects/{project_id}/resources

Parameters:

service (optional): Filter by service type
status (optional): Filter by resource status

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/projects/proj_123456/resources?service=compute"

Example Response:

{
  "resources": [
    {
      "id": "vps_789012",
      "type": "vps",
      "name": "web-server",
      "status": "running",
      "service": "compute",
      "region": "nairobi",
      "monthly_cost": 50.00,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Project Usage

Get usage statistics for a specific project.

Endpoint: GET /projects/{project_id}/usage

Parameters:

from_date (optional): Start date
to_date (optional): End date

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/projects/proj_123456/usage?from_date=2024-01-01"

API Keys

List API Keys

Get a list of API keys for your account.

Endpoint: GET /account/api-keys

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/api-keys

Example Response:

{
  "api_keys": [
    {
      "id": "key_123456",
      "name": "Production API Key",
      "prefix": "ls_prod_",
      "permissions": ["read", "write"],
      "last_used": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "expires_at": null
    }
  ]
}

Create API Key

Create a new API key with specific permissions.

Endpoint: POST /account/api-keys

Parameters:

name (required): API key name
permissions (required): Array of permissions
expires_at (optional): Expiration date
ip_whitelist (optional): Array of allowed IP addresses

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "permissions": ["read", "write"],
    "expires_at": "2024-12-31T23:59:59Z",
    "ip_whitelist": ["192.168.1.100", "10.0.0.0/8"]
  }' \
  https://api.lineserve.com/v1/account/api-keys

Example Response:

{
  "api_key": {
    "id": "key_789012",
    "name": "CI/CD Pipeline Key",
    "key": "ls_prod_abcdef123456789",
    "permissions": ["read", "write"],
    "expires_at": "2024-12-31T23:59:59Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Revoke API Key

Revoke an API key to disable access.

Endpoint: DELETE /account/api-keys/{key_id}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/api-keys/key_123456

Cost Analytics

Get Cost Breakdown

Get detailed cost breakdown by service and resource.

Endpoint: GET /account/analytics/costs

Parameters:

from_date (optional): Start date
to_date (optional): End date
group_by (optional): Group by (service, project, region, day, week, month)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/account/analytics/costs?from_date=2024-01-01&to_date=2024-01-31&group_by=service"

Example Response:

{
  "cost_breakdown": [
    {
      "service": "compute",
      "cost": 150.00,
      "percentage": 60.0,
      "resources": [
        {
          "type": "vps",
          "count": 3,
          "cost": 120.00
        },
        {
          "type": "kubernetes",
          "count": 1,
          "cost": 30.00
        }
      ]
    },
    {
      "service": "storage",
      "cost": 75.00,
      "percentage": 30.0,
      "resources": [
        {
          "type": "object_storage",
          "cost": 50.00
        },
        {
          "type": "block_storage",
          "cost": 25.00
        }
      ]
    }
  ],
  "total_cost": 250.00,
  "currency": "USD"
}

Get Usage Trends

Get usage trends over time.

Endpoint: GET /account/analytics/trends

Parameters:

metric (required): Metric to analyze (cost, resources, storage, bandwidth)
from_date (optional): Start date
to_date (optional): End date
interval (optional): Data interval (day, week, month)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/account/analytics/trends?metric=cost&interval=day"

Alerts and Notifications

List Alerts

Get a list of billing alerts and notifications.

Endpoint: GET /account/alerts

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/account/alerts

Create Alert

Create a new billing alert.

Endpoint: POST /account/alerts

Parameters:

type (required): Alert type (budget, usage, balance)
threshold (required): Alert threshold
condition (required): Condition (greater_than, less_than)
notification_methods (required): Array of notification methods

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "budget",
    "threshold": 200.00,
    "condition": "greater_than",
    "notification_methods": ["email", "sms"]
  }' \
  https://api.lineserve.com/v1/account/alerts

Error Handling

HTTP Status Codes

200 - Success
201 - Created
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Unprocessable Entity
429 - Rate Limited
500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient wallet balance for this operation",
    "details": {
      "required": 50.00,
      "available": 25.75,
      "currency": "USD"
    }
  }
}

Rate Limiting

Rate Limit: 1000 requests per hour per API key
Billing Operations: 100 requests per hour
Project Operations: 500 requests per hour

Base URL​

Authentication​

Account Management​

Get Account Information​

Update Account Information​

Billing Management​

Get Wallet Balances​

Add Funds to Wallet​

Get Billing History​

Get Current Usage​

Payment Methods​

List Payment Methods​

Add Payment Method​

Delete Payment Method​

Invoices​

List Invoices​

Get Invoice Details​

Download Invoice PDF​

Projects​

List Projects​

Create Project​

Get Project Details​

Update Project​

Delete Project​

Get Project Resources​

Get Project Usage​

API Keys​

List API Keys​

Create API Key​

Revoke API Key​

Cost Analytics​

Get Cost Breakdown​

Get Usage Trends​

Alerts and Notifications​

List Alerts​

Create Alert​

Error Handling​

HTTP Status Codes​

Error Response Format​

Rate Limiting​

Next Steps​

Base URL

Authentication

Account Management

Get Account Information

Update Account Information

Billing Management

Get Wallet Balances

Add Funds to Wallet

Get Billing History

Get Current Usage

Payment Methods

List Payment Methods

Add Payment Method

Delete Payment Method

Invoices

List Invoices

Get Invoice Details

Download Invoice PDF

Projects

List Projects

Create Project

Get Project Details

Update Project

Delete Project

Get Project Resources

Get Project Usage

API Keys

List API Keys

Create API Key

Revoke API Key

Cost Analytics

Get Cost Breakdown

Get Usage Trends

Alerts and Notifications

List Alerts

Create Alert

Error Handling

HTTP Status Codes

Error Response Format

Rate Limiting

Next Steps