@cosmosapp/pay_sdkServer

Products & customers

Manage your product catalog and customers, including their payment statistics.

Products and customers are optional catalogs you can attach to payments to organise and report on them.

Products / prices — client.products

import { ProductKind } from '@cosmosapp/pay_sdk';

const product = await client.products.create({
  name: 'Pro plan — monthly',
  description: 'Priority support included.', // optional
  amount: '49.00',                           // optional — omit for customer-set amount
  assetCode: 'USDC',                         // optional — omit for native XLM
  kind: ProductKind.Recurring,               // 'recurring' | 'one_time' | 'link'
  reference: 'sku_pro_monthly',              // optional
});

await client.products.list();
await client.products.fetch(product.id);
await product.edit({ amount: '59.00' });
await product.deactivate(); // active = false
await product.activate();   // active = true
await product.delete();

Product accessors: id, name, description, amount, asset, assetLabel, kind, active, reference, createdAt, updatedAt.

Customers — client.customers

const customer = await client.customers.create({
  name: 'Acme Inc.',
  email: 'billing@acme.com',  // optional
  alias: 'acme',              // optional
  wallets: [                  // optional, up to 20, on Stellar, Solana or Monad
    { chain: 'stellar', address: 'G...' },
    { chain: 'solana', address: '7EcD...', label: 'Phantom' },
  ],
  reference: 'crm_4821',      // optional
});

await customer.edit({ note: 'VIP, net-30' });
await client.customers.fetch(customer.id);
await customer.delete();

// list() includes payment stats per customer:
const customers = await client.customers.list();
for (const c of customers) {
  console.log(c.name, c.payments, c.succeeded, c.total);
}

Customer accessors: id, name, alias, note, email, wallets, account (deprecated: the first wallet's address), reference, createdAt, updatedAt, plus list-only stats payments, succeeded, total (null outside list()).

Customer wallets

A customer holds any number of wallets (up to 20) on Stellar, Solana or Monad; payment intents paid from any of them count toward the customer. A wallet belongs to one customer: one that another of your customers holds answers 409 customer_wallet_taken. account on create still works but is deprecated: use wallets.

// On the instance: the wallet is added to (or removed from) customer.wallets too.
const wallet = await customer.addWallet({ chain: 'monad', address: '0x5aAe...', label: 'Treasury' });
await customer.removeWallet(wallet);        // or customer.removeWallet(wallet.id)

// On the manager, by id:
await client.customers.addWallet(customer.id, { chain: 'stellar', address: 'G...' });
await client.customers.removeWallet(customer.id, 'cw4f0c2a9d...'); // { id, deleted: true }

addWallet returns the wallet ({ id, chain, address, label, createdAt }); a wallet the customer already holds answers as it is. Removing one stops its payments counting toward the customer; a later settled payment from it adds it as a new automatic customer.

References

  • Customer: A customer record, optionally enriched with on-chain payment stats.
  • Product: A product / price the consumer can charge for.

On this page