Console

Start

Platform

App store purchases

Auth

Builds

Database

Flags

Hosting

Jobs and cron

Localization

Monitoring

Network

Notifications

Organizations

Payments

Queues

Events

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

Request
CheckoutSession
ResourceMeta
Subject
LineItem
Response
ResourceMeta
Subject
LineItem
Errors
Examples

Reference

Create a checkout session

Creates a hosted checkout for a subject.

Checked 2026-09-28

Creates a hosted checkout for a subject.

Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/checkout_sessions
Scope billing:write
Effect write — a successful call changes state.
Collection checkout_sessions
Query checkout_session_id

#Request

Field	Type	What it is
`parent`	`string`	The parent to create in. Required.
`checkout_session`	`CheckoutSession`	The checkout to create; only caller-writable fields are read. Required.
`checkout_session_id`	`string`	The id, the final name segment; the server assigns one when empty.

#CheckoutSession

Field	Type	What it is
`name`	`string`	`orgs/{org}/projects/{project}/envs/{env}/checkout_sessions/{checkout_session}`.
`meta`	`ResourceMeta`	Resource metadata.
`subject`	`Subject`	Who pays and is entitled. Required.
`line_items`	`LineItem[]`	What is bought: catalog prices by lookup key. One recurring price makes a subscription; one-time prices make an order. Required.
`success_url`	`string`	Where the buyer lands after paying; `{CHECKOUT_SESSION_ID}` is replaced by the processor's session id. HTTPS only. Required.
`cancel_url`	`string`	Where the buyer lands on cancel. HTTPS only.
`currency_code`	`string`	The currency to charge in, upper-case ISO 4217; default the processor's choice for the buyer among the prices' currencies.
`locale`	`string`	The page language, for example `en` or `zh-HK`; default automatic.
`metadata`	`map<string, string>`	Copied to the subscription or order, for example attribution (`utm_source`, `ref`). At most 20 keys.
`allow_promotion_codes`	`bool`	Whether the buyer may enter a promotion code.

#ResourceMeta

Field	Type	What it is
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.

#Subject

Field	Type	What it is
`end_user`	`string`	An end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the `kind` group.
`customer_organization`	`string`	A customer organization's id. One of the `kind` group.

#LineItem

Field	Type	What it is
`price`	`string`	The price's lookup key. Required.
`quantity`	`int32`	How many; default 1. Seats for a per-seat or family price.

#Response

Field	Type	What it is
`name`	`string`	`orgs/{org}/projects/{project}/envs/{env}/checkout_sessions/{checkout_session}`.
`uid`	`string`	`chk_<cell><ulid>`; never reused. Output only.
`meta`	`ResourceMeta`	Resource metadata.
`subject`	`Subject`	Who pays and is entitled. Required.
`line_items`	`LineItem[]`	What is bought: catalog prices by lookup key. One recurring price makes a subscription; one-time prices make an order. Required.
`success_url`	`string`	Where the buyer lands after paying; `{CHECKOUT_SESSION_ID}` is replaced by the processor's session id. HTTPS only. Required.
`cancel_url`	`string`	Where the buyer lands on cancel. HTTPS only.
`currency_code`	`string`	The currency to charge in, upper-case ISO 4217; default the processor's choice for the buyer among the prices' currencies.
`locale`	`string`	The page language, for example `en` or `zh-HK`; default automatic.
`metadata`	`map<string, string>`	Copied to the subscription or order, for example attribution (`utm_source`, `ref`). At most 20 keys.
`allow_promotion_codes`	`bool`	Whether the buyer may enter a promotion code.
`url`	`string`	The hosted page. Output only.
`state`	`string`	`open`, `complete`, or `expired`. Output only.
`expire_time`	`timestamp`	When the page stops accepting payment. Output only.
`processor_session_id`	`string`	The processor's session id. Output only.

#ResourceMeta

Field	Type	What it is
`generation`	`int64`	Increases by one on every change to `spec`. Output only.
`etag`	`string`	Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as `If-Match` or `etag` to make Update and Delete conditional; a mismatch fails with ABORTED / 409 `ETAG_MISMATCH`. Output only.
`create_time`	`timestamp`	When the Resource was created. Output only.
`update_time`	`timestamp`	When the Resource last changed. Output only.
`delete_time`	`timestamp`	Set while the Resource is being deleted. Output only.
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.
`creator`	`string`	The principal that created the Resource. Output only.

#Subject

Field	Type	What it is
`end_user`	`string`	An end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the `kind` group.
`customer_organization`	`string`	A customer organization's id. One of the `kind` group.

#LineItem

Field	Type	What it is
`price`	`string`	The price's lookup key. Required.
`quantity`	`int32`	How many; default 1. Seats for a per-seat or family price.

#Errors

UNAUTHENTICATED — No valid key or token was presented.
PERMISSION_DENIED — The key lacks the method's permission.
UNKNOWN_FIELD — The request has a field the schema does not know.
INVALID_FIELD — A field failed validation.
INVALID_STATE — The Resource is in a state that forbids the call.
UNAVAILABLE — The Resource store, the owning service's backend, or the key verifier's snapshot is unavailable; retry after Retry-After.
IDEMPOTENCY_KEY_REUSED — An Idempotency-Key was reused with another body.
IDEMPOTENCY_IN_PROGRESS — The first call with this Idempotency-Key is still running.

Every error arrives in the body Errors describes.

#Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/checkout_sessions" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"line_items":[{"price":"…"}],"subject":{},"success_url":"…"}'

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links