Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The components are presentation-only — your backend is the only thing that talks to Rye’s API. This cookbook covers the most common integration patterns.
All examples assume you’ve already installed the relevant components (see Install) and have a Rye API key with access to Universal Checkout.

​
The drawdown checkout pattern

The most common rewards-program flow: user picks a product, applies some or all of their points balance, your backend creates a checkout intent against the Rye API, and <PaymentSheet /> walks them through confirmation.

​
1. Browse catalog → product detail page

Render <ProductCard /> tiles in your catalog grid. When a user clicks one, route to a PDP rendered with <ProductDetails />. Both components are presentational — your server fetches the product from Rye (or your own backend that mirrors Rye), passes data in via props, and receives selection changes via callbacks.

​
2. Variant selection + quantity

Inside <ProductDetails />, the <Variants /> and <Quantity /> slots manage selection and quantity locally. Persist the selection in your own state — you’ll need it for the checkout intent. When a variant goes out of stock between page load and checkout, surface a revalidationError on <ProductDetails />; it renders an inline alert above the variant pickers.

​
3. Create a checkout intent

When the user clicks the <ProductDetails.Redeem /> CTA, your server creates a checkout intent. See the Universal Checkout intent lifecycle for the full state machine. 
import CheckoutIntents from "checkout-intents";

const client = new CheckoutIntents({ apiKey: process.env.RYE_API_KEY });

const intent = await client.checkoutIntents.create({
  // ... product, buyer, variant picks, etc.
});

​
4. Confirmation sheet with mixed tender

Render <PaymentSheet /> with the intent data. Use <PayWithPoints /> inside a <PaymentSheet.Section /> to let the user pick how many points to apply. The <PayWithPoints.Summary /> slot’s orderTotal prop pairs nicely with <PaymentSheet.CostBreakdown /> — both show the user how the order splits between points and cash. When the user clicks <PaymentSheet.Confirm />, your server calls intent.confirm() (or intent.purchase() depending on the flow) and triggers the payment method.

​
5. Post-purchase

After the order places, route to an <OrderTracking /> page. Poll your own backend (which polls Rye) and update the <StatusPill /> and <Timeline /> props as the order progresses through the lifecycle. For the stuck/investigation state, swap <StatusCard /> for <InvestigationCard /> and surface <InvestigationActions /> so the user can decide how they want to proceed (wait, reattempt, refund).

​
The member-benefit pattern

For partners who run a discount-pass-through program (e.g. credit-card members get 5% off without applying points), skip <PayWithPoints /> and use <PaymentSheet.MemberBenefit /> to surface the discount as a line item. 
<PaymentSheet>
  <PaymentSheet.Header title="Confirm your order" subtitle="Includes your member benefit" />
  <PaymentSheet.Item item={item} />
  <PaymentSheet.Shipping buyer={buyer} />
  <PaymentSheet.MemberBenefit
    title="Member benefit applied"
    description="5% off, automatically applied at checkout."
    amount={{ currency: "USD", value: "-13.35" }}
  />
  <PaymentSheet.CostBreakdown lines={lines} total={total} />
  <PaymentSheet.Confirm onClick={onConfirm}>Confirm · {total}</PaymentSheet.Confirm>
</PaymentSheet>

​
Address entry

For first-time buyers or address edits, <AddressForm /> produces the canonical Buyer shape that the rest of the SDK consumes. Wire it to your own validation layer: 
<AddressForm
  value={buyer}
  onChange={setBuyer}
  fieldErrors={validate(buyer)}
  onSubmit={async (next) => {
    await persistAddress(next);
    router.push("/checkout");
  }}
>
  <AddressForm.Name />
  <AddressForm.Address />
  <AddressForm.Region />
  <AddressForm.Contact />
  <AddressForm.Submit>Save address</AddressForm.Submit>
</AddressForm>
The Buyer from AddressForm plugs straight into <PaymentSheet.Shipping buyer={buyer} /> and into intent creation. Same shape, no remapping.

​
Reference demo

rewards.rye.com is a full Next.js implementation of the patterns above. The source is MIT-licensed — clone it as a starting template.