Create a checkout session

Start a Laces-hosted checkout for one event and get the URL to send the buyer to.

POST /checkout-sessions

cURL

redirect

curl --request POST \
  --url https://connect.laces.run/v1/checkout-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_id": "q3Zk9mVx",
  "ui_mode": "redirect",
  "on_success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
  "on_cancel_url": "https://shop.example.com/events/kampala-city-10k",
  "client_reference_id": "cart-8841",
  "prefill": {
    "buyer_name": "Amina Nakato",
    "buyer_email": "[e-mail]"
  }
}
'

201

Example

{
  "code": 201,
  "message": "Checkout session created successfully",
  "data": {
    "id": "LCSCS-EXAMPLESESSN234EXAMPL",
    "url": "https://laces.run/checkout/LCSCS-EXAMPLESESSN234EXAMPL",
    "expires_at": "2026-10-10T08:14:03.000Z",
    "ui_mode": "redirect"
  }
}

Authorizations

bearerAuthoauth2publishableKey

Authorization · string · header · required

A token from POST /oauth/token, valid 1 hour. Paste it as LCSTOK-…-X (without the word Bearer).

Body

application/json

event_id · string · required

Your organization's event.

Example:

"q3Zk9mVx"

ui_mode · enum<string> · default: redirect

redirect (hosted page, the default) or embedded (laces.js modal).

Available options: redirect, embedded

on_success_url · string

Required for redirect, optional for embedded. Absolute https URL whose origin exactly matches one of your return URL domains (http://localhost:<port> / http://127.0.0.1:<port> only when registered). {CHECKOUT_SESSION_ID} (or %7BCHECKOUT_SESSION_ID%7D) is replaced with the session id; with no placeholder, session_id=<id> is added as a query parameter, overwriting any existing session_id.

Maximum string length: 2048

Example:

"https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}"

on_cancel_url · string<uri>

Required for redirect, optional for embedded. Same rules; used as given (no id added).

Maximum string length: 2048

Example:

"https://shop.example.com/events/kampala-city-10k"

embed_origin · string

Embedded sessions created with a bearer token only: the origin (https://host[:port]) of the page that will host the modal. Must be one of your allowed domains (400 invalid_embed_origin otherwise). With a publishable key the request's Origin is used and this field is ignored.

Example:

"https://shop.example.com"

client_reference_id · string

Your reference, returned when you read the session. Match it on verification.

Maximum string length: 256

Example:

"cart-8841"

prefill · object

Optional values to pre-fill on the checkout form.

Show child attributes

Response

201

application/json

The session.

code · integer · required

HTTP status, repeated in the body.

Example:

201

message · string · required

Example:

"Checkout session created successfully"

data · object · required

Show child attributes