createManagementClient

Function Signature

function createManagementClient(
  storeId: string,
  apiKey: string,
  options?: CreateAxiosDefaults,
): ManagementClient

Description

Creates and configures a client for interacting with the PayNow Management API. The Management API provides administrative operations for managing your store, including product management, order processing, customer administration, and analytics.

Management API keys provide full access to your store’s administrative functions. Store them securely and never expose them in client-side code.

Parameters

storeId

string

required

Your PayNow store identifier. This is used to scope all API requests to your specific store.

apiKey

string

required

Your PayNow Management API key. This key provides authenticated access to administrative operations.Security best practices:

Store API keys in environment variables, never in source code
Use different keys for development and production environments
Rotate keys periodically
Restrict key permissions to only what’s needed
Never expose management keys in client-side code

The key is automatically formatted with the APIKey prefix in the Authorization header.

options

CreateAxiosDefaults

Additional Axios configuration options to customize the HTTP client behavior.Common options:

timeout: Request timeout in milliseconds
headers: Additional HTTP headers to include in all requests
baseURL: Override the default API base URL (defaults to https://api.paynow.gg)
validateStatus: Custom function to determine if a status code should resolve or reject

See Axios documentation for all available options.

Returns

ManagementClient

object

A typed client instance with grouped API operations. Operations are organized by resource type (e.g., products, orders, customers, analytics) and accessed using dot notation.Example structure:

{
  products: {
    list: (config?) => Promise<AxiosResponse<Product[]>>,
    create: (config) => Promise<AxiosResponse<Product>>,
    update: (config) => Promise<AxiosResponse<Product>>,
    delete: (config) => Promise<AxiosResponse<void>>,
    // ... other product operations
  },
  orders: {
    list: (config?) => Promise<AxiosResponse<Order[]>>,
    get: (config) => Promise<AxiosResponse<Order>>,
    // ... other order operations
  },
  customers: {
    list: (config?) => Promise<AxiosResponse<Customer[]>>,
    get: (config) => Promise<AxiosResponse<Customer>>,
    // ... other customer operations
  },
  analytics: {
    getRevenue: (config?) => Promise<AxiosResponse<Analytics>>,
    // ... other analytics operations
  }
}

Each operation returns an Axios response with the typed data in the data property.

Usage Examples

Basic Client Setup

import { createManagementClient } from '@paynow/sdk';

// Create a management client with your API key
const client = createManagementClient(
  'your-store-id',
  process.env.PAYNOW_API_KEY // Load from environment variables
);

// List all products
const products = await client.products.list();
console.log(products.data);

// Get store orders
const orders = await client.orders.list({
  params: {
    status: 'completed',
    limit: 50
  }
});
console.log(orders.data);

Creating and Managing Products

import { createManagementClient } from '@paynow/sdk';

const client = createManagementClient(
  'your-store-id',
  process.env.PAYNOW_API_KEY
);

// Create a new product
const newProduct = await client.products.create({
  data: {
    name: 'Premium Subscription',
    description: 'Access to all premium features',
    price: 2999, // Price in cents
    currency: 'USD'
  }
});

console.log('Created product:', newProduct.data);

// Update the product
const updatedProduct = await client.products.update({
  path: {
    productId: newProduct.data.id
  },
  data: {
    price: 2499 // Discounted price
  }
});

console.log('Updated product:', updatedProduct.data);

Managing Orders

import { createManagementClient } from '@paynow/sdk';

const client = createManagementClient(
  'your-store-id',
  process.env.PAYNOW_API_KEY
);

// Get a specific order
const order = await client.orders.get({
  path: {
    orderId: 'order_123'
  }
});

console.log('Order details:', order.data);

// Filter orders by date range
const recentOrders = await client.orders.list({
  params: {
    startDate: '2024-01-01',
    endDate: '2024-01-31',
    status: 'completed'
  }
});

console.log(`Found ${recentOrders.data.length} orders`);

With Custom Configuration

import { createManagementClient } from '@paynow/sdk';

// Create a client with custom options
const client = createManagementClient(
  'your-store-id',
  process.env.PAYNOW_API_KEY,
  {
    timeout: 10000, // 10 second timeout for long-running operations
    headers: {
      'X-Request-Source': 'backend-service'
    }
  }
);

// Client uses custom configuration for all requests
const analytics = await client.analytics.getRevenue({
  params: {
    period: 'month'
  }
});

Error Handling

import { createManagementClient } from '@paynow/sdk';
import { AxiosError } from 'axios';

const client = createManagementClient(
  'your-store-id',
  process.env.PAYNOW_API_KEY
);

try {
  const product = await client.products.create({
    data: {
      name: 'New Product',
      price: 1999,
      currency: 'USD'
    }
  });
  console.log('Product created:', product.data);
} catch (error) {
  if (error instanceof AxiosError) {
    if (error.response?.status === 401) {
      console.error('Authentication failed: Invalid API key');
    } else if (error.response?.status === 403) {
      console.error('Permission denied: API key lacks required permissions');
    } else if (error.response?.status === 422) {
      console.error('Validation error:', error.response.data);
    } else {
      console.error('API Error:', error.response?.status, error.response?.data);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Server-side Integration Example

import { createManagementClient } from '@paynow/sdk';
import express from 'express';

const app = express();

// Initialize the client once for reuse
const paynowClient = createManagementClient(
  process.env.PAYNOW_STORE_ID,
  process.env.PAYNOW_API_KEY
);

// Admin endpoint to create products
app.post('/admin/products', async (req, res) => {
  try {
    const product = await paynowClient.products.create({
      data: req.body
    });
    res.json(product.data);
  } catch (error) {
    if (error instanceof AxiosError) {
      res.status(error.response?.status || 500).json({
        error: error.response?.data
      });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

app.listen(3000);

Authentication Notes

The apiKey parameter is required for all Management API operations
API keys provide full administrative access to your store
The key is automatically formatted as APIKey <key> in the Authorization header
All requests are made over HTTPS to ensure security
Invalid or expired API keys will result in 401 Unauthorized responses
Management API keys should only be used in server-side applications

Security Warning: Never use Management API keys in client-side JavaScript, mobile apps, or any publicly accessible code. These keys provide full administrative access to your store.

Best Practices

Environment Variables

Always store API keys in environment variables, never hardcode them:

// ✅ Good
const client = createManagementClient(
  process.env.PAYNOW_STORE_ID,
  process.env.PAYNOW_API_KEY
);

// ❌ Bad
const client = createManagementClient(
  'store_123',
  'sk_live_abc123' // Never hardcode keys!
);

Client Reusability

Create the client once and reuse it throughout your application:

// lib/paynow.ts
export const paynowClient = createManagementClient(
  process.env.PAYNOW_STORE_ID,
  process.env.PAYNOW_API_KEY
);

// In your application
import { paynowClient } from './lib/paynow';
const products = await paynowClient.products.list();

Error Handling

Always implement comprehensive error handling:

try {
  const result = await client.products.create({ data });
  return result.data;
} catch (error) {
  if (error instanceof AxiosError) {
    // Handle specific HTTP errors
    switch (error.response?.status) {
      case 401:
        // Handle authentication errors
        break;
      case 422:
        // Handle validation errors
        break;
      default:
        // Handle other errors
    }
  }
  throw error;
}

Timeouts

Set appropriate timeouts for different operations:

const client = createManagementClient(
  process.env.PAYNOW_STORE_ID,
  process.env.PAYNOW_API_KEY,
  {
    timeout: 10000 // 10 seconds for bulk operations
  }
);

Management API Overview

Explore all available Management API operations

Authentication Guide

Learn about authentication and API key management

Error Handling

Handle errors effectively in your application

Storefront Client

Create a client for storefront operations

Client Functions

Storefront API

Management API

Types & Schemas

Error Handling

Function Signature

Description

Parameters

Returns

Usage Examples

Basic Client Setup

Creating and Managing Products

Managing Orders

With Custom Configuration

Error Handling

Server-side Integration Example

Authentication Notes

Best Practices

Management API Overview

Authentication Guide

Error Handling

Storefront Client

Build docs developers (and LLMs) love

Client Functions

Storefront API

Management API

Types & Schemas

Error Handling

​Function Signature

​Description

​Parameters

​Returns

​Usage Examples

​Basic Client Setup

​Creating and Managing Products

​Managing Orders

​With Custom Configuration

​Error Handling

​Server-side Integration Example

​Authentication Notes

​Best Practices

​Related

Management API Overview

Authentication Guide

Error Handling

Storefront Client

Build docs developers (and LLMs) love

Function Signature

Description

Parameters

Returns

Usage Examples

Basic Client Setup

Creating and Managing Products

Managing Orders

With Custom Configuration

Error Handling

Server-side Integration Example

Authentication Notes

Best Practices

Related