GetPaidHQ API Documentation

GetPaidHQ is a subscription billing platform that provides REST APIs for managing customers, products, subscriptions, payments, and billing operations.

What is GetPaidHQ?

GetPaidHQ provides APIs for subscription billing, including customer management, product catalog management, subscription lifecycle operations, payment processing, and dunning management.

This documentation covers the REST API endpoints, request/response formats, and integration patterns for building billing systems with GetPaidHQ.

Core Features

Subscription Management

Create and manage customer subscriptions
Handle subscription lifecycle events (activate, pause, resume, cancel)
Support for trial periods and billing cycle management
Plan changes with proration handling

Product Catalog

Product and variant management
Flexible pricing configuration
Multiple pricing models including fixed, usage-based, and hybrid

Payment Processing

Customer payment method management
Payment processing and refund handling
Support for multiple payment gateways

Usage-Based Billing

Meter creation and management for tracking usage
Usage event recording via REST API
Usage aggregation and billing

Invoicing

Automated invoice generation and management
Invoice line item management
PDF generation capabilities

Dunning Management

Failed payment recovery campaigns
Configurable retry strategies
Payment token generation for customer payment updates

API Overview

Base URL

Production: https://api.getpaidhq.co Test: https://api-test.getpaidhq.co

Authentication

API requests require authentication using API keys passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Store API keys securely. Never expose them in client-side code or public repositories.

Request Format

All API requests should use JSON format with the appropriate Content-Type header:

Content-Type: application/json

Getting Started

Obtain API Keys

Create a GetPaidHQ account
Navigate to organization settings
Generate API key pairs for test and production environments

Create a Product

Set up your first product in the catalog:

POST /api/products
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "Premium Plan",
  "description": "Premium subscription plan"
}

Create Pricing

Attach pricing to your product:

POST /api/prices
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "productId": "prod_123",
  "amount": 2900,
  "currency": "USD",
  "interval": "month",
  "intervalCount": 1
}

Create a Customer

POST /api/customers
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Add Payment Method

Create a payment method for the customer:

POST /api/customers/{customerId}/payment-methods
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "type": "card",
  "token": "payment_method_token",
  "isDefault": true
}

Create Subscription

Create a subscription for the customer:

POST /api/subscriptions
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "customerId": "cust_123",
  "items": [{
    "priceId": "price_123",
    "quantity": 1
  }],
  "trialPeriodDays": 14
}

Core Concepts

Products and Variants

Products represent what you're selling. Variants allow different configurations of the same product:

Product: Base item (e.g., "API Access")
Variant: Specific configuration (e.g., "Basic", "Pro", "Enterprise")
Price: Cost and billing frequency attached to variants

Pricing Models

Fixed Pricing

Regular recurring charges at set intervals:

{
  "amount": 2900,
  "currency": "USD",
  "interval": "month",
  "intervalCount": 1
}

Usage-Based Pricing

Charges based on measured consumption:

{
  "unitAmount": 1,
  "currency": "USD",
  "usageType": "api_calls",
  "aggregationType": "sum"
}

Subscription Lifecycle

Subscriptions can have the following statuses:

trial - In trial period
active - Active and billing
past_due - Payment failed, retry in progress
paused - Temporarily suspended
cancelled - Cancelled, will not renew
expired - Completed or expired

Usage Metering

For usage-based billing:

Create meters to define what you're measuring
Record usage events via the API
Usage is aggregated based on meter configuration
Billing is calculated from aggregated usage

Test API endpoint: https://api-test.getpaidhq.co
Use test API keys for all test environment requests
Test data is isolated from production

Support

Email: support@getpaidhq.co
Documentation: This documentation site
API Status: Check system status for service updates

Next Steps

Review the API Guide for detailed endpoint documentation
Explore Billing concepts for subscription management
Set up Webhook handling for real-time updates
Configure Dunning management for payment recovery

Overview

GetPaidHQ API Documentation

What is GetPaidHQ?

Core Features

Subscription Management

Product Catalog

Payment Processing

Usage-Based Billing

Invoicing

Dunning Management

API Overview

Base URL

Authentication

Request Format

Getting Started

Obtain API Keys

Create a Product

Create Pricing

Create a Customer

Add Payment Method

Create Subscription

Core Concepts

Products and Variants

Pricing Models

Fixed Pricing

Usage-Based Pricing

Subscription Lifecycle

Usage Metering

API Reference Sections

API Reference

Billing Guide

Dunning Management

Developer Guide

Testing

Support

Next Steps

On this page