Billing objects

Subscriptions are built from four objects. This page lists their fields and endpoints. For how they fit together over a billing cycle, read Subscriptions.

All endpoints on this page need your secret key in the Authorization header, without Bearer. Base URL: https://api.moosyl.com. The full list of parameters and responses is in the API reference.

Lists and pagination

List endpoints accept page (default 1) and limit (default 20, max 100) and return:

{
  "data": [],
  "pagination": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 }
}

Single-object endpoints return { "data": { ... } }. The SDK unwraps data for you.

Products

A product groups the prices you charge for one offer.

A product is created in the environment of the key you use. Lists and lookups return the active products of that environment.

import { Moosyl } from "moosyl-sdk";

const moosyl = new Moosyl(process.env.MOOSYL_SECRET_KEY!);

const product = await moosyl.createProduct({ name: "Pro plan", description: "Everything in Pro" });
const { data: products } = await moosyl.listProducts();
const withPrices = await moosyl.getProduct(product.id);

curl -X POST https://api.moosyl.com/products \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro plan", "description": "Everything in Pro"}'

Archiving sets active to false. The product then disappears from lists and lookups and can't be updated or restored. Its prices and existing subscriptions are not changed.

Prices

A price is what a subscription bills: a whole amount in MRU every week, month or year.

The SDK has no price methods yet, so use HTTP:

curl -X POST https://api.moosyl.com/prices \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productId": "PRODUCT_ID", "amount": 1000, "interval": "monthly"}'

To list a product's prices, get the product: it includes its active prices.

Archiving a price hides it from lookups and from its product's price list. Subscriptions already on it keep billing.

Customers

A customer links your user to their subscriptions and invoices. Identify them with your own user ID in externalUserId.

Customers belong to your organization, so Sandbox and Production keys see the same customers.

const customer = await moosyl.createCustomer({ externalUserId: "user_abc123", phone: "22222222" });

const { data } = await moosyl.listCustomers({ externalUserId: "user_abc123" });

curl -X POST https://api.moosyl.com/customers \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId": "user_abc123", "phone": "22222222"}'

There's no get or delete endpoint: look a customer up with GET /customers?id=… or ?externalUserId=…. Creating a second customer with the same externalUserId fails. To create the customer and the subscription in one call, use createSubscriptionByExternalUser (see Subscriptions).

Invoices

Moosyl creates an invoice for each billing period of a subscription, with a payment request your customer pays. You can't create invoices through the API.

const { data: invoices } = await moosyl.listInvoices({ subscriptionId: subscription.id });

curl "https://api.moosyl.com/invoices?subscriptionId=SUBSCRIPTION_ID" \
  -H "Authorization: YOUR_SECRET_KEY"

To collect an unpaid invoice, send your customer to its payment request, for example with a checkout session created from paymentRequestId.

Next steps

• Subscriptions: create subscriptions and follow the billing cycle
• Webhooks: subscription-updated and payment-request-created events
• API reference: every parameter and response