JavaScript SDK
Checkouts
Checkouts create hosted payment pages for your customers.
Checkouts create hosted payment pages for your customers. When a checkout completes successfully, an Order is created.
For all fields and options, see the Checkouts API reference. The OpenAPI spec is also available for tooling.
The Checkout resource
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier for the checkout (checkout_…). |
resource | string | Always checkout. |
status | string | created, paid, canceled, failed, or expired. |
customerId | string | null | The customer this checkout is for, if known. |
orderId | string | null | Order ID, available after successful payment. |
redirectUrlSuccess | string | Where the customer returns on success. |
redirectUrlCanceled | string | Where the customer returns on cancel. |
metadata | object | null | Your custom key/value metadata. |
expiresAt | string | null | Expiration timestamp (ISO 8601). |
createdAt | string | Creation timestamp (ISO 8601). |
testmode | boolean | Whether this is a test checkout. |
links.checkoutUrl | Link | The hosted page to send the customer to. |
Create a checkout
POST /v1/checkouts
Required attributes
| Name | Type | Description |
|---|---|---|
products | array | Product items to sell. Each item is { id, quantity }, where id is a subscription_plan_… or one_off_product_… id. |
redirectUrlSuccess | string | Success redirect URL. |
redirectUrlCanceled | string | Cancel redirect URL. |
Optional attributes
| Name | Type | Description |
|---|---|---|
customerId | string | Attach the checkout to an existing customer. |
metadata | object | Custom metadata echoed back on the checkout and resulting order. |
const checkout = await vatly.checkouts.create({
redirectUrlSuccess: "https://yourapp.com/success",
redirectUrlCanceled: "https://yourapp.com/canceled",
products: [{ id: "subscription_plan_abc123", quantity: 1 }],
customerId: "customer_abc123",
metadata: { signupId: "su_42" },
});
// Send the customer here:
redirect(checkout.links.checkoutUrl.href);
Retrieve a checkout
GET /v1/checkouts/{checkoutId}
const checkout = await vatly.checkouts.get("checkout_abc123");
List checkouts
GET /v1/checkouts
const page = await vatly.checkouts.list({ limit: 25 });
for await (const checkout of vatly.checkouts.listAll()) {
// ...
}