Create hosted checkouts
Build a cart, then call create() to make the API request. The result is a full
SDK Checkout with Fluent's get_url() convenience. Pass the configured
vatly from Configuration to these functions.
Sell a one-off or mixed cart
from vatly import RequestOptions
from vatly_fluent import CustomerProfile, EntityRef, Vatly
async def example(vatly: Vatly):
checkout = (
await vatly.checkout_builder(CustomerProfile(vatly_id="customer_example"))
.with_items(
[
{"id": "one_off_product_example", "quantity": 2},
{"id": "subscription_plan_example", "quantity": 1},
]
)
.with_metadata({"purchaseId": "42"})
.for_entity(EntityRef("team", "42"))
.create(options=RequestOptions(idempotency_key="purchase:42"))
)
return checkout.id, checkout.get_url()
The customer and entity must already be authorized. Omit the profile for a guest
checkout. .for_entity() needs the checkout-record driver.
Start a subscription with a trial
from vatly import RequestOptions
from vatly_fluent import Vatly
async def example(vatly: Vatly):
return (
await vatly.subscribe()
.to_plan("subscription_plan_example")
.with_quantity(3)
.with_trial_days(14)
.in_testmode()
.create(options=RequestOptions(idempotency_key="trial:42"))
)
subscribe().create() creates a checkout, not an immediate subscription.
Use the general builder for mixed carts. Reusing a subscription builder replaces
its plan item rather than appending another.
| Builder method | Purpose |
|---|---|
with_items | Append detached cart items |
to_plan, with_quantity | Select one plan and a positive integer quantity |
with_trial_days, with_trial_ends_at | Trial length or aware deadline, rounded up to whole days |
with_redirect_url_success, with_redirect_url_canceled | Override default redirects |
with_locale, with_metadata, with_billing_address | Add checkout details |
payload | Inspect a detached wire-format dictionary without a request |
in_testmode, in_live_mode | Assert the existing key's mode |
Store the purchase key before the API call and reuse it after ambiguous failures,
including a local-save failure after remote success. The redirect does not prove
payment; use webhooks. Read lines through checkout.order_id's Order.