> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# API Reference — Customers

Provision and manage your customers in Paygent. The Customers API allows you to safely synchronize users from your own database to Paygent's billing system.

## Create or Get Customer

When a user registers or logs into your system, call this endpoint to check if they exist in Paygent. If they do not, Paygent will automatically provision a new customer record linked to your organization. This endpoint is idempotent and safe to call multiple times.

**`cURL`**

```bash title="cURL"
curl --request POST \
  --url 'https://cp-api.withpaygent.com/api/v1/customers/create-or-get' \
  --header 'Content-Type: application/json' \
  --header 'paygent-api-key: YOUR_API_KEY' \
  --data '{
    "externalId": "cust_usr_99887711",
    "name": "Acme Corporation Inc.",
    "email": "billing@acme.com",
    "country": "US",
    "city": "San Francisco"
  }'
```

## Get Customer Subscription Status

Call this endpoint when loading your customer's portal subscription page. It automatically calculates the customer's state and returns the recommended UI action (e.g. `upgrade`, `create_order`, `complete_payment`).

**`cURL`**

```bash title="cURL"
curl --request GET \
  --url 'https://cp-api.withpaygent.com/api/v1/customers/by-external-id/cust_usr_99887711/subscription?agentId=YOUR_AGENT_ID' \
  --header 'paygent-api-key: YOUR_API_KEY'
```

## List Customer Orders

To show an audit list of all contracts, plans, and historical orders in the client's invoice section, call this endpoint.

**`cURL`**

```bash title="cURL"
curl --request GET \
  --url 'https://cp-api.withpaygent.com/api/v1/customers/by-external-id/cust_usr_99887711/orders' \
  --header 'paygent-api-key: YOUR_API_KEY'
```