Skip to main content

​
Introduction

There are two key steps that must be taken in order for off session checkouts with a product requiring a Letter of Medical Necessity to work as intended:
  1. Having the customer complete the initial (on session) checkout session
  2. Using the customer’s off-session-verified payment method (along with their customer_id) from step 1 in subsequent off session checkouts
Important: For any products requiring a Letter of Medical Necessity, the customer must have an approved Letter for the product in order for any off session checkout sessions to work. They can receive this letter during the initial on session checkout discussed in the next section. If they are denied a letter or do not have one, off session checkouts will not work with that customer for the associated product(s).

​
Initial (On Session) Checkout Session

This step is vital to ensure all future off session payments work. During the initial on session checkout, the customer will:
  • Go through the checkout consultation to determine if they are eligible to receive a Letter of Medical Necessity for the product(s) in the checkout.
  • Provide a valid payment method that will then be verified for future off session payments (assuming the payment is successful).
  • Be assigned a Flex customer_id (if they are a customer using Flex for the first time; if they have used Flex prior they will already have this).
All of these components are vital to ensure future off session payments for the customer work as expected.

​
Example On Session Checkout Creation

The key difference here compared to other checkouts is making sure you set the setup_future_use parameter to off_session. This is how Flex knows to validate the payment method used in the checkout for future off session payments. 
curl --request POST \
  --url https://api.withflex.com/v1/checkout/sessions \
  --header 'authorization: Bearer <API_KEY>' \
  --header 'content-type: application/json' \
  --data '{
    "checkout_session": {
      "line_items": [
        {
          "price": "<PRICE_ID>",
          "quantity": 1
        }
      ],
      "setup_future_use": "off_session",
      "mode": "payment",
      "success_url": "https://example.com/success",
      "cancel_url": "https://example.com/cancel"
    }
  }'
This will create a checkout session that the customer will then go through to receive their letter and submit their initial payment. After the customer fills out their payment information and clicks “Pay Now” and the payment successfully goes through, the customer will have:
  • A valid Letter for the product (Flex will use this valid letter as part of the process when determining if future off session payments can go through)
  • A customer_id
  • A verified payment_method
That is everything you will need for future off session payments.

​
Off Session Checkout Creation

Now that we have access to:
  • The customer’s customer_id
  • The customer’s off session verified payment_method
  • A validated Letter attached to the customer for the product
We can move forward with off session payments.

​
Getting customer_id

The customer_id is a required field for off session checkouts, and is also useful for programmatically finding the customer’s payment method(s). There are several ways to obtain it:
  • Grabbing it from the checkout.session.completed webhook event that is fired when the checkout session completes
  • Using the associated checkout session’s ID with the GET Checkout endpoint, and grabbing it from the returned checkout session object
  • Finding it with the List Customers endpoint
  • Finding it in the Customers tab of the Flex dashboard

​
Getting payment_method ID

Now that we have the customer_id, we can use the List Payment Methods endpoint to grab the customer’s payment method that is approved for off sessions. You will know if the payment method is viable for off sessions by seeing the off_session field with a value of true on the returned payment method object. 
{
  "payment_method_id": "<ID>",
  "billing_details": { ... },
  "customer": "<ID>",
  "metadata": null,
  "card": { ... },
  "created_at": "2026-01-23T19:13:46.145643Z",
  "test_mode": true,
  "off_session": true
}

​
Example Off Session Checkout

Now, to use all of this information to complete an off session payment, plug it into the correct places in the Off Session Checkout call: 
curl --request POST \
  --url https://api.withflex.com/v1/checkout/sessions \
  --header 'authorization: Bearer <API_KEY>' \
  --header 'content-type: application/json' \
  --data '{
    "checkout_session": {
      "line_items": [
        {
          "price": "<PRICE_ID>",
          "quantity": 1
        }
      ],
      "mode": "off_session",
      "customer": "<CUSTOMER_ID>",
      "payment_method": "<PAYMENT_METHOD_ID>",
      "success_url": "https://example.com/success",
      "cancel_url": "https://example.com/cancel"
    }
  }'
A successful call will return a response with the key details: 
{
  "status": "complete",
  "payment_intent": {
    "status": "succeeded",
    "amount": "<amount>",
    "amount_received": "<amount_received>"
  },
  "letter_of_medical_necessity_required": true,
  "visit_type": "<visit_type>"
}
If you get a response like the above, you have successfully set up an off session checkout flow!

​
Additional Information

​
What happens if the customer does not have a letter for the product?

If you try to submit an off session payment in this scenario, the call will fail with an error response like this: 
{
  "detail": [
    {
      "loc": ["visit_type"],
      "msg": "A LoMN is required for this visit type",
      "type": "invalid_request_error"
    }
  ]
}
This indicates that the customer does not have a valid letter for the product in question, and they will not be able to have off session checkouts for the product until that letter is acquired.

​
Do letters ever expire once a customer gets one?

Yes, letters remain valid for 1 year from the day the customer goes through the consultation. If you want to use off session payments for longer than that, customers will need to go through the on session flow once per year to maintain a valid letter on file.

​
Will one letter cover a customer for all products?

Not necessarily. Letters are tied to specific visit_type values, so a letter only applies to products that fall under the same visit_type. For example, if a customer went through an on session checkout and purchased a product bucketed under the gym visit type, they would then have a valid letter for all products in your catalog that also have a gym visit type. You could use an off session payment immediately for those products without the customer needing to go through the on session flow again. However, if they wanted to purchase a product under the skincare visit type, the gym letter would not be sufficient. The customer would need to go through another on session checkout consultation to receive a letter for skincare visit type products before off session payments would work.