Billing integration API

Create, suspend, restore and cancel VPN services from your billing system.

Authentication

Create a billing API token under Settings → Billing in your hosted dashboard. Keep it on your server and treat it like a password. Never put it in browser or mobile application code.

Authorization: Bearer <billing-api-token>
Accept: application/json
Content-Type: application/json

Your dashboard shows its own API address. Replace vpn.yourdomain.com in the examples with that hostname.

Create a customer service

Use the same customer and service identifiers for every update. If you try the request again, reuse the same idempotency key.

curl -X POST "https://vpn.yourdomain.com/api/v1/integration/accounts" \
  -H "Authorization: Bearer <billing-api-token>" \
  -H "Idempotency-Key: order-8801-create" \
  -H "Content-Type: application/json" \
  --data '{
    "external_client_id": "customer-1042",
    "external_service_id": "service-8801",
    "email": "customer@example.com",
    "name": "Example Customer",
    "profile_count": 5,
    "plan_type": "shared",
    "product_name": "VPN access"
  }'

Integration API

VPN Dashboard Integration API

Authenticated billing integration API for customer, account, server and app-token lifecycle automation.

v1.0.3 OpenAPI 3.1.0

Base URL

https://vpn.yourdomain.com/api/v1/integration

Rate limit

90 requests per minute per token/IP bucket.

Billing connection

When a billing token is scoped to a provider, omit provider from requests. Otherwise pass provider as a lowercase billing connection key.

Retries

A matching key and request body returns the original response with Idempotency-Replayed. The same key with a different body returns HTTP 409.

Account request fields

external_client_id: Required. Stable customer identifier from your billing system; maximum 120 characters.
external_service_id: Required. Stable service identifier; maximum 120 characters.
email: Required when creating a new customer. Must be a valid email address.
name: Optional customer name; maximum 255 characters.
profile_count: Required. Number of VPN profiles included with the service, from 1 to 10,000.
product_name: Optional customer-facing product name; maximum 255 characters.
status: Optional: active, suspended or cancelled.

Endpoints

get /profile Read integration profile and capabilities

Responses

200: Integration profile

post /accounts Create or update a VPN account

Parameters

Idempotency-Key: header · required
Required for mutations. The same key must always use the same request body.

Request body

{
    "required": true,
    "content": {
        "application/json": {
            "schema": {
                "$ref": "#/components/schemas/Account"
            }
        }
    }
}

Responses

200: Existing account updated
201: Account created and app token returned
409: Idempotency key conflict or in-progress request

post /accounts/{external_service_id}/suspend Suspend a VPN account

Parameters

external_service_id: path · required
External service/account identifier from the billing platform.
Idempotency-Key: header · required
Required for mutations. The same key must always use the same request body.

Responses

200: Lifecycle action applied
409: Idempotency key conflict or in-progress request

post /accounts/{external_service_id}/unsuspend Reactivate a VPN account

Parameters

external_service_id: path · required
External service/account identifier from the billing platform.
Idempotency-Key: header · required
Required for mutations. The same key must always use the same request body.

Responses

200: Lifecycle action applied
409: Idempotency key conflict or in-progress request

post /accounts/{external_service_id}/cancel Cancel a VPN account

Parameters

external_service_id: path · required
External service/account identifier from the billing platform.
Idempotency-Key: header · required
Required for mutations. The same key must always use the same request body.

Responses

200: Lifecycle action applied
409: Idempotency key conflict or in-progress request

Need the complete API reference?

Open integration downloads

Errors and retries

400: The request could not be understood.
401: The token or request signature is missing or invalid.
403: The token does not have permission for the action.
404: The customer, account, profile or server was not found.
409: The requested change conflicts with the service’s current status, or the idempotency key was already used for a different request.
422: One or more request fields failed validation.
429: The rate limit was reached. Retry after the response indicates.
5xx: A temporary service failure occurred. Wait before trying again, increasing the delay after each failed attempt.