How to redeem a Stripe Checkout offer

What you'll build

A Stripe Checkout redemption method and an offer that uses it. Redeeming the offer creates a Stripe Checkout session and returns a navigate action that points the user to it. You will create the method, attach it to an offer, present that offer through an experience, generate an offer token by resolving the experience in a surface decision, and redeem the token.

1. Prerequisites

A Stripe integration with a configured price
A secret API key for your preview environment

2. Create the redemption method

Navigate to Offers, then Redemption Methods, and create a new redemption method. Configure it with the following settings:

Name: Stripe Checkout
Schema: Stripe Checkout

See Add a redemption method for more detail.

3. Edit the workflow

Open the method's Workflow tab and replace the default workflow. The offer is built in a subsequent step. offer.redemption.instructions holds the Checkout session parameters configured when building the offer. The workflow forwards them to Stripe, adds the redirect URLs, and returns the session URL. Anonymous users cannot complete a purchase, so the workflow routes them to sign-up first, carrying the offer token:

Redemption Method Workflow

const :  = async ({ , ,  }) => {
  if (. === "anonymous") {
    return {
      : false,
      : 401,
      : "navigate",
      : `https://example.com/sign-up?offerToken=${.}`,
    };
  }

  const { ,  } = .;

  const  = await ...(
    ,
    {
      : "POST",
      : "/v1/checkout/sessions",
      : {
        ...,
        // Optional: Override properties of the checkout session, for example, dynamic return urls
        : "https://example.com/success",
        : "https://example.com/cancel",
      },
    },
  );

  if (!. || !.?.url) {
    return {
      : false,
      : 502,
      : "Failed to create checkout session",
    };
  }

  return { : true, : "navigate", : ..url };
};

export default ;

4. Create the offer

Create an offer that uses the redemption method, then add one or more catalogue prices for your configured Stripe prices. The prices you add become the line_items the workflow forwards to Stripe. See Add an offer.

5. Present the offer through an experience

An offer token only exists once a surface decision presents the offer, so the offer must sit in an experience that a surface presents. Create one of:

HTML experience: a banner or message built with HTML, CSS, and JavaScript. Generate it from a prompt with the MonetizationOS Assistant, or paste in your own code.
App experience: schema-driven components rendered by your own frontend library. Fill in the content fields via an auto-generated form, choosing a schema that supports offers.

Either way, attach a presentation schema, add the offer to its slot, then assign the experience to a Web Content experience slot on the surface you will call.

The surface decision in the next step presents the offer and returns its token.

6. Generate the offer token

Trigger a surface decision for the surface that presents the experience:

Payload

{
  "surfaceSlug": "<surface-slug>",
  "identity": { "userIdentifier": "buyer@example.com" }
}

Example Request

curl --request POST \
  --url https://api.monetizationos.com/api/v1/surface-decisions \
  --header 'Authorization: Bearer <secret-key>' \
  --header 'content-type: application/json' \
  --data '{"surfaceSlug":"<surface-slug>","identity":{"userIdentifier":"buyer@example.com"}}'

When the offer is presented, the decision response carries the offer with its token:

Surface decision response (offer)

{
  "offer": {
    "id": "off_00c29f1d",
    "presentation": { "title": "Premium Monthly", "price": "£10.00" },
    "redemptionSchema": "mos:stripe-checkout-instructions",
    "token": "<offer-token>"
  }
}

7. Redeem the offer

Send a POST request to the offer-redemptions endpoint with the offer token to redeem it: