API Reference
Reference the Public API endpoints required for subscription integration.
Base URL and authentication
The production base URL is https://api.vietbilling.com/public/v2. Every endpoint below uses Authorization: Bearer <organization-api-key> and JSON. The API key determines the Organization; URLs never contain an Organization id.
| Method | Endpoint | Purpose |
|---|---|---|
POST | /customers | Create a Customer |
POST | /checkouts | Create a Checkout and optionally create its Customer |
GET | /checkouts/{checkoutId} | Read a Checkout |
GET | /subscriptions/{subscriptionId} | Read a Subscription |
PATCH | /subscriptions/{subscriptionId} | Change Product or schedule/undo cancellation |
GET | /benefit-grants | List active BenefitGrants for a Customer |
Request example
curl -X GET \
"https://api.vietbilling.com/public/v2/subscriptions/sub_123" \
-H "Authorization: Bearer $VIETBILLING_API_KEY" \
-H "Accept: application/json"
Error handling
Check the HTTP status before reading data. Validation errors need request changes; authentication errors should stop immediately; network and 5xx errors may be retried with backoff and a fixed attempt limit.