API Overview

The GetPaidHQ API is a comprehensive subscription billing platform that supports traditional subscriptions, usage-based billing, and hybrid models. Built with enterprise-grade security and scalability in mind, it provides everything you need to manage complex billing scenarios.

Getting started

Base URL

All API requests should be made to:

https://api.getpaidhq.com

For testing, use:

https://api.test.getpaidhq.com

Authentication

The API uses API key authentication. Include your API key in the request headers:

curl https://api.getpaidhq.com/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key from your organization settings in the GetPaidHQ dashboard.

Making your first request

Here's how to create a customer:

curl https://api.getpaidhq.com/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe"
  }'

Core concepts

Organizations

Organizations are the top-level entity in GetPaidHQ. All resources (customers, products, subscriptions) belong to an organization. Multi-tenancy is built-in, ensuring complete data isolation between organizations.

Customers

Customers represent your end users who purchase subscriptions. Each customer can have multiple payment methods and subscriptions.

Products and Variants

Products represent the services you offer. Each product can have multiple variants (e.g., Basic, Pro, Enterprise plans), and each variant can have multiple pricing configurations.

Prices

Prices define how customers are charged. GetPaidHQ supports:

• Traditional pricing: Fixed recurring amounts
• Usage-based pricing: Pure usage billing with unit pricing, percentage fees, or transaction fees
• Hybrid pricing: Fixed base amount plus usage-based charges

Subscriptions

Subscriptions link customers to products with specific pricing. They handle billing cycles, proration, upgrades, downgrades, and cancellations automatically.

Usage Records

For usage-based billing, usage records track consumption that gets aggregated and billed according to your pricing configuration.

Supported billing models

Traditional subscriptions

Fixed recurring charges billed on a schedule (monthly, yearly, etc.).

{
  "billing_type": "traditional",
  "amount": 2999,
  "currency": "USD",
  "interval": "month"
}

Usage-based billing

Charges based on actual consumption with flexible aggregation:

{
  "billing_type": "usage_based",
  "usage_type": "api_calls",
  "unit_type": "requests",
  "unit_price": 10,
  "aggregation_type": "sum"
}

Hybrid models

Combine fixed charges with usage-based overages:

{
  "billing_type": "hybrid",
  "base_amount": 4999,
  "usage_component": {
    "usage_type": "data_transfer", 
    "unit_price": 100,
    "included_units": 1000
  }
}

Key features

Multi-currency support

Bill customers in their local currency with automatic exchange rate handling.

Dunning management

Automated retry logic for failed payments with customizable retry schedules and recovery actions.

Proration

Automatic proration when customers upgrade, downgrade, or change plans mid-cycle.

Invoice generation

Automated PDF invoice generation with customizable templates.

Webhook events

Real-time notifications for all billing events to keep your systems synchronized.

Analytics and reporting

Comprehensive reporting on revenue, churn, failed payments, and usage metrics.

Response format

All API responses follow a consistent JSON format:

{
  "id": "cus_1234567890",
  "object": "customer", 
  "email": "customer@example.com",
  "name": "John Doe",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List endpoints return paginated results:

{
  "items": [...],
  "total_count": 150,
  "page": 1,
  "page_size": 25
}

Error handling

Errors return appropriate HTTP status codes with descriptive error messages:

{
  "error": {
    "type": "validation_error",
    "message": "Email is required",
    "field": "email"
  }
}

Rate limits

API requests are limited to prevent abuse:

• Standard accounts: 1,000 requests per minute
• Pro accounts: 5,000 requests per minute
• Enterprise accounts: Custom limits

Rate limit headers are included in all responses to help you monitor usage.

Support

• Documentation: Comprehensive guides and examples
• SDKs: Official SDKs for popular programming languages
• Support: 24/7 support for Enterprise customers
• Community: Developer community and forums

Ready to get started? Check out our Authentication guide or dive into the Customers resource documentation.