Vatly
Api Reference

Checkouts

On this page, we'll dive into the different checkout endpoints you can use to manage your checkouts programmatically.

The Checkout API Resource

Below you'll find all properties for the Vatly Checkout API resource.

Properties

NameTypeDescription
idstringUnique identifier for the checkout (starts with checkout_).
resourcestringThe resource type. Always checkout.
orderIdstring | nullUnique identifier for the order created from this checkout. Only available when the checkout has been paid successfully.
customerIdstringThe customer associated with this checkout. Only present once a customer has been associated — for an anonymous checkout this happens when the buyer completes payment.
testmodebooleanWhether this checkout is in test mode.
redirectUrlSuccessstringThe URL to which the checkout should redirect the user after the checkout has been paid successfully. May contain the literal {CHECKOUT_ID} placeholder, which Vatly substitutes with this checkout's ID at creation time (e.g. https://example.com/return?checkout_id={CHECKOUT_ID}).
redirectUrlCanceledstringThe URL to which the user should get redirected when the user cancels the checkout. Supports the same {CHECKOUT_ID} placeholder as redirectUrlSuccess.
metadataobject | nullArbitrary key-value metadata for your application. Up to 50 keys, with key names up to 40 characters and values up to 500 characters.
statusstringThe status of the checkout. Can be created, paid, canceled, failed, or expired.
expiresAtstring | nullWhen this checkout will expire (ISO 8601 format).
createdAtstringThe moment the checkout was created, in ISO 8601 format.
linksobjectHATEOAS links to related resources. Contains checkoutUrl (the hosted checkout page URL), self, and optionally order (after completion).

List all checkouts

GET /v1/checkouts

This endpoint allows you to retrieve a paginated list of all your checkouts. By default, a maximum of ten checkouts are shown per page.

Optional attributes

NameTypeDescription
limitintegerThe number of checkouts to return (default: 10, max: 100).
startingAfterstringA cursor for use in pagination. Returns results after this checkout ID.
endingBeforestringA cursor for use in pagination. Returns results before this checkout ID.
curl -G https://api.vatly.com/v1/checkouts \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

Create a checkout

POST /v1/checkouts

This endpoint allows you to start a new hosted Vatly Checkout. Make sure you have at least one subscription plan or one-off product configured in your Vatly account.

Once paid, any subscription plan product assigned to the checkout will kick off a new subscription for that plan.

Required attributes

NameTypeDescription
productsarrayAn array of product objects to include in this checkout. Each product can have: id (required, starts with one_off_product_ or subscription_plan_), quantity (optional, default: 1), price (optional, Money object), trialDays (optional, for subscription plans), metadata (optional).
redirectUrlSuccessstringThe URL to which the checkout should redirect the user after the checkout has been paid successfully. You may include the literal {CHECKOUT_ID} placeholder anywhere in the URL — Vatly substitutes it with this checkout's ID, so your return page can read the checkout ID without a server-side token store.
redirectUrlCanceledstringThe URL to which the user should get redirected when the user cancels the checkout. Supports the same {CHECKOUT_ID} placeholder.

Optional attributes

NameTypeDescription
metadataobjectArbitrary key-value metadata for your application.
customerIdstringThe ID for an existing customer to associate with this checkout. If provided, the customer's email will be pre-filled. Must match the testmode of the API token.
curl https://api.vatly.com/v1/checkouts \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH", "quantity": 1},
      {"id": "subscription_plan_Rk5pQrSvWm8NjLhYbUcP", "trialDays": 14}
    ],
    "redirectUrlSuccess": "https://example.com/return?checkout_id={CHECKOUT_ID}",
    "redirectUrlCanceled": "https://example.com/canceled"
  }'

Custom pricing

Charge an amount that differs from the product's dashboard price by setting price on the item — a Money object (value is a decimal string, currency an ISO 4217 code). The id still references a product you created in the dashboard; products cannot be created on the fly via the API. Omit price to use the product's configured price.

curl https://api.vatly.com/v1/checkouts \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
        "quantity": 2,
        "price": {"value": "49.99", "currency": "EUR"}
      }
    ],
    "redirectUrlSuccess": "https://example.com/success",
    "redirectUrlCanceled": "https://example.com/canceled"
  }'
The full request and response schema — every accepted field and its validation rules — is published in the OpenAPI spec. Point your code generator or AI assistant at it when an example leaves a field ambiguous.

Retrieve a checkout

GET /v1/checkouts/:id

This endpoint allows you to retrieve a checkout by providing the checkout id. Refer to the list at the top of this page to see which properties are included with checkout objects.

curl https://api.vatly.com/v1/checkouts/checkout_QdEpFhdSrG4Y3DnfsdqsH \
  -H "Authorization: Bearer live_your_api_key_here"

Test helpers

Simulate subscription renewals in test mode so you can verify recurring billing flows end to end.

One-off Products

On this page, we'll dive into the different one-off product endpoints you can use to query your products programmatically.

Copyright © 2026