Skip to main content
In this guide you’ll create a customer, look them up, and update their details through the API. A customer groups a buyer’s payments, subscriptions, and saved payment methods under one record. You don’t have to create customers up front. Bachs creates one automatically the first time someone completes a payment (matched by email). But creating them yourself lets you attach your own IDs, pre-fill checkout, and reconcile against your system.

​
Before you start

  • A sandbox API key (sk_sandbox_...) with the customers:read / customers:write scopes. See Permissions.

​
Steps

1

Create a customer

Call POST /v1/customers with at least an email. Attach your own data with metadata.
billing_address is optional. Omit it and the customer has none, shown as null. line1 and country are required whenever you do supply one, and country must be a real ISO-3166-1 alpha-2 code (for example NG, FR).Keep the customer_id (prefixed cust_). You’ll use it to attach the customer to a checkout or subscription.
2

Find a customer

Retrieve one by ID, or list and search by email or name.
The list response returns { items, pagination }. Page through with limit and the cursor. See Pagination.
3

Update a customer

Send only the fields you want to change with PATCH. Everything else stays as it was.
billing_address is the one exception to “only the fields you send change.” Omit it and it is untouched, send null and it is cleared, but send an object and it replaces the whole address. Any component you do not include becomes null; it does not merge with what is stored. See the customer object for the full semantics and a worked example. name and phone_number don’t have this behavior; they update normally.

​
Attach a customer to a checkout

Once you have a customer_id, pass it when creating a checkout so the payment ties to that record. See Accept a payment.
If you pass a new email at checkout instead, Bachs creates or matches a customer for you. The same email is never duplicated; later payments append to the existing record.

​
When a checkout creates a customer

You don’t have to pass a customer at all. Omit it on a standard hosted checkout and Bachs collects the buyer’s email and name on the checkout page. By default they do not join your directory: you get the identity on customer_details instead. Send customer_creation: "always" to add them, matched by email so a buyer you already hold attaches to their existing record rather than a second one. customer stays required for a subscription checkout, where recurring billing needs a durable record. See Guest checkout for the full flow.

​
Putting hosted-checkout buyers in your directory

The default, customer_creation: "if_required", keeps a one-time buyer out of your directory. Their email and name still reach you, on customer_details on the checkout object and on checkout.completed, and their purchases group together in your dashboard so you can look them up when they write in. What you do not get is a customer you can reach through this API: customer is null on every response and webhook for that checkout, and no customer.created or customer.updated event fires. Pass customer_creation: "always" when you create the checkout and the buyer is added to your directory like any other customer, matched by email to one you already hold. See customer_creation.
An email a buyer types on the checkout page is not verified. Under always, someone who knows one of your customers’ email addresses can have their purchase recorded against that customer. They cannot see anything about that customer, and they cannot change their name, phone number or any other stored detail. Use the default, if_required, if you would rather a hosted-page buyer could never reach your existing customers at all.
customer_creation does not apply to a subscription or a setup-mode checkout. Both always create a customer, whatever you pass, because recurring billing needs a durable record to keep the renewal card on. Setting if_required everywhere will not stop subscription customers from appearing in your directory.

​
From the dashboard

You can also create and manage customers without code. Open Customers to view a record’s payments, subscriptions, and refunds in one place, or add a customer manually. Records created in the dashboard and via the API are the same customers.

​
Next steps