Define your checkout experience

Below we highlight common use cases that come up with checkout sessions and how to handle them. If there is a scenario that is not addressed, please reach out to miguel@withflex.com

Collect Shipping Details and Shipping Rates

If you need to ship a good, then you can have Flex collect shipping details for you by setting the shipping_address_collection parameter to true as part of the payload.

If you additionally want to charge a shipping rate then you can do so by either:

Creating a fixed shipping rate beforehand using the Shipping Rate API

curl --request POST \
  --url https://api.withflex.com/v1/shipping_rates \
  --header 'authorization: Bearer fsk_test_YzNiYjdhNWItN2FkOS00ZTMyLWE5MmQtZTdhNzMzYzE2NTIy' \
  --header 'content-type: application/json' \
  --data '{"shipping_rate": {"display_name": "Standard Shipping","amount": 500}}'

Then specifying the returned shipping_rate_id as part of the payload when creating a checkout session.

{
  "checkout_session": {
    "line_items": [
      {
        "price": "fprice_01HW5NTAB88NK7HPD0H688EPG9",
        "quantity": 1
      }
    ],
    "success_url": "https://withflex.com/thank-you?success=true",
    "mode": "payment",
    "cancel_url": "https://withflex.com/thank-you?canceled=true",
    "shipping_options": {
      "shipping_rate_id": "fshr_01HW6FC7ZYWNW4XFSE1KMD8JDW"
    }
  }
}

Create the shipping rate when creating the checkout session

If your shipping is variable based off of the cart items then you can pass along the shipping data to create the shipping rate as part of the checkout session payload.

{
  "checkout_session": {
    "line_items": [
      {
        "price": "fprice_01HW5NTAB88NK7HPD0H688EPG9",
        "quantity": 1
      }
    ],
    "success_url": "https://withflex.com/thank-you?success=true",
    "mode": "payment",
    "cancel_url": "https://withflex.com/thank-you?canceled=true",
    "shipping_options": {
      "shipping_rate_data": {
        "display_name": "Standard Shipping",
        "amount": 500
      }
    }
  }
}

Setting a tax amount

If you need to pass along a tax amount to charge a customer you can do so by setting a tax_rate. It is important to note that Flex does not currently calculate tax. This is an amount that you have previously calculated.

{
  "checkout_session": {
    "line_items": [
      {
        "price": "fprice_01HW5NTAB88NK7HPD0H688EPG9",
        "quantity": 1
      }
    ],
    "success_url": "https://withflex.com/thank-you?success=true",
    "mode": "payment",
    "cancel_url": "https://withflex.com/thank-you?canceled=true",
    "tax_rate": {
      "amount": 599
    }
  }
}

Add a discount

If you'd like to add a discount when charging a customer you can do so by creating a coupon then setting the discounts parameter as part of the payload.

Creating a predefined coupon beforehand

curl --request POST \
  --url https://api.withflex.com/v1/coupons \
  --header 'authorization: Bearer fsk_test_YzNiYjdhNWItN2FkOS00ZTMyLWE5MmQtZTdhNzMzYzE2NTIy' \
  --header 'content-type: application/json' \
  --data '{"coupon": {"name": "$10 off","amount_off": 1000}}'

Then using the returned coupon_id as part of the checkout session payload

{
  "checkout_session": {
    "line_items": [
        {
          "price": "fprice_01HW5NTAB88NK7HPD0H688EPG9",
          "quantity": 1
        }
    ],
    "success_url": "https://withflex.com/thank-you?success=true",
    "mode": "payment",
    "cancel_url": "https://withflex.com/thank-you?canceled=true",
    "discounts": {
        {"coupon": "fcoup_01HW6H666X6NMZ6NJHJ3SH3W93"}
    }
  }
}

Embedded Checkout

The checkout may be embedded on a page or within a modal by placing the checkout within an iframe:

  <iframe id="flex-checkout" src="CHECKOUT_SESSION_REDIRECT_URL" allow="payment *; publickey-credentials-get *" width="393" height="852" />

A MessageEvent (opens in a new tab) will be emitted to the window just before the user is redirected. You can listen to this event like this:

window.addEventListener('message', (event) => {
  // Ignore events that originate from something other than the iframe.
  if (event.source !== document.getElementById('flex-checkout').contentWindow) {
    return;
  }
 
  console.log("Message Received", event.data);
});

The data (opens in a new tab) property mimics the checkout.session.completed Webhook Event. However, unlike webhooks, the event from the client is not guaranteed to fire. Therefore it is recommended to listen to the webhooks in order to ensure that the message is received.

The message could be customized by creating a redirect to your own site and having that page post a message (opens in a new tab) to the parent:

window.parent.postMessage(message, { targetOrigin: "*" });

React Example

This is an example of how you could embed the checkout in a React application:

"use client";
 
import { useEffect, useRef } from "react";
 
export default function Frame({ src }: { src: string }) {
  const frame = useRef<HTMLIFrameElement>(null);
 
  useEffect(() => {
    const listener = ({ source, data }: MessageEvent) => {
      if (source !== frame.current?.contentWindow) {
        return;
      }
 
      console.log("[Frame] Message Received", data);
    };
 
    window.addEventListener("message", listener);
 
    return () => {
      window.removeEventListener("message", listener);
    };
  }, []);
 
  return <iframe src={src} allow="payment *; publickey-credentials-get *" width="393" height="852" ref={frame} />;
}

Fulfillment Overview