Skip to main content

Documentation Index

Fetch the complete documentation index at: https://yanhgming.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Customers represent the individuals or businesses that pay you through Marlin. Each customer record is scoped to your merchant account and identified primarily by their Solana wallet address. When you create an invoice, Marlin automatically upserts a customer record for you — but you can also create and manage customers directly using these endpoints. The GET /api/customers/:id endpoint returns the customer’s full invoice and subscription history.

​
GET /api/customers

List all customers on your merchant account, ordered newest-first.

​
Query parameters

​
search
string
Free-text search across walletAddress, label (display name), and email.

​
Response — 200 OK

Returns an array of customer objects. Each object includes _count: { invoices: number, subscriptions: number } with aggregate totals.
​
id
string
Database UUID.
​
merchantId
string
Your merchant account ID.
​
walletAddress
string
The customer’s Solana wallet address (base58).
​
email
string | null
Customer email address.
​
label
string | null
Display name for the customer.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
​
_count
object
Aggregate counts: { invoices: number, subscriptions: number }.
curl "https://api.marlin.dev/api/customers?search=acme" \
  --header "Authorization: Bearer sk_live_abc123"

​
POST /api/customers

Create a new customer record. If a customer with the given walletAddress already exists on your account, Marlin upserts the record — updating email and label if provided — and returns the existing customer rather than creating a duplicate.

​
Request body

​
walletAddress
string
required
The customer’s Solana wallet address (base58, 32–44 characters).
​
email
string
Customer email address. Marlin uses this address when delivering invoice notification emails.
​
label
string
Display name for the customer (max 100 characters).

​
Response — 201 Created

Returns the created or upserted customer object.
​
id
string
Database UUID.
​
merchantId
string
Your merchant account ID.
​
walletAddress
string
The customer’s Solana wallet address.
​
email
string | null
Customer email address.
​
label
string | null
Display name.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
curl --request POST https://api.marlin.dev/api/customers \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "email": "alice@example.com",
    "label": "Alice"
  }'

​
PATCH /api/customers/:id

Update the email or label of an existing customer. Both fields accept null to clear a previously set value.

​
Path parameters

​
id
string
required
The customer’s database UUID.

​
Request body

All fields are optional. Include only the fields you want to change.
​
email
string | null
New email address, or null to remove the existing email.
​
label
string | null
New display name (max 100 characters), or null to remove the existing label.

​
Response — 200 OK

Returns the updated customer object. Error cases
  • NOT_FOUND (404) — The customer does not exist or does not belong to your account.
  • VALIDATION_ERROR (400) — The request body failed schema validation (e.g. invalid email format).
curl --request PATCH https://api.marlin.dev/api/customers/01HXYZ \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{ "label": "Alice Smith", "email": "alice.smith@example.com" }'