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-stg.withflex.com/v1/shipping_rates \
  --header 'authorization: Bearer fsk_MzkxYzU2MTAtZGYxOC00OWUyLThlODQtYTA0ODMwNjhiYmVm' \
  --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-stg.withflex.com/v1/coupons \
  --header 'authorization: Bearer fsk_MzkxYzU2MTAtZGYxOC00OWUyLThlODQtYTA0ODMwNjhiYmVm' \
  --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"}
    }
  }
}

Fulfillment Overview