The Customers API allows you to create, retrieve, update customer information, and generate customer tokens for headless integrations.
List Customers
Retrieve all customers in your store.
const response = await client.customers.getCustomers({
params: {
limit: 50,
search: '[email protected]', // Optional: search by email or name
after: 'customer-id', // Optional: for pagination
asc: false // Optional: sort order
}
});
console.log(response.data); // Array of CustomerDto
Parameters
limit (optional): Maximum number of customers to returnsearch (optional): Search by customer email or nameafter (optional): Return customers after this ID (cursor-based pagination)before (optional): Return customers before this IDasc (optional): Sort order - true for ascending, false for descending
Response
Returns an array of customer objects with customer details, purchase history, and metadata.
Get Customer by ID
Retrieve a specific customer by their ID.
const response = await client.customers.getCustomerById({
path: {
customerId: '1234567890'
}
});
console.log(response.data); // CustomerDto
Parameters
customerId (required): The ID of the customer to retrieve
Create Customer
Create a new customer account.
const response = await client.customers.createCustomer({
data: {
email: '[email protected]',
name: 'John Doe',
platform_accounts: [
{
platform: 'steam',
identifier: '76561198000000000'
}
],
metadata: {
notes: 'VIP customer'
}
}
});
console.log(response.data); // Created CustomerDto
Request Body
Key fields include:
email: Customer’s email addressname: Customer’s display nameplatform_accounts: Array of linked platform accounts (Steam, Minecraft, etc.)metadata: Custom key-value data for the customer
Update Customer
Update an existing customer’s information.
const response = await client.customers.updateCustomer({
path: {
customerId: '1234567890'
},
data: {
name: 'John Smith',
metadata: {
tier: 'premium',
notes: 'Upgraded to premium'
}
}
});
console.log(response.data); // Updated CustomerDto
Parameters
customerId (required): The ID of the customer to updatedata (required): Fields to update (partial update supported)
Lookup Customer
Lookup a customer by external platform ID.
const response = await client.customers.lookupCustomer({
params: {
platform: 'steam',
platform_id: '76561198000000000'
}
});
console.log(response.data); // CustomerDto if found
Parameters
platform (required): Platform type (e.g., ‘steam’, ‘minecraft’)platform_id (required): Platform-specific identifier
This is useful for finding customers by their game account IDs.
Bulk Create Customers
Create up to 200 customers at once.
const response = await client.customers.bulkCreateCustomers({
data: {
customers: [
{
email: '[email protected]',
name: 'User One',
platform_accounts: [{
platform: 'steam',
identifier: '76561198000000001'
}]
},
{
email: '[email protected]',
name: 'User Two',
platform_accounts: [{
platform: 'steam',
identifier: '76561198000000002'
}]
}
]
}
});
console.log(response.data); // Array of created customers
Request Body
customers (required): Array of customer objects to create (max 200)
Bulk creation is useful for migrating customers from another platform or importing large customer lists.
Customer Tokens
Generate tokens for headless/storefront API access.
Create Customer Token
Generate a token that allows a customer to use the Storefront API.
const response = await client.customers.createCustomerToken({
path: {
customerId: '1234567890'
}
});
console.log(response.data.token); // Customer token string
Invalidate Customer Tokens
Invalidate all tokens for a customer (useful for security purposes).
await client.customers.invalidateCustomerTokens({
path: {
customerId: '1234567890'
}
});
// Returns 204 No Content on success
Customer Delivery Items
Manage delivery items for a customer.
Get Customer Delivery Items
const response = await client.delivery.getCustomerDeliveryItems({
path: {
customerId: '1234567890'
}
});
console.log(response.data); // Array of delivery items
Assign Delivery Item
Manually assign a delivery item to a customer.
const response = await client.delivery.assignDeliveryItem({
path: {
customerId: '1234567890'
},
data: {
product_id: '9876543210',
quantity: 1
}
});
console.log(response.data); // Assigned delivery item
Revoke Delivery Item
Revoke a delivery item from a customer.
await client.delivery.revokeDeliveryItem({
path: {
customerId: '1234567890',
deliveryItemId: '1111111111'
}
});
// Returns 204 No Content on success
Example: Customer Management
import { createManagementClient, isPayNowError } from '@paynow-gg/typescript-sdk';
const client = createManagementClient(
process.env.STORE_ID!,
process.env.API_KEY!
);
async function manageCustomers() {
try {
// Search for a customer
const customers = await client.customers.getCustomers({
params: {
search: '[email protected]',
limit: 10
}
});
if (customers.data.length === 0) {
// Create new customer if not found
const newCustomer = await client.customers.createCustomer({
data: {
email: '[email protected]',
name: 'John Doe',
platform_accounts: [{
platform: 'steam',
identifier: '76561198000000000'
}]
}
});
console.log('Created customer:', newCustomer.data.id);
} else {
const customer = customers.data[0];
console.log('Found customer:', customer.id);
// Update customer metadata
await client.customers.updateCustomer({
path: { customerId: customer.id },
data: {
metadata: {
last_login: new Date().toISOString(),
status: 'active'
}
}
});
}
} catch (error) {
if (isPayNowError(error)) {
console.error('API Error:', error.response?.data);
} else {
throw error;
}
}
}
manageCustomers();
Example: Lookup and Grant Items
async function grantItemToPlayer(steamId: string, productId: string) {
try {
// Lookup customer by Steam ID
const customer = await client.customers.lookupCustomer({
params: {
platform: 'steam',
platform_id: steamId
}
});
if (!customer.data) {
console.log('Customer not found, creating new account');
const newCustomer = await client.customers.createCustomer({
data: {
platform_accounts: [{
platform: 'steam',
identifier: steamId
}]
}
});
// Assign item to new customer
await client.delivery.assignDeliveryItem({
path: { customerId: newCustomer.data.id },
data: { product_id: productId, quantity: 1 }
});
console.log('Item granted to new customer');
} else {
// Assign item to existing customer
await client.delivery.assignDeliveryItem({
path: { customerId: customer.data.id },
data: { product_id: productId, quantity: 1 }
});
console.log('Item granted to existing customer');
}
} catch (error) {
if (isPayNowError(error)) {
console.error('Failed to grant item:', error.response?.data);
}
throw error;
}
}
await grantItemToPlayer('76561198000000000', '9876543210');
- Orders - View customer order history
- Analytics - Track customer analytics and payments
- Storefront API - Customer-facing API using customer tokens