API Reference

Welcome to the GetPaidHQ API Reference. This section provides comprehensive documentation for our REST API, including endpoints, parameters, responses, and examples.

API Overview

GetPaidHQ provides a RESTful API that allows you to manage all aspects of your billing and subscription operations programmatically.

Base URL

https://api.getpaidhq.com/v1

Authentication

All API requests require authentication using an API key passed in the Authorization header:

Authorization: Bearer your_api_key_here

Core Resources

Quick Reference

Common Endpoints

Customers

• POST /customers - Create a new customer
• GET /customers/{id} - Retrieve customer details
• PUT /customers/{id} - Update customer information
• DELETE /customers/{id} - Delete a customer

Subscriptions

• POST /subscriptions - Create a new subscription
• GET /subscriptions/{id} - Get subscription details
• PUT /subscriptions/{id} - Update subscription
• POST /subscriptions/{id}/cancel - Cancel subscription

Usage Records

• POST /usage-records - Record usage data
• POST /usage-records/batch - Batch record usage
• GET /usage-records - List usage records
• GET /subscriptions/{id}/usage-summary - Get usage summary

HTTP Status Codes

API Features

Pagination

List endpoints support cursor-based pagination:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "cursor_string"
}

Filtering & Sorting

Many endpoints support filtering and sorting:

GET /customers?status=active&sort=created_at&order=desc

Idempotency

Prevent duplicate operations using idempotency keys:

POST /subscriptions
Idempotency-Key: unique-key-123

Rate Limiting

API requests are rate limited by organization:

• Standard: 100 requests per minute
• Premium: 1000 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

Request & Response Format

Request Format

• Content-Type: application/json
• All dates in ISO 8601 format
• Amounts in smallest currency unit (cents)

Response Format

{
  "object": "customer",
  "id": "cus_123",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  // ... other fields
}

Error Format

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_param",
    "message": "Missing required parameter: email",
    "param": "email"
  }
}

Code Examples

Create a Customer

curl -X POST https://api.getpaidhq.com/v1/customers \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "metadata": {
      "user_id": "123"
    }
  }'

Create a Subscription

curl -X POST https://api.getpaidhq.com/v1/subscriptions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "items": [{
      "price_id": "price_monthly",
      "quantity": 1
    }],
    "trial_period_days": 14
  }'

Record Usage

curl -X POST https://api.getpaidhq.com/v1/usage-records \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_item_id": "si_123",
    "quantity": 100,
    "timestamp": "2024-01-01T12:00:00Z",
    "action": "increment"
  }'

Integration

The API accepts standard HTTP requests and can be integrated using any HTTP client library in your preferred programming language.

Testing

Test Environment

Use the test environment for development and testing:

https://api-test.getpaidhq.co

Test Data

We provide test data for common scenarios:

• Test customer IDs
• Test payment methods
• Test webhook events

API Collection

Download our Postman collection for easy API testing: Download Postman Collection

Webhooks

GetPaidHQ sends webhooks for important events:

• customer.created - New customer created
• subscription.created - New subscription created
• invoice.payment_succeeded - Payment successful
• invoice.payment_failed - Payment failed

Configure webhook endpoints in your dashboard and verify signatures for security.

Need Help?

• Interactive API Explorer - Try endpoints directly in your browser
• Support - Contact our technical support team
• Status Page - Check API status and uptime
• Changelog - Stay updated with API changes