Customers

Manage customer accounts and data in your PayNow store

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: '[e-mail]', // 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 return
• search (optional): Search by customer email or name
• after (optional): Return customers after this ID (cursor-based pagination)
• before (optional): Return customers before this ID
• asc (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: '[e-mail]',
    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 address
• name: Customer’s display name
• platform_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 update
• data (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: '[e-mail]',
        name: 'User One',
        platform_accounts: [{
          platform: 'steam',
          identifier: '76561198000000001'
        }]
      },
      {
        email: '[e-mail]',
        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

The generated token can be used to authenticate Storefront API requests on behalf of the customer.

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: '[e-mail]',
        limit: 10
      }
    });

    if (customers.data.length === 0) {
      // Create new customer if not found
      const newCustomer = await client.customers.createCustomer({
        data: {
          email: '[e-mail]',
          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');

Related Resources

• Orders - View customer order history
• Analytics - Track customer analytics and payments
• Storefront API - Customer-facing API using customer tokens