Billing API

Access billing information, manage subscriptions, and track usage programmatically. Monitor costs, view invoices, and manage your subscription tier.

Overview

The Billing API provides comprehensive access to your subscription and usage data. Use these endpoints to build custom billing dashboards, automate cost tracking, and integrate with your financial systems.

Payment processing is handled securely through Stripe. Sensitive payment details are never exposed through the API.

Endpoints

GET /api/v1/billing/usage

Get Current Usage

Get your current billing period usage summary including scans, uptime checks, and calculated costs.

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "data": {
    "billing_period": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    },
    "usage": {
      "quick_scans": 150,
      "standard_scans": 85,
      "deep_scans": 12,
      "uptime_checks": 43200,
      "storage_mb": 256
    },
    "costs": {
      "base_fee": "9.99",
      "scan_charges": "12.50",
      "uptime_charges": "5.00",
      "storage_charges": "0.00",
      "volume_discount": "-2.75",
      "subtotal": "24.74"
    },
    "tier": "pro"
  }
}
GET /api/v1/billing/usage/events

Get Usage Events

Retrieve detailed usage events for auditing and cost analysis.

Query Parameters

Parameter Type Description
event_type string Optional Filter by type: quick_scan, standard_scan, deep_scan, uptime_check
start_date string Optional Filter events from this date (YYYY-MM-DD)
end_date string Optional Filter events until this date (YYYY-MM-DD)
limit integer Optional Maximum events to return, max 500 (default: 100)
offset integer Optional Offset for pagination (default: 0)

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/usage/events?event_type=standard_scan&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "data": {
    "events": [
      {
        "id": 12345,
        "event_type": "standard_scan",
        "domain_id": 1,
        "domain_hostname": "example.com",
        "quantity": 1,
        "unit_price": "0.05",
        "total_cost": "0.05",
        "created_at": "2025-01-12T10:30:00Z"
      }
    ],
    "total": 85,
    "limit": 50,
    "offset": 0
  }
}
GET /api/v1/billing/tier

Get Current Tier

Get your current subscription tier details including limits and features.

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/tier" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "tier": {
    "name": "pro",
    "display_name": "Pro",
    "monthly_price": "9.99",
    "domain_limit": 50,
    "history_days": 365,
    "scan_frequencies": ["daily", "hourly"],
    "features": {
      "api_access": true,
      "slack_integration": true,
      "webhook_alerts": true,
      "priority_support": false
    }
  },
  "billing": {
    "billing_cycle_start": "2025-01-01",
    "billing_cycle_end": "2025-01-31",
    "current_total": "24.74",
    "payment_status": "active",
    "stripe_customer_id": "cus_xxx",
    "stripe_subscription_id": "sub_xxx"
  }
}
GET /api/v1/billing/tiers

List Available Tiers

Get a list of all available subscription tiers with their features and pricing.

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/tiers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "tiers": [
    {
      "name": "free",
      "display_name": "Free",
      "monthly_price": "0.00",
      "domain_limit": 2,
      "history_days": 30,
      "scan_frequencies": ["daily"],
      "features": {
        "api_access": false,
        "slack_integration": false,
        "webhook_alerts": false
      }
    },
    {
      "name": "pro",
      "display_name": "Pro",
      "monthly_price": "9.99",
      "domain_limit": 50,
      "history_days": 365,
      "scan_frequencies": ["daily", "hourly"],
      "features": {
        "api_access": true,
        "slack_integration": true,
        "webhook_alerts": true
      }
    },
    {
      "name": "business",
      "display_name": "Business",
      "monthly_price": "49.99",
      "domain_limit": 200,
      "history_days": -1,
      "scan_frequencies": ["daily", "hourly", "15min"],
      "features": {
        "api_access": true,
        "slack_integration": true,
        "webhook_alerts": true,
        "priority_support": true
      }
    }
  ]
}
GET /api/v1/billing/invoices

List Invoices

Retrieve a paginated list of all your invoices with payment status.

Query Parameters

Parameter Type Description
page integer Optional Page number for pagination (default: 1)
per_page integer Optional Items per page, max 100 (default: 20)
status string Optional Filter by status: draft, pending, paid, overdue, void, refunded

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/invoices?status=paid" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "invoices": [
    {
      "id": 123,
      "invoice_number": "INV-2025-0001",
      "billing_period_start": "2024-12-01",
      "billing_period_end": "2024-12-31",
      "subtotal": "22.50",
      "tax_amount": "0.00",
      "total_amount": "22.50",
      "status": "paid",
      "due_date": "2025-01-15",
      "paid_at": "2025-01-05T14:30:00Z",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 12,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /api/v1/billing/invoices/{invoice_id}

Get Invoice Details

Retrieve full invoice details including itemized charges and line items.

Path Parameters

Parameter Type Description
invoice_id integer Required Path The unique invoice ID

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/invoices/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "invoice": {
    "id": 123,
    "invoice_number": "INV-2025-0001",
    "billing_period": {
      "start": "2024-12-01",
      "end": "2024-12-31"
    },
    "charges": {
      "base_fee": "9.99",
      "scan_charges": "10.50",
      "uptime_charges": "2.01",
      "storage_charges": "0.00",
      "volume_discount": "-0.00"
    },
    "totals": {
      "subtotal": "22.50",
      "tax_rate": "0.00",
      "tax_amount": "0.00",
      "total_amount": "22.50"
    },
    "status": "paid",
    "is_paid": true,
    "is_overdue": false,
    "due_date": "2025-01-15",
    "paid_at": "2025-01-05T14:30:00Z",
    "stripe_invoice_id": "in_xxx",
    "line_items": [
      {
        "description": "Pro Plan - Monthly",
        "quantity": 1,
        "unit_price": "9.99",
        "total": "9.99"
      },
      {
        "description": "Standard SSL Scans (210)",
        "quantity": 210,
        "unit_price": "0.05",
        "total": "10.50"
      }
    ],
    "notes": null,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-05T14:30:00Z"
  }
}
GET /api/v1/billing/payments

List Payments

Retrieve your payment history with transaction details.

Query Parameters

Parameter Type Description
page integer Optional Page number for pagination (default: 1)
per_page integer Optional Items per page, max 100 (default: 20)
status string Optional Filter by status: pending, processing, succeeded, failed, refunded, cancelled

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/payments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "payments": [
    {
      "id": 456,
      "invoice_id": 123,
      "amount": "22.50",
      "currency": "USD",
      "payment_method": "card",
      "status": "succeeded",
      "is_successful": true,
      "card_last_four": "4242",
      "card_brand": "visa",
      "failure_reason": null,
      "created_at": "2025-01-05T14:30:00Z",
      "processed_at": "2025-01-05T14:30:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 12,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /api/v1/billing/estimate

Estimate Monthly Cost

Calculate estimated monthly costs based on your planned usage parameters.

Query Parameters

Parameter Type Description
domains integer Optional Number of domains (default: 1)
scan_type string Optional Scan type: quick, standard, deep (default: standard)
scan_frequency string Optional Frequency: daily, hourly, 15min, 5min (default: daily)
uptime_interval integer Optional Uptime check interval in seconds: 30, 60, 300
uptime_domains integer Optional Number of domains with uptime monitoring (default: 0)

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/billing/estimate?domains=10&scan_frequency=hourly&uptime_domains=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "success": true,
  "estimate": {
    "parameters": {
      "domains": 10,
      "scan_type": "standard",
      "scan_frequency": "hourly",
      "uptime_interval": null,
      "uptime_domains": 5
    },
    "monthly_scans": 7200,
    "monthly_uptime_checks": 0,
    "costs": {
      "scan_cost": "36.00",
      "uptime_cost": "0.00",
      "base_fee": "9.99",
      "volume_discount": "-4.60",
      "estimated_total": "41.39"
    },
    "recommended_tier": "pro"
  }
}
POST /api/v1/billing/checkout

Create Checkout Session

Create a Stripe Checkout session for upgrading your subscription tier.

Rate limited: This endpoint is limited to 10 requests per hour.

Request Body

Parameter Type Description
tier_name string Required Body Target tier: payg, pro, business
success_url string Required Body URL to redirect on successful payment
cancel_url string Required Body URL to redirect if user cancels

Example Request

cURL 
curl -X POST "https://myssl.info/api/v1/billing/checkout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier_name": "pro",
    "success_url": "https://myapp.com/billing/success",
    "cancel_url": "https://myapp.com/billing/cancel"
  }'

Example Response

200 OK 
{
  "success": true,
  "checkout_url": "https://checkout.stripe.com/pay/cs_xxx",
  "session_id": "cs_xxx"
}
POST /api/v1/billing/portal

Create Billing Portal Session

Create a Stripe Billing Portal session for managing payment methods and viewing invoices.

Request Body

Parameter Type Description
return_url string Required Body URL to return to after portal session

Example Request

cURL 
curl -X POST "https://myssl.info/api/v1/billing/portal" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://myapp.com/settings/billing"
  }'

Example Response

200 OK 
{
  "success": true,
  "portal_url": "https://billing.stripe.com/session/xxx"
}

Error Codes

Billing-specific error codes you may encounter:

Code Message Description
400 Invalid tier The specified tier name is not valid
400 Missing required parameters Required parameters (success_url, cancel_url, return_url) are missing
400 No billing account found User doesn't have a billing account. Contact support.
400 Invalid date format Date parameters must be in YYYY-MM-DD format
404 Invoice not found The specified invoice does not exist or you don't have access
429 Rate limit exceeded Too many requests to checkout/portal endpoints. Wait and try again.

Related Endpoints

Usage API

Detailed usage tracking and limits

Authentication

API keys and authentication