PayKitBeta

Customers

A customer is your own user, keyed by an externalRef you choose (your user id). It's the record subscriptions are created against.

POST/v1/clients/{clientId}/projects/{projectId}/customers

Create a customer

customers.write

Create (or return) a customer keyed by your own externalRef. Idempotent by ref: repeating with the same ref returns the existing record (200 instead of 201).

Path parameters

clientIdstringYour PayKit client (workspace) id.
projectIdstringThe project (environment) the customer belongs to.

Request body

externalRef *stringYour stable id for this user.
emailstringThe customer's email (optional).

Repeating with an email fills one in if the record has none. It never overwrites an email already stored, and never restores one that was erased. Use PATCH to change an address.

curl -X POST "https://api.paykit.co.za/v1/clients/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/projects/f6e5d4c3b2a1908172635445362718a9/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"externalRef":"user_123","email":"buyer@example.com"}'
201 Created
{
  "customer": {
    "id": "7c1f…9a",
    "externalRef": "user_123",
    "email": "buyer@example.com"
  }
}
GET/v1/clients/{clientId}/projects/{projectId}/customers/{externalRef}

Get a customer

customers.read

Resolve a customer's id (and email) by your ref.

Path parameters

clientIdstringYour PayKit client id.
projectIdstringThe project the customer belongs to.
externalRefstringYour id for the user.
curl -X GET "https://api.paykit.co.za/v1/clients/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/projects/f6e5d4c3b2a1908172635445362718a9/customers/user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "customer": {
    "id": "7c1f…9a",
    "externalRef": "user_123",
    "email": "buyer@example.com"
  }
}
PATCH/v1/clients/{clientId}/projects/{projectId}/customers/{externalRef}

Change a customer's email

customers.write

Update the email PayKit holds for a customer. The externalRef is your own key and never changes here.

Path parameters

clientIdstringYour PayKit client id.
projectIdstringThe project the customer belongs to.
externalRefstringYour id for the user.

Request body

email *stringThe customer's new email.

A new address clears any bounce suppression held against the old one, so a customer who corrected a wrong address becomes mailable again. Sending the address they already have changes nothing, so a suppressed address cannot be revived by resending it.

Returns 404 customer_not_found for an unknown ref, and 409 customer_erased for a customer whose personal data has been erased.

curl -X PATCH "https://api.paykit.co.za/v1/clients/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/projects/f6e5d4c3b2a1908172635445362718a9/customers/user_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email":"new@example.com"}'
200 OK
{
  "customer": {
    "id": "7c1f…9a",
    "externalRef": "user_123",
    "email": "new@example.com"
  }
}
IntroductionSubscriptions