> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and Manage Your Customers Using the PayGood API

> Learn how to create platform customers and merchant-scoped customers, retrieve customer records, and list customers linked to a merchant.

Customers represent the people or organizations you transact with through PayGood. Every customer is scoped to a specific merchant. Use `entityType: "individual"` for a person and `entityType: "organization"` for a business.

## Create an individual customer

Send a `POST /merchants/{merchantId}/customers` request with `firstName`, `lastName`, and `email`. Include an `idempotencyKey` to make the request safely retryable.

```bash theme={null}
curl -X POST https://api.paygood.co/merchants/mer_01hxy8m1nqk9g3x3y3p0azq2bg/customers \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityType": "individual",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "idempotencyKey": "cust-create-001"
  }'
```

PayGood returns the created customer record with a unique `customerId`.

```json theme={null}
{
  "customerId": "cus_01hxy4m2nqk9g3x3y3p0azq1cf",
  "name": "Jane Smith",
  "displayName": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "entityType": "individual",
  "phone": "+15551234567",
  "createdAt": "2024-06-01T12:00:00Z"
}
```

## Create an organization customer

For a business customer, set `entityType` to `organization` and pass `organizationName` instead of `firstName` and `lastName`.

```bash theme={null}
curl -X POST https://api.paygood.co/merchants/mer_01hxy8m1nqk9g3x3y3p0azq2bg/customers \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityType": "organization",
    "organizationName": "Acme Corp",
    "email": "billing@acmecorp.com",
    "phone": "+15559876543",
    "idempotencyKey": "cust-create-002"
  }'
```

```json theme={null}
{
  "customerId": "cus_01hxy5n3prk9h4y4z4q1bar2dg",
  "name": "Acme Corp",
  "displayName": "Acme Corp",
  "organizationName": "Acme Corp",
  "email": "billing@acmecorp.com",
  "entityType": "organization",
  "phone": "+15559876543",
  "createdAt": "2024-06-01T12:05:00Z"
}
```

## Retrieve a customer

Fetch a customer record at any time by their `customerId` using `GET /customers/{id}`.

```bash theme={null}
curl -X GET https://api.paygood.co/customers/cus_01hxy4m2nqk9g3x3y3p0azq1cf \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY'
```

```json theme={null}
{
  "customerId": "cus_01hxy4m2nqk9g3x3y3p0azq1cf",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "entityType": "individual",
  "phone": "+15551234567",
  "createdAt": "2024-06-01T12:00:00Z"
}
```

## List merchant customers

To retrieve all customers linked to your merchant, use `GET /merchants/{merchantId}/customers`. Results are returned as a paginated list.

```bash theme={null}
curl -X GET https://api.paygood.co/merchants/mer_01hxy8m1nqk9g3x3y3p0azq2bg/customers \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY'
```

The response contains an `items` array and a `page` object for cursor-based pagination.

```json theme={null}
{
  "items": [
    {
      "customerId": "cus_01hxy5n3prk9h4y4z4q1bar2dg",
      "name": "Acme Corp",
      "email": "billing@acmecorp.com",
      "entityType": "organization",
      "createdAt": "2024-06-01T12:05:00Z"
    }
  ],
  "page": {
    "hasMore": false,
    "nextCursor": null
  }
}
```

Pass the `nextCursor` value as a query parameter on your next request to fetch the following page of results.