SDK v2 Billing

The v2 namespace is the recommended SDK surface for new merchant billing integrations. It maps to /api/v2/*.

Legacy SDK namespaces

client.intents, terminals, and the old merchant stats APIs remain available for existing integrations, but they are legacy and deprecated in future. Prefer client.v2 for new checkout and billing work.

Node.js

import {StendlyClient} from '@stendly/sdk';

const client = new StendlyClient({
  apiKey: process.env.STENDLY_API_KEY!,
  environment: 'devnet'
});

const product = await client.v2.createProduct({
  projectId: process.env.STENDLY_PROJECT_ID!,
  name: 'VPN Pro',
  description: 'Monthly VPN access',
}, 'product-vpn-pro');

const price = await client.v2.createPrice({
  projectId: process.env.STENDLY_PROJECT_ID!,
  productId: product.id,
  name: 'VPN Pro monthly',
  unitAmountCents: 999,
  currency: 'USD',
  billingMode: 'subscription',
  recurringInterval: 'month',
}, 'price-vpn-pro-monthly');

const checkout = await client.v2.createCheckoutSession({
  projectId: process.env.STENDLY_PROJECT_ID!,
  priceId: price.id,
  mode: 'subscription',
  externalCustomerId: 'telegram_123456',
  customerEmail: 'customer@example.com',
  merchantReference: 'order_1001',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
}, 'checkout-order-1001');

console.log(checkout.checkoutUrl);

Python

from stendly import Client
from stendly.models import (
    CreateBillingProductRequest,
    CreateBillingPriceRequest,
    CreateCheckoutSessionRequest,
)
import os

client = Client(api_key=os.environ["STENDLY_API_KEY"], environment="devnet")
project_id = os.environ["STENDLY_PROJECT_ID"]

product = client.v2.create_product(
    CreateBillingProductRequest(
        project_id=project_id,
        name="AI token pack",
        description="Prepaid AI credits",
    ),
    idempotency_key="product-ai-token-pack",
)

price = client.v2.create_price(
    CreateBillingPriceRequest(
        project_id=project_id,
        product_id=product.id,
        name="10,000 AI credits",
        unit_amount_cents=1000,
        currency="USD",
        billing_mode="balance_top_up",
        credit_amount=10000,
    ),
    idempotency_key="price-ai-credits-10000",
)

checkout = client.v2.create_checkout_session(
    CreateCheckoutSessionRequest(
        project_id=project_id,
        price_id=price.id,
        mode="balance_top_up",
        external_customer_id="user_123",
        merchant_reference="topup_1001",
        success_url="https://example.com/success",
        cancel_url="https://example.com/cancel",
    ),
    idempotency_key="checkout-topup-1001",
)

print(checkout.checkout_url)

.NET

using Stendly;
using Stendly.Models;

var client = new StendlyClient(new HttpClient(), Environment.GetEnvironmentVariable("STENDLY_API_KEY")!, "devnet");
var projectId = Guid.Parse(Environment.GetEnvironmentVariable("STENDLY_PROJECT_ID")!);

var product = await client.V2.CreateProductAsync(
    new CreateBillingProductRequest(
        ProjectId: projectId,
        Name: "Online order",
        Description: "Single purchase"
    ),
    idempotencyKey: "product-online-order"
);

var price = await client.V2.CreatePriceAsync(
    new CreateBillingPriceRequest(
        ProjectId: projectId,
        ProductId: product.Id,
        UnitAmountCents: 4999,
        Name: "Standard order",
        Currency: "USD",
        BillingMode: "one_time"
    ),
    idempotencyKey: "price-online-order"
);

var checkout = await client.V2.CreateCheckoutSessionAsync(
    new CreateCheckoutSessionRequest(
        ProjectId: projectId,
        PriceId: price.Id,
        Mode: "one_time",
        MerchantReference: "order_1001",
        SuccessUrl: "https://example.com/success",
        CancelUrl: "https://example.com/cancel"
    ),
    idempotencyKey: "checkout-order-1001"
);

Console.WriteLine(checkout.CheckoutUrl);

v2 methods

Area	Methods
Overview	overview
Projects	listProjects, retrieveProject, createProject, updateProject, deleteProject
Customers	listCustomers, retrieveCustomer, createCustomer
Products	listProducts, retrieveProduct, createProduct, updateProduct
Prices	listPrices, retrievePrice, createPrice, updatePrice
Checkout sessions	listCheckoutSessions, retrieveCheckoutSession, createCheckoutSession
Invoices	listInvoices, retrieveInvoice
Subscriptions	listSubscriptions, retrieveSubscription, updateSubscription, cancelSubscription, previewSubscriptionChange
Usage	listUsage, recordUsage
Portal sessions	createPortalSession
Webhook deliveries	listWebhookDeliveries, retrieveWebhookDelivery, resendWebhookDelivery

Website examples

Use these examples when you need a complete website checkout flow:

• examples/v2-node
• examples/v2-python
• examples/v2-dotnet

They cover all three checkout modes, catalog setup, usage recording, webhook receiver, signature verification, and local order status sync.