Managing customers in Marlin

Learn what a Marlin customer record is, how wallet addresses link customers to on-chain payments, and how to use metadata for your own reference data.

A customer in Marlin is an off-chain record that ties together a person’s contact information, their Solana wallet, and all the invoices and subscriptions associated with them. Every invoice and subscription must belong to a customer — the customer record is the anchor for all billing activity in your account.

The Customer interface

export interface Customer {
  id: string;
  object: "customer";
  email: string;
  name: string | null;
  walletAddress: string | null;
  metadata: Record<string, string>;
  createdAt: string;
  updatedAt: string;
}

Key fields

email — The customer’s email address. Marlin uses this to deliver invoice notification emails. It is the only required field when creating a customer.

name — An optional display name shown in your dashboard and on hosted checkout pages. If omitted, the email address is shown instead.

walletAddress — The customer’s Solana public key (base58-encoded). This is the address Marlin matches against when recording on-chain payments. When a payment transaction is confirmed on Solana, Marlin uses the signing wallet address to link the payment to the correct customer record.

walletAddress can be null if you create the customer record before they have connected a wallet — for example, when pre-creating customers from your CRM. You can add or update the wallet address later with PATCH /api/customers/:id.

metadata — A free-form Record<string, string> you control entirely. Use it to store any reference data you need to join Marlin’s records back to your own systems — internal user IDs, CRM contact IDs, plan tier labels, or anything else. Marlin never reads or acts on metadata values; they are passed through as-is and returned on every customer object.

Creating customers

You can create customers explicitly before any payment activity:

import Marlin from "@marlin/sdk";

const marlin = new Marlin({ apiKey: process.env.MARLIN_API_KEY! });

const customer = await marlin.customers.create({
  email: "[e-mail]",
  name: "Ada Lovelace",
  walletAddress: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv",
  metadata: {
    internalUserId: "usr_00192",
    plan: "enterprise",
  },
});

Customers can also be created implicitly. When a checkout session completes for a new wallet address that does not match any existing customer, Marlin creates a customer record automatically.

Updating a customer

Use UpdateCustomerInput to change any field — including setting or correcting a walletAddress:

await marlin.customers.update(customer.id, {
  walletAddress: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  metadata: {
    internalUserId: "usr_00192",
    plan: "growth",
  },
});

When you update metadata, the entire object is replaced — not merged. Pass all keys you want to keep, not just the ones you are changing.

Listing and filtering customers

// List all customers (paginated)
const { data, nextCursor } = await marlin.customers.list({ limit: 20 });

// Filter by email
const results = await marlin.customers.list({ email: "[e-mail]" });

Next steps

Customers API reference

Full endpoint reference for creating, updating, and listing customer records.