Checkouts.md

Checkouts

Create a hosted payment page and redirect your buyer to it. A checkout can contain one-off products, subscription plans, or both. Use IDs from your own product catalog. Examples accept the client from setup.

Create a payment page

from vatly import RequestOptions, VatlyClient
from vatly.models import CreateCheckoutRequest


def example(client: VatlyClient):
    checkout = client.checkouts.create(
        CreateCheckoutRequest(
            products=[{"id": "one_off_product_example", "quantity": 1}],
            redirect_url_success="https://app.example.com/billing/success",
            redirect_url_canceled="https://app.example.com/billing/canceled",
            customer_id="customer_example",
        ),
        options=RequestOptions(idempotency_key="purchase:order-42"),
    )
    return checkout.id, checkout.links.checkout_url.href

Persist the purchase key before calling Vatly and reuse it after a timeout. A new key can create a second purchase. The raw SDK Checkout has no get_url() method; that convenience belongs to Fluent.

Input model field	Wire key	Required?
products	products	Yes: items with id, positive quantity; optional trialDays for plans
redirect_url_success	redirectUrlSuccess	Yes
redirect_url_canceled	redirectUrlCanceled	Yes
customer_id	customerId	No: an authorized existing customer
locale, metadata, billing_address	locale, metadata, billingAddress	No

Pydantic inputs accept Python names. Dictionary inputs use wire keys, including trialDays inside product dictionaries. Omit customer_id for a guest checkout.

Read a checkout or traverse pages

from vatly import VatlyClient


def example(client: VatlyClient):
    checkout = client.checkouts.get("checkout_example")
    page = client.checkouts.list({"limit": 10})
    ids = [item.id for item in client.checkouts.list_all({"limit": 25})]
    return checkout.order_id, page.count, ids

Response field	Meaning
id, status, testmode	Identifier, payment state and mode
customer_id	Customer when assigned; may be None
order_id	Read this Order for purchased lines; may be None before payment
links.checkout_url.href	Hosted checkout destination

The success redirect is not payment confirmation. Use signed webhooks and your own ownership records. Checkout responses do not contain a products array.

Checkout API reference · All methods