JavaScript SDK

Orders

Orders record checkout purchases and subscription renewals, including pending payments.

Orders record checkout purchases and subscription renewals, including pending payments. They carry invoice links and tax breakdowns, and let you create refunds and inspect chargebacks.

For all fields and options, see the Orders API reference. The OpenAPI spec is also available for tooling.

The Order resource

Name	Type	Description
`id`	`string`	Unique identifier (`order_…`).
`customerId`	`string \| null`	The customer this order belongs to.
`status`	`string`	`created`, `pending`, `paid`, `canceled`, or `expired`. Payment recovery is signaled by `order.payment_failed`, not a status of that name.
`total`	`Money`	Gross amount (incl. tax).
`subtotal`	`Money`	Net amount (excl. tax).
`reversedSubtotal`	`Money`	Net amount already reversed via refunds/chargebacks.
`refundableSubtotal`	`Money`	Net amount still refundable.
`taxSummary`	`array`	Per-rate VAT breakdown.
`lines`	`OrderLine[]`	Line items, incl. `productType` / `productId` and `relatedResources`.
`invoiceNumber`	`string \| null`	Assigned once the invoice is issued.
`paymentMethod`	`string \| null`	Payment method used.
`metadata`	`object \| null`	Custom metadata carried from the checkout.
`testmode`	`boolean`	Whether this is a test order.

lines[].relatedResources.subscriptionId names the subscription a signup, renewal or immediate-update line belongs to. productType / productId keep their meaning: a signup line references the plan (subscription_plan), a renewal or update line the subscription (subscription).

relatedResources is null on historical lines and on unrelated lines (one-off products, billing verification, authorization minimums). Older payloads may omit it.
subscriptionId is null on a signup line while its subscription is not yet available. A later orders.get returns the ID once it is.
An ID is not proof of activation or entitlement. Retrieve the subscription and check its status before granting access.

// For a paid checkout, use checkout.orderId.
const order = await vatly.orders.get("order_abc123");
for (const line of order.lines) {
  const subscriptionId = line.relatedResources?.subscriptionId; // string | null | undefined
  if (subscriptionId) {
    const subscription = await vatly.subscriptions.get(subscriptionId);
  }
}

Retrieve an order

GET /v1/orders/{orderId}

const order = await vatly.orders.get("order_abc123");
console.log(order.total.value, order.total.currency);

List orders

GET /v1/orders

const page = await vatly.orders.list({ limit: 25 });

for await (const order of vatly.orders.listAll()) {
  // ...
}

Invoice update link (hosted)

POST /v1/orders/{orderId}/invoice-update-link

Returns a hosted link where the customer can correct their invoice details (billing address, VAT number, company name).

const link = await vatly.orders.createInvoiceUpdateLink("order_abc123");
redirect(link.href);

Refunds on an order

Refunds are created against the order they belong to.

// Partial refund of specific items:
const refund = await vatly.orders.createRefund("order_abc123", {
  items: [
    { itemId: "order_item_abc123", amount: { value: "15.00", currency: "EUR" } },
  ],
});

// Full refund of the entire order:
const full = await vatly.orders.createFullRefund("order_abc123");

// List / get / cancel:
const page = await vatly.orders.listRefunds("order_abc123", { limit: 10 });
for await (const r of vatly.orders.listAllRefunds("order_abc123")) {
  // ...
}
const one = await vatly.orders.getRefund("order_abc123", "refund_abc123");
await vatly.orders.cancelRefund("order_abc123", "refund_abc123"); // only while pending

See Refunds for the top-level refund endpoints.

Chargebacks on an order

const page = await vatly.orders.listChargebacks("order_abc123");
const chargeback = await vatly.orders.getChargeback("order_abc123", "chargeback_abc123");

See Chargebacks for the top-level chargeback endpoints.

Edit this pageorReport an issue

Subscription plans

Subscription plans define recurring products, prices, and billing intervals.

One-off products

One-off products are single-purchase items (no recurring billing).