Billing API

The Billing API allows you to check your subscription status and monitor usage.

Get Subscription Status

Retrieves your current subscription plan and status.

Endpoint: GET /v1/billing/subscription

Example Request

curl https://api.ezy-forms.com.au/v1/billing/subscription \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "plan": {
    "id": "plan_professional",
    "name": "Professional",
    "sessions_included": 100,
    "price_per_session_overage": 5.00
  },
  "status": "active",
  "current_period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "usage": {
    "sessions_used": 45,
    "sessions_remaining": 55
  },
  "billing_email": "[email protected]",
  "next_invoice_date": "2024-02-01T00:00:00Z"
}

Plan Types

| Plan | Sessions Included | Overage Price | |------|-------------------|---------------| | Starter | 10 | $10.00/session | | Professional | 100 | $5.00/session | | Enterprise | Unlimited | N/A |

Get Usage Statistics

Retrieves detailed usage statistics for your account.

Endpoint: GET /v1/billing/usage

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | period | string | Time period: current_month, last_month, last_30_days, last_90_days | | start_date | date | Start date for custom range (YYYY-MM-DD) | | end_date | date | End date for custom range (YYYY-MM-DD) |

Example Request

curl "https://api.ezy-forms.com.au/v1/billing/usage?period=current_month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "sessions": {
    "total_created": 52,
    "completed": 45,
    "cancelled": 3,
    "expired": 2,
    "in_progress": 2
  },
  "completion_rate": 86.5,
  "average_completion_time_hours": 4.2,
  "breakdown_by_form_type": {
    "financial_statement": 52
  },
  "daily_usage": [
    {
      "date": "2024-01-01",
      "sessions_created": 3,
      "sessions_completed": 2
    },
    {
      "date": "2024-01-02",
      "sessions_created": 5,
      "sessions_completed": 4
    }
  ]
}

Billing Portal

For detailed invoices and payment management, use the billing portal:

1. Log in to your Partner Dashboard
2. Navigate to Settings → Billing
3. Click Manage Billing to access the portal

The portal allows you to:

• View and download invoices
• Update payment methods
• Change subscription plans
• Update billing information

Billing Events

You can receive webhooks for billing events:

billing.invoice_paid

Sent when an invoice is successfully paid.

{
  "event": "billing.invoice_paid",
  "timestamp": "2024-02-01T00:00:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "amount": 49900,
    "currency": "aud",
    "period_start": "2024-01-01T00:00:00Z",
    "period_end": "2024-01-31T23:59:59Z"
  }
}

billing.invoice_payment_failed

Sent when a payment attempt fails.

{
  "event": "billing.invoice_payment_failed",
  "timestamp": "2024-02-01T00:00:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "amount": 49900,
    "failure_reason": "card_declined",
    "retry_at": "2024-02-03T00:00:00Z"
  }
}

billing.subscription_cancelled

Sent when a subscription is cancelled.

{
  "event": "billing.subscription_cancelled",
  "timestamp": "2024-02-01T00:00:00Z",
  "data": {
    "effective_date": "2024-02-28T23:59:59Z",
    "reason": "customer_request"
  }
}

Errors

| Error Code | Description | |------------|-------------| | subscription_not_found | No active subscription found | | invalid_date_range | Invalid date range for usage query | | billing_access_denied | API key doesn't have billing permissions |