--- title: "Create checkout intent" method: POST path: "/api/v1/checkout-intents" tags: ["Checkout Intents"] --- # Create checkout intent `POST /api/v1/checkout-intents` Create a checkout intent with the given request body. ## Request body - CheckoutIntentPostParams - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required ## Response `201` Created - union - RetrievingOfferCheckoutIntent - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required - `createdAt` string, date-time, required - `id` string, required - `state` 'retrieving_offer', required - AwaitingConfirmationCheckoutIntent - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required - `createdAt` string, date-time, required - `id` string, required - `paymentMethod` union - StripeTokenPaymentMethod - `stripeToken` string, required - `type` 'stripe_token', required - BasisTheoryPaymentMethod - `basisTheoryToken` string, required - `type` 'basis_theory_token', required - DrawdownPaymentMethod - `type` 'drawdown', required - X402PaymentMethod - `network` 'base' | 'solana' | 'tempo', required - `type` 'x402', required - `offer` Offer, required - `commission` CommissionPotential — The commission a developer would earn if this offer is placed. - `estimate` boolean, required - `amount` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Shipping, required - `availableOptions` ShippingOption[], required - `deliveryEstimate` DeliveryEstimate — Estimated range of dates that items will be delivered in. At least one of `earliest` or `latest` are guaranteed to be set. Interpretation: * If both `earliest` and `latest` are set, then the delivery estimate is the range between the two dates. * If only `earliest` is set, then the delivery estimate is any date after that date. * If only `latest` is set, then the delivery estimate is any date before that date. - `latest` string, date-time — Latest date that items will be delivered by. - `earliest` string, date-time — Earliest date that items will be delivered by. - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `cost` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `id` string, required - `selectedOptionId` string - `cost` Cost, required - `total` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `surcharge` Money - `currencyCode` string, required - `amountSubunits` integer, required - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `tax` Money - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Money - `currencyCode` string, required - `amountSubunits` integer, required - `subtotal` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `appliedPromoCodes` string[] - `state` 'awaiting_confirmation', required - RequiresActionCheckoutIntent - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required - `createdAt` string, date-time, required - `id` string, required - `nextAction` NextAction, required - `x402` object, required - `expiresAt` string, required - `recipient` string, required - `currency` 'USDC', required - `maxAmountRequired` string, required - `network` string, required - `scheme` 'exact', required - `type` 'x402', required - `paymentMethod` union, required - StripeTokenPaymentMethod - `stripeToken` string, required - `type` 'stripe_token', required - BasisTheoryPaymentMethod - `basisTheoryToken` string, required - `type` 'basis_theory_token', required - DrawdownPaymentMethod - `type` 'drawdown', required - X402PaymentMethod - `network` 'base' | 'solana' | 'tempo', required - `type` 'x402', required - `offer` Offer, required - `commission` CommissionPotential — The commission a developer would earn if this offer is placed. - `estimate` boolean, required - `amount` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Shipping, required - `availableOptions` ShippingOption[], required - `deliveryEstimate` DeliveryEstimate — Estimated range of dates that items will be delivered in. At least one of `earliest` or `latest` are guaranteed to be set. Interpretation: * If both `earliest` and `latest` are set, then the delivery estimate is the range between the two dates. * If only `earliest` is set, then the delivery estimate is any date after that date. * If only `latest` is set, then the delivery estimate is any date before that date. - `latest` string, date-time — Latest date that items will be delivered by. - `earliest` string, date-time — Earliest date that items will be delivered by. - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `cost` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `id` string, required - `selectedOptionId` string - `cost` Cost, required - `total` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `surcharge` Money - `currencyCode` string, required - `amountSubunits` integer, required - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `tax` Money - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Money - `currencyCode` string, required - `amountSubunits` integer, required - `subtotal` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `appliedPromoCodes` string[] - `state` 'requires_action', required - PlacingOrderCheckoutIntent - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required - `createdAt` string, date-time, required - `id` string, required - `paymentMethod` union, required - StripeTokenPaymentMethod - `stripeToken` string, required - `type` 'stripe_token', required - BasisTheoryPaymentMethod - `basisTheoryToken` string, required - `type` 'basis_theory_token', required - DrawdownPaymentMethod - `type` 'drawdown', required - X402PaymentMethod - `network` 'base' | 'solana' | 'tempo', required - `type` 'x402', required - `offer` Offer, required - `commission` CommissionPotential — The commission a developer would earn if this offer is placed. - `estimate` boolean, required - `amount` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Shipping, required - `availableOptions` ShippingOption[], required - `deliveryEstimate` DeliveryEstimate — Estimated range of dates that items will be delivered in. At least one of `earliest` or `latest` are guaranteed to be set. Interpretation: * If both `earliest` and `latest` are set, then the delivery estimate is the range between the two dates. * If only `earliest` is set, then the delivery estimate is any date after that date. * If only `latest` is set, then the delivery estimate is any date before that date. - `latest` string, date-time — Latest date that items will be delivered by. - `earliest` string, date-time — Earliest date that items will be delivered by. - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `cost` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `id` string, required - `selectedOptionId` string - `cost` Cost, required - `total` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `surcharge` Money - `currencyCode` string, required - `amountSubunits` integer, required - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `tax` Money - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Money - `currencyCode` string, required - `amountSubunits` integer, required - `subtotal` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `appliedPromoCodes` string[] - `state` 'placing_order', required - CompletedCheckoutIntent - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required - `createdAt` string, date-time, required - `id` string, required - `estimatedDeliveryDate` string, date-time, nullable - `orderId` string, nullable, required - `paymentMethod` union, required - StripeTokenPaymentMethod - `stripeToken` string, required - `type` 'stripe_token', required - BasisTheoryPaymentMethod - `basisTheoryToken` string, required - `type` 'basis_theory_token', required - DrawdownPaymentMethod - `type` 'drawdown', required - X402PaymentMethod - `network` 'base' | 'solana' | 'tempo', required - `type` 'x402', required - `offer` Offer, required - `commission` CommissionPotential — The commission a developer would earn if this offer is placed. - `estimate` boolean, required - `amount` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Shipping, required - `availableOptions` ShippingOption[], required - `deliveryEstimate` DeliveryEstimate — Estimated range of dates that items will be delivered in. At least one of `earliest` or `latest` are guaranteed to be set. Interpretation: * If both `earliest` and `latest` are set, then the delivery estimate is the range between the two dates. * If only `earliest` is set, then the delivery estimate is any date after that date. * If only `latest` is set, then the delivery estimate is any date before that date. - `latest` string, date-time — Latest date that items will be delivered by. - `earliest` string, date-time — Earliest date that items will be delivered by. - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `cost` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `id` string, required - `selectedOptionId` string - `cost` Cost, required - `total` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `surcharge` Money - `currencyCode` string, required - `amountSubunits` integer, required - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `tax` Money - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Money - `currencyCode` string, required - `amountSubunits` integer, required - `subtotal` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `appliedPromoCodes` string[] - `state` 'completed', required - FailedCheckoutIntent - `referenceId` string - `discoverPromoCodes` boolean - `constraints` CheckoutConstraints - `offerRetrievalEffort` 'max' | 'low' — Controls how much effort the system should spend retrieving an offer. - 'max': Full effort including AI agent fallback (slower, higher success rate) - 'low': Fast API-only retrieval, fails if API unavailable (faster, lower success rate) Default: 'max' - `maxShippingPrice` integer - `maxTotalPrice` integer - `promoCodes` PromoCode[] - `variantSelections` VariantSelection[] - `value` union, required - string - number, double - `label` string, required - `buyer` Buyer, required - `postalCode` string, required - `country` string, required - `province` string, required - `city` string, required - `address2` string - `address1` string, required - `phone` string, required - `email` string, required - `lastName` string, required - `firstName` string, required - `quantity` integer, required - `productUrl` string, required - `createdAt` string, date-time, required - `id` string, required - `failureReason` FailureReason, required - `message` string, required - `code` 'unknown' | 'checkout_intent_expired' | 'payment_failed' | 'payment_cvc_expired' | 'insufficient_stock' | 'product_out_of_stock' | 'offer_retrieval_failed' | 'order_placement_failed' | 'developer_not_found' | 'missing_shipping_method' | 'unsupported_currency' | 'invalid_input' | 'incorrect_cost_breakdown' | 'unsupported_store_no_guest_checkout' | 'workflow_invocation_failed' | 'variant_selections_invalid' | 'variant_selections_required' | 'form_validation_error' | 'captcha_blocked' | 'bot_protection_blocked' | 'constraint_total_price_exceeded' | 'constraint_shipping_cost_exceeded' | 'promo_code_discovery_not_enabled' | 'product_not_found', required — Type derived from runtime array - always in sync - `paymentMethod` union - StripeTokenPaymentMethod - `stripeToken` string, required - `type` 'stripe_token', required - BasisTheoryPaymentMethod - `basisTheoryToken` string, required - `type` 'basis_theory_token', required - DrawdownPaymentMethod - `type` 'drawdown', required - X402PaymentMethod - `network` 'base' | 'solana' | 'tempo', required - `type` 'x402', required - `offer` Offer - `commission` CommissionPotential — The commission a developer would earn if this offer is placed. - `estimate` boolean, required - `amount` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Shipping, required - `availableOptions` ShippingOption[], required - `deliveryEstimate` DeliveryEstimate — Estimated range of dates that items will be delivered in. At least one of `earliest` or `latest` are guaranteed to be set. Interpretation: * If both `earliest` and `latest` are set, then the delivery estimate is the range between the two dates. * If only `earliest` is set, then the delivery estimate is any date after that date. * If only `latest` is set, then the delivery estimate is any date before that date. - `latest` string, date-time — Latest date that items will be delivered by. - `earliest` string, date-time — Earliest date that items will be delivered by. - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `cost` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `id` string, required - `selectedOptionId` string - `cost` Cost, required - `total` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `surcharge` Money - `currencyCode` string, required - `amountSubunits` integer, required - `discount` Money - `currencyCode` string, required - `amountSubunits` integer, required - `tax` Money - `currencyCode` string, required - `amountSubunits` integer, required - `shipping` Money - `currencyCode` string, required - `amountSubunits` integer, required - `subtotal` Money, required - `currencyCode` string, required - `amountSubunits` integer, required - `appliedPromoCodes` string[] - `state` 'failed', required ## Other responses - `401` — Authentication Failed - `422` — Validation Error - `500` — Internal Server Error - `503` — Service Unavailable ## Changes - **2026-07-03** `cd4a7aa2308b` — 5 info - removed `#/components/schemas/NekudaPaymentMethod, #/components/schemas/PravaPaymentMethod` from the `anyOf[subschema #2: Awaiting Confirmation]/allOf[subschema #2]/paymentMethod` response property `anyOf` list for the response status `201` - removed `#/components/schemas/NekudaPaymentMethod, #/components/schemas/PravaPaymentMethod` from the `anyOf[subschema #3: Requires Action]/allOf[subschema #2]/paymentMethod` response property `anyOf` list for the response status `201` - removed `#/components/schemas/NekudaPaymentMethod, #/components/schemas/PravaPaymentMethod` from the `anyOf[subschema #4: Placing Order]/allOf[subschema #2]/paymentMethod` response property `anyOf` list for the response status `201` - removed `#/components/schemas/NekudaPaymentMethod, #/components/schemas/PravaPaymentMethod` from the `anyOf[subschema #5: Completed]/allOf[subschema #2]/paymentMethod` response property `anyOf` list for the response status `201` - …1 more - …earlier changes not shown [Full history](https://skmtc.dev/rye-com/apis/universal-checkout-api/changes/api/v1/checkout-intents/post.md) --- [API](https://skmtc.dev/rye-com/apis/universal-checkout-api.md) · [All operations](https://skmtc.dev/rye-com/apis/universal-checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rye-com/universal-checkout-api/revisions/175c7f9e090e/schema)