Billing Endpoints

Subscription management, plan listing, and Stripe checkout/portal integration.

Plans

GET/v1/billing/plans

List available plans

Returns all available subscription plans. No authentication required.

Example Request

Bash
curl https://api.netloc8.com/v1/billing/plans

Response

200List of plans
JSON
[
    {
        "id": "free",
        "name": "Free",
        "monthlyCap": 5000,
        "maxKeys": 2,
        "maxSites": 1,
        "price": 0,
        "stripePriceId": null
    },
    {
        "id": "pro",
        "name": "Pro",
        "monthlyCap": 100000,
        "maxKeys": 10,
        "maxSites": 2,
        "price": 29,
        "stripePriceId": "price_..."
    }
]

Subscriptions

GET/v1/billing/subscriptionbilling:read

Get current subscription

Returns the authenticated user's effective plan and active subscription details.

Example Request

Bash
curl -H "X-API-Key: YOUR_KEY" \
  https://api.netloc8.com/v1/billing/subscription

Response

200Plan and subscription data
JSON
{
    "plan": {
        "id": "pro",
        "name": "Pro",
        "monthlyCap": 100000,
        "maxKeys": 10,
        "maxSites": 2,
        "price": 29
    },
    "subscription": {
        "id": "sub_abc123",
        "status": "active",
        "currentPeriodStart": "2026-03-01T00:00:00Z",
        "currentPeriodEnd": "2026-04-01T00:00:00Z",
        "overagesEnabled": false
    }
}
POST/v1/billing/subscriptionbilling:write

Create checkout session

Creates a Stripe Checkout session for a subscription upgrade. Returns a URL to redirect the user.

Request Body

ParameterTypeRequiredDescription
planIdstringRequiredID of the target plan (e.g. "pro")

Example Request

Bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"planId": "pro"}' \
  https://api.netloc8.com/v1/billing/subscription

Response

200Checkout session URL
JSON
{
    "url": "https://checkout.stripe.com/c/pay/..."
}
PATCH/v1/billing/subscriptionbilling:write

Update subscription settings

Update subscription preferences such as overage billing. Pro plan and above only.

Request Body

ParameterTypeRequiredDescription
overagesEnabledbooleanRequiredEnable or disable overage billing

Example Request

Bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overagesEnabled": true}' \
  https://api.netloc8.com/v1/billing/subscription

Response

200Setting updated
JSON
{
    "overagesEnabled": true
}
DELETE/v1/billing/subscriptionbilling:write

Cancel subscription

Cancels the authenticated user's active subscription at the end of the current billing period. Access continues until period end.

Example Request

Bash
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  https://api.netloc8.com/v1/billing/subscription

Response

200Subscription marked for cancellation
JSON
{
    "status": "canceling"
}

Billing Portal

POST/v1/billing/portalbilling:write

Create billing portal session

Creates a Stripe Customer Portal session for managing billing details, invoices, and payment methods.

Example Request

Bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  https://api.netloc8.com/v1/billing/portal

Response

200Portal session URL
JSON
{
    "url": "https://billing.stripe.com/p/session/..."
}