Management Operations - PayNow TypeScript SDK

Overview

The Management API allows you to programmatically manage your PayNow store. All Management API operations require authentication with an API key.

Management API operations require a valid API key. Never expose your API key in client-side code.

Authentication

Include your API key in the Authorization header:

const client = createClient<paths>({
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Product Management

List Products

Retrieve all products in your store:

const products = await client.GET('/v1/stores/{storeId}/products', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

if (products.data) {
  console.log(`Found ${products.data.length} products`);
}

Do NOT use this endpoint for displaying products on your storefront. Use the Storefront API instead.

Create Product

Define Product

Create a new product with basic information:

const product = await client.POST('/v1/stores/{storeId}/products', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    name: 'Premium Package',
    slug: 'premium-package',
    description: 'Access to premium features',
    price: 1999, // $19.99 in cents
    image_url: 'https://example.com/image.png',
    enabled_at: new Date().toISOString()
  }
});

Configure Options

Set subscription and removal settings:

const product = await client.POST('/v1/stores/{storeId}/products', {
  params: { path: { storeId: 'YOUR_STORE_ID' } },
  body: {
    name: 'Monthly VIP',
    price: 999,
    allow_subscription: true,
    subscription_interval_value: 1,
    subscription_interval_scale: 'month',
    remove_after_enabled: true,
    remove_after_time_value: 30,
    remove_after_time_scale: 'day'
  }
});

Creating dynamic products during checkout without prior approval is prohibited per the User Agreement.

Update Product

Modify an existing product:

const updated = await client.PATCH('/v1/stores/{storeId}/products/{productId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      productId: 'PRODUCT_ID'
    }
  },
  body: {
    price: 2499, // Update price to $24.99
    description: 'Updated description'
  }
});

Delete Product

await client.DELETE('/v1/stores/{storeId}/products/{productId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      productId: 'PRODUCT_ID'
    }
  }
});

Order Management

List Orders

Retrieve all orders with optional filtering:

const orders = await client.GET('/v1/stores/{storeId}/orders', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

if (orders.data) {
  orders.data.forEach(order => {
    console.log('Order ID:', order.id);
    console.log('Total:', order.total_amount);
    console.log('Status:', order.status);
  });
}

Get Single Order

Retrieve detailed information about a specific order:

const order = await client.GET('/v1/stores/{storeId}/orders/{orderId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      orderId: 'ORDER_ID'
    }
  }
});

if (order.data) {
  console.log('Customer:', order.data.customer);
  console.log('Lines:', order.data.lines);
  console.log('Payment:', order.data.payment);
}

Refund Order

Issue a full or partial refund:

const refund = await client.POST('/v1/stores/{storeId}/orders/{orderId}/refund', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      orderId: 'ORDER_ID'
    }
  },
  body: {
    amount: 1999, // Refund amount in cents
    reason: 'Customer requested refund'
  }
});

Refunds cannot be undone. Ensure you have the correct order ID and amount.

Customer Management

List Customers

const customers = await client.GET('/v1/stores/{storeId}/customers', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

Get Customer

Retrieve a specific customer:

const customer = await client.GET('/v1/stores/{storeId}/customers/{customerId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      customerId: 'CUSTOMER_ID'
    }
  }
});

Lookup Customer

Find a customer by their platform ID:

const customer = await client.GET('/v1/stores/{storeId}/customers/lookup', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' },
    query: {
      platform: 'steam',
      platform_id: '76561198152492642'
    }
  }
});

Create Customer

const customer = await client.POST('/v1/stores/{storeId}/customers', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    steam_id: '76561198152492642',
    name: 'John Doe',
    metadata: {
      'source': 'api',
      'notes': 'VIP customer'
    }
  }
});

Update Customer

const updated = await client.PATCH('/v1/stores/{storeId}/customers/{customerId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      customerId: 'CUSTOMER_ID'
    }
  },
  body: {
    name: 'Updated Name',
    metadata: {
      'tier': 'gold'
    }
  }
});

Bulk Create Customers

Create up to 200 customers at once:

const result = await client.POST('/v1/stores/{storeId}/customers/bulk', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    customers: [
      { steam_id: '76561198152492642', name: 'Player 1' },
      { steam_id: '76561198152492643', name: 'Player 2' }
    ]
  }
});

Delivery Item Management

Get Customer Delivery Items

const items = await client.GET('/v1/stores/{storeId}/customers/{customerId}/delivery/items', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      customerId: 'CUSTOMER_ID'
    }
  }
});

Assign Delivery Item

Manually assign a product to a customer:

const item = await client.POST('/v1/stores/{storeId}/customers/{customerId}/delivery/items', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      customerId: 'CUSTOMER_ID'
    }
  },
  body: {
    product_id: 'PRODUCT_ID',
    quantity: 1,
    execute_on_gameserver_id: 'GAMESERVER_ID' // Optional
  }
});

Revoke Delivery Item

await client.DELETE('/v1/stores/{storeId}/customers/{customerId}/delivery/items/{deliveryItemId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      customerId: 'CUSTOMER_ID',
      deliveryItemId: 'ITEM_ID'
    }
  },
  body: {
    reason: 'Violation of terms'
  }
});

Bulk Assign Delivery Items

const result = await client.POST('/v1/stores/{storeId}/delivery/items', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    assignments: [
      {
        customer_id: 'CUSTOMER_1',
        product_id: 'PRODUCT_ID',
        quantity: 1
      },
      {
        customer_id: 'CUSTOMER_2',
        product_id: 'PRODUCT_ID',
        quantity: 2
      }
    ]
  }
});

Subscription Management

List Subscriptions

const subscriptions = await client.GET('/v1/stores/{storeId}/subscriptions', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

Get Subscription

const subscription = await client.GET('/v1/stores/{storeId}/subscriptions/{subscriptionId}', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      subscriptionId: 'SUBSCRIPTION_ID'
    }
  }
});

Cancel Subscription

await client.POST('/v1/stores/{storeId}/subscriptions/{subscriptionId}/cancel', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      subscriptionId: 'SUBSCRIPTION_ID'
    }
  }
});

Coupons & Gift Cards

Create Coupon

const coupon = await client.POST('/v1/stores/{storeId}/coupons', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    code: 'SUMMER2024',
    discount_type: 'percent',
    discount_amount: 2000, // 20% in basis points
    max_uses: 100,
    expires_at: '2024-08-31T23:59:59Z'
  }
});

List Coupons

const coupons = await client.GET('/v1/stores/{storeId}/coupons', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

Create Gift Card

const giftcard = await client.POST('/v1/stores/{storeId}/giftcards', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    starting_balance: 5000, // $50.00 in cents
    expires_at: '2025-12-31T23:59:59Z'
  }
});

if (giftcard.data) {
  console.log('Gift Card Code:', giftcard.data.code);
}

Sales Management

Create Sale

const sale = await client.POST('/v1/stores/{storeId}/sales', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    name: 'Holiday Sale',
    discount_type: 'percent',
    discount_amount: 2500, // 25% in basis points
    begins_at: '2024-12-01T00:00:00Z',
    ends_at: '2024-12-31T23:59:59Z',
    product_ids: ['PRODUCT_1', 'PRODUCT_2']
  }
});

Game Server Management

Create Game Server

const server = await client.POST('/v1/stores/{storeId}/gameservers', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    name: 'US East Server',
    enabled: true
  }
});

if (server.data) {
  console.log('Server Token:', server.data.token);
}

List Game Servers

const servers = await client.GET('/v1/stores/{storeId}/gameservers', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

Custom Variables

Create Custom Variable

const variable = await client.POST('/v1/stores/{storeId}/custom-variables', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    identifier: 'player_name',
    name: 'Player Name',
    description: 'Enter your in-game name',
    type: 'text',
    value_regex: '^[a-zA-Z0-9_]{3,16}$'
  }
});

const variable = await client.POST('/v1/stores/{storeId}/custom-variables', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    identifier: 'server_choice',
    name: 'Server Selection',
    description: 'Choose your preferred server',
    type: 'dropdown',
    options: [
      { name: 'US East', value: 'us-east', price: 0, is_default: true },
      { name: 'EU West', value: 'eu-west', price: 500 } // +$5.00
    ]
  }
});

Analytics & Reporting

Get Payments

const payments = await client.GET('/v1/stores/{storeId}/payments', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

if (payments.data) {
  const total = payments.data.reduce((sum, p) => sum + p.amount, 0);
  console.log('Total Revenue:', total);
}

Get Order Delivery Items

const items = await client.GET('/v1/stores/{storeId}/orders/{orderId}/delivery/items', {
  params: {
    path: {
      storeId: 'YOUR_STORE_ID',
      orderId: 'ORDER_ID'
    }
  }
});

Webhooks

List Webhook Subscriptions

const webhooks = await client.GET('/v1/stores/{storeId}/webhooks', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  }
});

Create Webhook Subscription

const webhook = await client.POST('/v1/stores/{storeId}/webhooks', {
  params: {
    path: { storeId: 'YOUR_STORE_ID' }
  },
  body: {
    url: 'https://yourserver.com/webhooks',
    events: ['ON_ORDER_COMPLETED', 'ON_SUBSCRIPTION_RENEWED']
  }
});

Learn More About Webhooks

See the webhooks guide for detailed event handling

Best Practices

Rate Limiting: Implement exponential backoff for retries
Error Handling: Always check response status and handle errors gracefully
Pagination: Use pagination parameters for large datasets
Idempotency: Store order/transaction IDs to prevent duplicates
Testing: Use test mode for development and testing
Security: Never expose API keys in client-side code
Logging: Log all API interactions for debugging and auditing

Common Patterns

Complete Order Processing

async function processOrder(orderId: string) {
  // 1. Get order details
  const order = await client.GET('/v1/stores/{storeId}/orders/{orderId}', {
    params: { path: { storeId: 'STORE_ID', orderId } }
  });

  if (!order.data) return;

  // 2. Get delivery items
  const items = await client.GET('/v1/stores/{storeId}/orders/{orderId}/delivery/items', {
    params: { path: { storeId: 'STORE_ID', orderId } }
  });

  // 3. Process each item
  items.data?.forEach(item => {
    console.log('Deliver:', item.product.name, 'to', order.data.customer.name);
  });
}

Get Started

Core Concepts

Guides

Documentation Index

​Overview

​Authentication

​Product Management

​List Products

​Create Product

​Update Product

​Delete Product

​Order Management

​List Orders

​Get Single Order

​Refund Order

​Customer Management

​List Customers

​Get Customer

​Lookup Customer

​Create Customer

​Update Customer

​Bulk Create Customers

​Delivery Item Management

​Get Customer Delivery Items

​Assign Delivery Item

​Revoke Delivery Item

​Bulk Assign Delivery Items

​Subscription Management

​List Subscriptions

​Get Subscription

​Cancel Subscription

​Coupons & Gift Cards

​Create Coupon

​List Coupons

​Create Gift Card

​Sales Management

​Create Sale

​Game Server Management

​Create Game Server

​List Game Servers

​Custom Variables

​Create Custom Variable

​Create Dropdown Variable

​Analytics & Reporting

​Get Payments

​Get Order Delivery Items

​Webhooks

​List Webhook Subscriptions

​Create Webhook Subscription

Learn More About Webhooks

​Best Practices

​Common Patterns

​Complete Order Processing

​Next Steps

Storefront Operations

Webhooks

Overview

Authentication

Product Management

List Products

Create Product

Update Product

Delete Product

Order Management

List Orders

Get Single Order

Refund Order

Customer Management

List Customers

Get Customer

Lookup Customer

Create Customer

Update Customer

Bulk Create Customers

Delivery Item Management

Get Customer Delivery Items

Assign Delivery Item

Revoke Delivery Item

Bulk Assign Delivery Items

Subscription Management

List Subscriptions

Get Subscription

Cancel Subscription

Coupons & Gift Cards

Create Coupon

List Coupons

Create Gift Card

Sales Management

Create Sale

Game Server Management

Create Game Server

List Game Servers

Custom Variables

Create Custom Variable

Create Dropdown Variable

Analytics & Reporting

Get Payments

Get Order Delivery Items

Webhooks

List Webhook Subscriptions

Create Webhook Subscription

Best Practices

Common Patterns

Complete Order Processing

Next Steps