Back to Guides
REST API Examples
cURL ReadyUse Bear Billing REST API directly with cURL, Postman, or any HTTP client. No SDK required. All examples use standard HTTP requests that work in any programming language.
Authentication
All API requests require an API key passed via the Authorization header:
# Get your API key from: https://dashboard.bearbilling.com/settings/api-keys
curl https://api.bearbilling.com/v1/customers \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json"Security: Never commit API keys to version control. Use environment variables in production.
Customers
POST
Create a Customer
curl -X POST https://api.bearbilling.com/v1/customers \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"name": "Acme Corporation",
"metadata": {
"userId": "user_123",
"plan": "pro"
}
}'View Response
{
"id": "cus_1NZxY7KZ2qYgJ8vP",
"email": "customer@example.com",
"name": "Acme Corporation",
"metadata": {
"userId": "user_123",
"plan": "pro"
},
"created_at": "2025-01-13T10:30:00Z"
}GET
Get a Customer
curl https://api.bearbilling.com/v1/customers/cus_1NZxY7KZ2qYgJ8vP \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"GET
List Customers
curl https://api.bearbilling.com/v1/customers?limit=10 \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"Subscriptions
POST
Create a Subscription
curl -X POST https://api.bearbilling.com/v1/subscriptions \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organization_id": "cus_1NZxY7KZ2qYgJ8vP",
"plan_id": "plan_pro_monthly",
"billing_cycle": "monthly",
"start_date": "2025-01-13T10:30:00Z"
}'View Response
{
"id": "sub_1NZxY7KZ2qYgJ8vP",
"organization_id": "cus_1NZxY7KZ2qYgJ8vP",
"plan_id": "plan_pro_monthly",
"status": "active",
"billing_cycle": "monthly",
"current_period_start": "2025-01-13T10:30:00Z",
"current_period_end": "2025-02-13T10:30:00Z",
"created_at": "2025-01-13T10:30:00Z"
}DELETE
Cancel a Subscription
curl -X DELETE https://api.bearbilling.com/v1/subscriptions/sub_1NZxY7KZ2qYgJ8vP \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"Usage Tracking
POST
Record Usage Event
curl -X POST https://api.bearbilling.com/v1/usage \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subscription_id": "sub_1NZxY7KZ2qYgJ8vP",
"metric_name": "api_calls",
"quantity": 100,
"timestamp": "2025-01-13T10:35:00Z",
"idempotency_key": "evt_unique_key_123"
}'Idempotency: Always include an idempotency_key to prevent duplicate usage recording if requests are retried.
Error Handling
HTTP Status Codes
| 200 | OK - Request succeeded |
| 201 | Created - Resource created successfully |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Something went wrong |
Error Response Format
{
"error": {
"type": "validation_error",
"message": "Invalid email format",
"field": "email",
"code": "INVALID_EMAIL"
}
}