Customers
Create and update customer records with billing addresses and payment instruments to support invoicing, recurring billing, and payment recovery
A customer represents a person or business you bill, either individual (B2C) or business (B2B). Create a customer record first, then select it when creating invoices. Each record includes name, email, billing address, tax status, and configuration preferences.
Create customer
When you create a customer, provide at minimum an email address. You can add name, phone, address, tax details, and configuration preferences at creation or add them later. A complete profile enables accurate invoicing and powers Smart Retries for failed payment recovery.
Send a request to the create customerAPI v2 endpoint.
Pass email and type as required fields. Optionally include first_name, last_name, phone, merchant_customer_id, address, tax, configuration, and metadata.
For business customers, include business_details with the business name and legal address.
The response returns the full customer object.
To create a customer
- Go to Billing > Billing 2.0 > Customers.
- Click on Create customer.
- Select the Individual or Business customer type.
- Enter the customer Email.
- Optionally, fill in First name, Last name, Phone number, and Merchant customer ID.
- In the Billing address section, enter address details.
- In the Tax information section, select Taxability to specify if the customer is taxable.
- In the Configuration section, set the Default billing currency and Preferred locales.
- In the Metadata section, add custom key-value pairs if needed.
- Click on Create.
Update customer
You can update customer details at any time.
Send a request to the update customerAPI v2 endpoint with the customer ID and the fields to modify. Only the top-level fields you include in the request are updated. Nested objects such as address, tax, configuration, and business_details are replaced in full when included. To update a single nested field, include the entire object with all fields you want to keep.
You can update email, name, phone, address, tax information, configuration, metadata, business details, and customer type.
You can convert an individual customer to a business customer by setting type to BUSINESS. This is a one-way change. Converting from business to individual is not supported.
Changing the customer type does not affect existing invoices. Paid and finalized invoices remain unchanged. Draft invoices created before the conversion keep the original customer details. Only invoices created after the conversion reflect the new type and business details.
To update a customer
- Go to Billing > Billing 2.0 > Customers.
- Click on the customer ID to open the details page.
- Use the Edit buttons next to Details, Billing address, Tax information, or Configuration to modify the relevant fields and save changes as you make them.
- Optionally, change a customer type from individual to business by clicking on Convert to business. Fill in the business details in the form that appears, then click on Convert to confirm.
The customer details page also shows the customer’s payment instruments and a list of associated invoices.
View customers
View a customer to see their profile, billing address, tax information, or associated invoices.
Send a request to the get customerAPI v2 endpoint with the customer ID. The response returns the full customer object.
To find a customer
- Go to Billing > Billing 2.0 > Customers.
The list shows customer ID, name, email, type, status, taxability, merchant customer ID, and creation date. Filter customers by:
- Customer ID or Merchant customer ID using the search fields
- Email using the search field
- Type using the dropdown (Individual or Business)
- Status using the dropdown
- Created at from and Created at to using the date pickers
- Click on a customer ID to open the details page.
Customer profile
A customer profile stores the information that appears on invoices and receipts.
| Field | Required | Description |
|---|---|---|
| Yes | Used to notify the customer of failed payments or when further action is needed. | |
| Customer type | Yes | Either individual (B2C) or business (B2B). You can convert an individual customer to a business customer. Converting from business to individual is not supported. |
| Merchant customer ID | Optional | Your internal customer ID. Lets you look up the Solidgate record from your own system. |
| Billing address | Optional | Appears on invoices, credit notes, and receipts. Required for accurate tax calculation. For countries with states or provinces, include the state or province. |
| Business details | Optional | Business name and legal address for B2B customers. Appears on invoices and receipts. Required when creating a business customer or converting an individual customer to a business customer. |
Tax information
Tax information on the customer record is used when generating invoices.
Taxability indicates whether the customer is subject to tax. Customers are taxable by default. Set to exempt for tax-exempt customers.
A customer can have up to 20 tax registrations. Each tax registration ID must be unique within a customer’s registrations, and the combination of scheme and country must also be unique. Different customers can share the same tax registration ID.
For each registration, set validation.mode to AUTO or MANUAL.
- With
AUTO, Solidgate sets the registration status toPENDINGand validates it through VIES. Validation runs asynchronously, and the status updates once it completes. - With
MANUAL, providevalidation.status(VALIDorINVALID) andvalidation.validated_at. Solidgate trusts your input, and you accept responsibility for its accuracy.
Payment instruments
Payment instruments are collected automatically from payment details associated with a customer. Each time a customer completes a payment, the card or payment method is saved and linked to their record. You can view all saved payment instruments on the customer details page in the Hub or retrieve them through the API.
Customer events
Solidgate sends webhook notifications when customer records change. You can configure webhook endpoints through the webhooksAPI v2 or in the SolidgateHub under Developers, select API v2 from the dropdown, then go to Webhook endpoints.
| Event | Description |
|---|---|
CUSTOMER_CREATED | A new customer was created. The payload includes the full customer record. Customer createdWebhook |
CUSTOMER_UPDATED | A customer was updated. The payload includes the full customer record with updated values. Customer updatedWebhook |
Common tasks
Generate and send invoice
Before you create an invoice, create a customer for billing purposes.
- Create the customer.
- Define the product you want to sell and set its price.
- Create an invoice using the customer from step 1 and one or more prices from step 2.
After you create the invoice, you can continue updating the customer’s details until the invoice is finalized. Changes apply to the next billing period, when a new invoice is generated using the customer’s latest details.
Add or update tax registration
You can add a tax registration ID to the customer profile. Solidgate uses this information, along with the customer’s location and product configuration, to calculate the final price.
When you update a customer’s tax registrations, include the complete list of registrations you want to keep. Any existing registration not included in the update is removed.
Include the tax object with the registration’s scheme, id, country, and validation details when you create a customerAPI v2, or send it in a request to update a customerAPI v2 to add or change existing tax registrations.
To add a tax registration
- Go to Billing > Billing 2.0 > Customers.
- Find and select a customer profile record.
- Next to Tax information, click on Edit.
- Click on Add registration.
Set Mode to Auto or Manual.
- With Auto, Status and Validated at are set automatically.
- With Manual, set Status and Validated at yourself.
- Select Country and enter the Tax ID. Scheme is fixed to VAT.
- Click on Save changes.