Vatly
JavaScript SDK

SDK operation reference

Import VatlyClient from @getvatly/sdk.

Import VatlyClient from @getvatly/sdk. All paths below are relative to /v1. Every method takes optional RequestOptions last. For field details, see the API reference; the OpenAPI spec is also available for tooling. Bodies and results use generated types; server-side validation still applies. Types, components, paths, and operations are exported from the package root.

SDK methodHTTPPathResult
checkouts.list(params?)GET/checkoutsPage of Checkout
checkouts.create(body)POST/checkoutsCheckout
checkouts.get(id)GET/checkouts/{id}Checkout
customers.list(params?)GET/customersPage of Customer
customers.create(body)POST/customersCustomer (new or existing)
customers.get(id)GET/customers/{id}Customer
customers.update(id, body)PATCH/customers/{id}Customer
customers.createPortalSession(id, body?)POST/customers/{id}/portal-sessionsPortalSession
customers.listSubscriptions(id, params?)GET/customers/{id}/subscriptionsPage of Subscription
customers.getSubscription(id, subId)GET/customers/{id}/subscriptions/{subId}Subscription
oneOffProducts.list(params?)GET/one-off-productsPage of OneOffProduct
oneOffProducts.create(body)POST/one-off-productsOneOffProduct
oneOffProducts.get(id)GET/one-off-products/{id}OneOffProduct
oneOffProducts.update(id, body)PATCH/one-off-products/{id}OneOffProduct
oneOffProducts.archive(id)POST/one-off-products/{id}/archivevoid (204)
oneOffProducts.unarchive(id)DELETE/one-off-products/{id}/archiveOneOffProduct
subscriptionPlans.list(params?)GET/subscription-plansPage of SubscriptionPlan
subscriptionPlans.create(body)POST/subscription-plansSubscriptionPlan
subscriptionPlans.get(id)GET/subscription-plans/{id}SubscriptionPlan
subscriptionPlans.update(id, body)PATCH/subscription-plans/{id}SubscriptionPlan
subscriptionPlans.archive(id)POST/subscription-plans/{id}/archivevoid (204)
subscriptionPlans.unarchive(id)DELETE/subscription-plans/{id}/archiveSubscriptionPlan
orders.list(params?)GET/ordersPage of Order
orders.get(id)GET/orders/{id}Order
orders.createInvoiceUpdateLink(id)POST/orders/{id}/invoice-update-linkInvoiceUpdateLink (href, type)
orders.listRefunds(id, params?)GET/orders/{id}/refundsPage of Refund
orders.createRefund(id, body)POST/orders/{id}/refundsRefund
orders.createFullRefund(id, body?)POST/orders/{id}/refunds/fullRefund
orders.getRefund(id, refundId)GET/orders/{id}/refunds/{refundId}Refund
orders.cancelRefund(id, refundId)DELETE/orders/{id}/refunds/{refundId}void (204)
orders.listChargebacks(id, params?)GET/orders/{id}/chargebacksPage of Chargeback
orders.getChargeback(id, chargebackId)GET/orders/{id}/chargebacks/{chargebackId}Chargeback
refunds.list(params?)GET/refundsPage of Refund
refunds.get(id)GET/refunds/{id}Refund
chargebacks.list(params?)GET/chargebacksPage of Chargeback
chargebacks.get(id)GET/chargebacks/{id}Chargeback
webhookEvents.get(id)GET/webhook-events/{id}WebhookEvent
webhookEndpoints.list(params?)GET/webhook-endpointsPage of WebhookEndpoint
webhookEndpoints.create(body)POST/webhook-endpointsWebhookEndpoint
webhookEndpoints.get(id)GET/webhook-endpoints/{id}WebhookEndpoint
webhookEndpoints.update(id, body)PATCH/webhook-endpoints/{id}WebhookEndpoint
webhookEndpoints.delete(id)DELETE/webhook-endpoints/{id}void (204)
subscriptions.list(params?)GET/subscriptionsPage of Subscription
subscriptions.get(id)GET/subscriptions/{id}Subscription
subscriptions.update(id, body)PATCH/subscriptions/{id}Subscription
subscriptions.cancel(id)DELETE/subscriptions/{id}void (204)
subscriptions.createBillingUpdateLink(id, body)POST/subscriptions/{id}/billing-update-linkSubscriptionBillingUpdateLink (href, type)
subscriptions.resume(id)POST/subscriptions/{id}/resumeSubscription
testHelpers.fastForwardRenewal(id, body?)POST/test-helpers/subscriptions/{id}/fast-forward-renewalSubscription
testHelpers.simulateOrderPayment(id, body)POST/test-helpers/orders/{id}/simulate-paymentOrder

All top-level lists have a listAll(params?, opts?) async iterator. Nested subscription/refund lists have listAllSubscriptions / listAllRefunds. Pagination params: limit, startingAfter, endingBefore. Product/plan lists also accept includeArchived. Immediate cancellation uses subscriptions.cancel(id, { immediately: true, ...requestOptions }).

Alpha migration notes

  • Package scope changed to @getvatly/sdk (also @getvatly/sdk/webhooks).
  • Cancellation now accurately returns Promise<void>, not a subscription. Fetch the subscription afterward if needed.
  • Billing-update methods now return a hosted link, not a subscription. Deprecated updateBilling / requestAddressUpdateLink aliases still work.
  • The obsolete simulatePaymentFailure(transactionId) endpoint is removed; use simulateOrderPayment(orderId, { paymentStatus: "failed" }).
  • fastForwardRenewal now takes an optional body second and options third.
  • Optional fields with server defaults no longer need to be supplied in requests.
  • Errors can expose details; only in_progress idempotency conflicts retry.
  • Subscription updates require at least one of subscriptionPlanId, price, or quantity; trialUntil cannot stand alone. This is validated by the API.

Deterministic payment testing

Only test-mode keys are allowed (guarded before sending a request):

const subscription = await vatly.testHelpers.fastForwardRenewal("subscription_123", {
  paymentStatus: "failed",
  failureReason: "card_expired",
});
const order = await vatly.testHelpers.simulateOrderPayment("order_123", {
  paymentStatus: "paid",
});

Omitting the renewal body advances the cycle and leaves its payment pending. failureReason only applies with paymentStatus: "failed". These operations simulate payment outcomes; payment recovery remains managed by Vatly. See the testing guide for recovery timelines and event semantics.

Webhooks

Vatly sends webhooks to notify your application when events happen — an order being paid, a refund completing, a subscription being canceled.

Getting started

Create checkouts and manage billing with @getvatly/fluent on your server.

Copyright © 2026