Symbol

getpaidhq

HomeDocs
DocumentationDeveloper GuideAPI GuideRelease Notes

Customers

Manage customer data, payment methods, balances, and portal sessions with comprehensive CRUD operations

Customers

Customers represent your end users in GetPaidHQ. Each customer can have multiple subscriptions, payment methods, and invoices. Customer data is automatically isolated by organization for multi-tenancy.

The customer object

{
  "id": "cus_1234567890abcdef",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "+1-555-123-4567",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "currency": "USD",
  "timezone": "America/Los_Angeles",
  "language": "en",
  "tax_id": "123-45-6789",
  "tax_exempt": false,
  "metadata": {
    "user_id": "12345",
    "source": "signup_form"
  },
  "payment_methods": [
    {
      "id": "pm_1234567890",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      },
      "is_default": true
    }
  ],
  "balance": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Attributes

  • id string - Unique identifier for the customer
  • email string - Customer's email address (required, must be unique)
  • name string - Customer's full name
  • phone string - Customer's phone number
  • address object - Customer's billing address
  • currency string - Customer's preferred currency (3-letter ISO code)
  • timezone string - Customer's timezone (IANA timezone identifier)
  • language string - Customer's preferred language (2-letter ISO code)
  • tax_id string - Customer's tax identification number
  • tax_exempt boolean - Whether the customer is exempt from taxes
  • metadata object - Custom key-value pairs for additional data
  • payment_methods array - List of customer's payment methods
  • balance integer - Customer's account balance in cents
  • created_at string - ISO 8601 timestamp when customer was created
  • updated_at string - ISO 8601 timestamp when customer was last updated

Create a customer

Creates a new customer in your organization.

POST https://api.getpaidhq.com/api/customers

Parameters

  • email string required - Customer's email address (must be unique)
  • name string - Customer's full name
  • phone string - Customer's phone number
  • address object - Customer's billing address
    • line1 string - Address line 1
    • line2 string - Address line 2
    • city string - City
    • state string - State/province
    • postal_code string - ZIP/postal code
    • country string - Country code (2-letter ISO)
  • currency string - Preferred currency (defaults to organization currency)
  • timezone string - Customer's timezone
  • language string - Preferred language
  • tax_id string - Tax identification number
  • tax_exempt boolean - Whether customer is tax exempt
  • metadata object - Custom key-value pairs

Example request

curl https://api.getpaidhq.com/api/customers \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco", 
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "currency": "USD",
    "metadata": {
      "user_id": "12345",
      "plan": "pro"
    }
  }'

Example response

{
  "id": "cus_1234567890abcdef",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "+1-555-123-4567",
  "address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA", 
    "postal_code": "94105",
    "country": "US"
  },
  "currency": "USD",
  "timezone": "America/Los_Angeles",
  "language": "en",
  "tax_exempt": false,
  "metadata": {
    "user_id": "12345",
    "plan": "pro"
  },
  "payment_methods": [],
  "balance": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Retrieve a customer

Retrieves an existing customer by ID.

GET https://api.getpaidhq.com/api/customers/{customer_id}

Parameters

  • customer_id string required - The ID of the customer to retrieve

Example request

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

Example response

{
  "id": "cus_1234567890abcdef",
  "email": "customer@example.com",
  "name": "John Doe",
  "currency": "USD",
  "payment_methods": [
    {
      "id": "pm_1234567890",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242"
      },
      "is_default": true
    }
  ],
  "balance": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update a customer

Updates an existing customer. Only provided fields will be updated.

PUT https://api.getpaidhq.com/api/customers/{customer_id}

Parameters

  • customer_id string required - The ID of the customer to update
  • email string - Customer's email address
  • name string - Customer's full name
  • phone string - Customer's phone number
  • address object - Customer's billing address
  • currency string - Preferred currency
  • timezone string - Customer's timezone
  • language string - Preferred language
  • tax_id string - Tax identification number
  • tax_exempt boolean - Whether customer is tax exempt
  • metadata object - Custom key-value pairs

Example request

curl https://api.getpaidhq.com/api/customers/cus_1234567890abcdef \
  -X PUT \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "phone": "+1-555-987-6543",
    "metadata": {
      "user_id": "12345",
      "plan": "enterprise"
    }
  }'

Example response

{
  "id": "cus_1234567890abcdef",
  "email": "customer@example.com",
  "name": "John Smith",
  "phone": "+1-555-987-6543",
  "currency": "USD",
  "metadata": {
    "user_id": "12345",
    "plan": "enterprise"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:22:00Z"
}

Delete a customer

Permanently deletes a customer. This action cannot be undone.

DELETE https://api.getpaidhq.com/api/customers/{customer_id}

Parameters

  • customer_id string required - The ID of the customer to delete

Notes

  • Customers with active subscriptions cannot be deleted
  • All payment methods will be detached before deletion
  • Customer data in invoices and payments will be preserved for record-keeping

Example request

curl https://api.getpaidhq.com/api/customers/cus_1234567890abcdef \
  -X DELETE \
  -H "Authorization: Bearer pk_live_..."

Example response

{
  "id": "cus_1234567890abcdef",
  "deleted": true
}

List customers

Returns a paginated list of customers for your organization.

GET https://api.getpaidhq.com/api/customers

Parameters

  • limit integer - Number of customers to return (1-100, default: 25)
  • page integer - Page number for pagination (default: 1)
  • cursor string - Cursor for cursor-based pagination
  • email string - Filter by email address
  • created_after string - Filter customers created after this date (ISO 8601)
  • created_before string - Filter customers created before this date (ISO 8601)
  • has_payment_method boolean - Filter by whether customer has payment methods
  • currency string - Filter by customer currency
  • order_by string - Sort field (created_at, updated_at, name, email)
  • order_dir string - Sort direction (asc or desc)

Example request

curl "https://api.getpaidhq.com/api/customers?limit=50&order_by=created_at&order_dir=desc" \
  -H "Authorization: Bearer pk_live_..."

Example response

{
  "items": [
    {
      "id": "cus_1234567890abcdef",
      "email": "customer1@example.com",
      "name": "John Doe",
      "currency": "USD",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "cus_1234567890abcdeg", 
      "email": "customer2@example.com",
      "name": "Jane Smith",
      "currency": "USD",
      "created_at": "2024-01-15T09:15:00Z"
    }
  ],
  "total_count": 247,
  "page": 1,
  "page_size": 50,
  "has_more": true,
  "next_cursor": "eyJpZCI6ImN1c18xMjM0NTY3ODkwYWJjZGVnIn0="
}

Search customers

Search customers by name, email, or metadata.

GET https://api.getpaidhq.com/api/customers/search

Parameters

  • query string required - Search query
  • limit integer - Number of results to return (1-100, default: 25)
  • fields array - Fields to search (name, email, metadata)

Example request

curl "https://api.getpaidhq.com/api/customers/search?query=john&fields[]=name&fields[]=email" \
  -H "Authorization: Bearer pk_live_..."

Example response

{
  "items": [
    {
      "id": "cus_1234567890abcdef",
      "email": "john@example.com",
      "name": "John Doe",
      "score": 0.95
    }
  ],
  "total_count": 1
}

Payment methods

Add payment method

Adds a payment method to a customer.

POST https://api.getpaidhq.com/api/customers/{customer_id}/payment_methods

Parameters

  • customer_id string required - The customer ID
  • type string required - Payment method type (card, bank_account)
  • token string required - Payment method token from your payment processor
  • is_default boolean - Whether to set as default payment method

Example request

curl https://api.getpaidhq.com/api/customers/cus_1234567890abcdef/payment_methods \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "token": "tok_visa_4242",
    "is_default": true
  }'

List payment methods

GET https://api.getpaidhq.com/api/customers/{customer_id}/payment_methods

Example request

curl https://api.getpaidhq.com/api/customers/cus_1234567890abcdef/payment_methods \
  -H "Authorization: Bearer pk_live_..."

Example response

{
  "items": [
    {
      "id": "pm_1234567890",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      },
      "is_default": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Update payment method

PUT https://api.getpaidhq.com/api/customers/{customer_id}/payment_methods/{payment_method_id}

Parameters

  • is_default boolean - Whether to set as default
  • metadata object - Custom metadata

Delete payment method

DELETE https://api.getpaidhq.com/api/customers/{customer_id}/payment_methods/{payment_method_id}

Customer balance

Retrieve balance

GET https://api.getpaidhq.com/api/customers/{customer_id}/balance

Example response

{
  "balance": -500,
  "currency": "USD",
  "transactions": [
    {
      "id": "txn_1234567890",
      "amount": -500,
      "description": "Credit applied",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Adjust balance

POST https://api.getpaidhq.com/api/customers/{customer_id}/balance

Parameters

  • amount integer required - Amount to adjust in cents (positive for credit, negative for debit)
  • description string required - Description of the adjustment
  • metadata object - Custom metadata

Example request

curl https://api.getpaidhq.com/api/customers/cus_1234567890abcdef/balance \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": -1000,
    "description": "Account credit for referral"
  }'

Customer portal

Create portal session

Creates a secure session for customers to manage their subscriptions and payment methods.

POST https://api.getpaidhq.com/api/customers/{customer_id}/portal_session

Parameters

  • return_url string required - URL to redirect after session
  • features object - Available features in the portal
    • subscription_management boolean - Allow subscription changes
    • payment_method_management boolean - Allow payment method updates
    • invoice_history boolean - Show invoice history

Example request

curl https://api.getpaidhq.com/api/customers/cus_1234567890abcdef/portal_session \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://your-app.com/account",
    "features": {
      "subscription_management": true,
      "payment_method_management": true,
      "invoice_history": true
    }
  }'

Example response

{
  "id": "ps_1234567890abcdef",
  "url": "https://portal.getpaidhq.com/session/ps_1234567890abcdef",
  "customer_id": "cus_1234567890abcdef",
  "expires_at": "2024-01-15T11:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Webhooks

The following webhook events are available for customers:

  • customer.created - New customer created
  • customer.updated - Customer information updated
  • customer.deleted - Customer deleted
  • customer.payment_method.added - Payment method added
  • customer.payment_method.updated - Payment method updated
  • customer.payment_method.removed - Payment method removed

Example webhook payload

{
  "id": "evt_1234567890abcdef",
  "type": "customer.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "cus_1234567890abcdef",
    "email": "customer@example.com",
    "name": "John Doe",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error codes

Common error codes when working with customers:

CodeDescription
customer_not_foundCustomer ID doesn't exist
email_already_existsEmail address is already in use
invalid_email_formatEmail format is invalid
customer_has_active_subscriptionsCannot delete customer with active subscriptions
payment_method_not_foundPayment method ID doesn't exist
invalid_currencyCurrency code is not supported

Integration Examples

Using cURL

# Create customer
curl -X POST https://api.getpaidhq.co/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }'

# Retrieve customer
curl -X GET https://api.getpaidhq.co/api/customers/cus_1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY"

# List customers
curl -X GET "https://api.getpaidhq.co/api/customers?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update customer
curl -X PATCH https://api.getpaidhq.co/api/customers/cus_1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith"
  }'

Webhooks

Receive real-time event notifications with secure webhook endpoints, signature verification, and retry handling

Subscriptions API

Complete API reference for managing customer subscriptions, billing cycles, and subscription lifecycle events.

On this page

Customers
The customer object
Attributes
Create a customer
Parameters
Example request
Example response
Retrieve a customer
Parameters
Example request
Example response
Update a customer
Parameters
Example request
Example response
Delete a customer
Parameters
Notes
Example request
Example response
List customers
Parameters
Example request
Example response
Search customers
Parameters
Example request
Example response
Payment methods
Add payment method
Parameters
Example request
List payment methods
Example request
Example response
Update payment method
Parameters
Delete payment method
Customer balance
Retrieve balance
Example response
Adjust balance
Parameters
Example request
Customer portal
Create portal session
Parameters
Example request
Example response
Webhooks
Example webhook payload
Error codes
Integration Examples
Using cURL