Skip to Content
FluxStore is currently invite-only. Some sections of this documentation are still being written and expanded.
APIManagement APICheckout SessionsCreate a checkout session
POST/api/v1/checkout/sessions

Create a new checkout session. Returns a hosted-checkout URL to redirect the customer to.

See the Checkout Sessions overview for the full flow, prerequisites, and idempotency rules.

Headers

X-Api-Keystringrequired
Your API key.
Idempotency-Keystring
Optional idempotency key. Reusing it on an open session returns the same session.
Content-Typestringrequired
Must be application/json.

Body

itemsobject[]required
Items to purchase. 1–50 entries.
customerobjectrequired
Customer info. This is who pays.
giftobject
Deliver this order’s goods to another player instead of the customer. See Gifting below.
couponCodestring
Optional discount coupon code.
giftCardCodestring
Optional gift card code (store credit). Unrelated to the gift object; a gift card pays for an order, gift redirects who receives it.
successUrlstring· urlrequired
HTTPS, origin must be in allow-list. Supports {CHECKOUT_SESSION_ID} and {ORDER_ID} placeholders.
cancelUrlstring· urlrequired
HTTPS, origin must be in allow-list. Supports {CHECKOUT_SESSION_ID}.
clientReferenceIdstring
Your internal reference ID; max 255 chars; echoed back on the session.
expiresInSecondsinteger
Session expiry, 60–86400. Defaults to 3600 (1 hour).

items[]

packageIdstring· uuidrequired
Active package on this store.
quantityinteger
1–100, default 1.
serverIdstring· uuid
Required if the package has userServerSelectionEnabled.

customer

playerUsernamestringrequired
Player in-game name, 3–32 chars.
playerUuidstring· uuid
Minecraft UUID, optional.
emailstring· email
If absent, customer enters it at checkout.

gift

recipientUsernamestringrequired
Player who receives the goods, 1–32 chars, no whitespace or control characters.
recipientUuidstring· uuid
Recipient’s Minecraft UUID. Optional - FluxStore resolves it server-side the same way it resolves customer.playerUuid, per the store’s player identity mode. In premium_required mode recipientUsername is always verified against Mojang/PlayerDB and any recipientUuid you supply is ignored (exactly like customer.playerUuid) - a username that doesn’t resolve to a real account is rejected with 400. In best_effort mode, a supplied value is trusted as-is; otherwise it’s looked up. In offline mode, a supplied value is stored as-is; otherwise this stays null.

Gifting is opt-in per store and off by default, so a gift object sent to a store that has not enabled it is rejected. See Gifting for what it changes, and Checkout Sessions for the response shape, warnings and rejections.

OverviewRetrieve a checkout session