Payment Links

Create Payment Link

Changed on Nov 3, 2026

Creates a payment link: a shareable URL that generates a checkout session each time a customer opens it. The mode is determined by line_items — it becomes subscription if any price is recurring, otherwise payment; pass mode=setup to save a payment method without a charge (setup mode requires a label and empty line_items). Creating a link may create supporting objects as a side effect: inline price_data provisions a Product and Price (in Stripe and Flex), inline shipping rate data creates a Shipping Rate, and inline coupon_data discounts create Coupons. Promotion codes are not accepted as discounts here — use coupon IDs or inline coupon data.

post/v1/payment_links

Request

Base URL
https://api.withflex.com
URL
https://api.withflex.com/v1/payment_links
Auth
HTTP bearer

Request body

Example request

{
  "payment_link": {
    "line_items": [
      {
        "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "price_data": {
          "description": "Premium SPF 50 mineral sunscreen",
          "unit_amount": 2500,
          "recurring": {
            "interval": "day",
            "interval_count": 0,
            "trial_period_days": 0
          },
          "metadata": {
            "order_id": "8842",
            "channel": "shopify"
          },
          "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
          "product_data": {
            "name": "Example",
            "description": "Premium SPF 50 mineral sunscreen",
            "upc_code": "example_value",
            "gtin": "example_value",
            "reference_gtin": "example_value",
            "url": "https://example.com",
            "client_reference_id": "example_value",
            "metadata": {
              "order_id": "8842",
              "channel": "shopify"
            },
            "image_urls": [
              "https://example.com/image.png"
            ],
            "categories": [
              "string"
            ],
            "components": [
              "string"
            ]
          }
        },
        "quantity": 0,
        "shipping_options": {
          "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
          "shipping_rate_data": {
            "display_name": "Example",
            "amount": 2500,
            "metadata": {
              "order_id": "8842",
              "channel": "shopify"
            }
          }
        },
        "tax_rate": {
          "amount": 2500
        },
        "components": [
          {
            "quantity": 1,
            "dressing_mode": "MIXED",
            "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
            "client_reference_id": "string"
          }
        ]
      }
    ],
    "label": "Example",
    "shipping_address_collection": false,
    "shipping_options": {
      "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "shipping_rate_data": {
        "display_name": "Example",
        "amount": 2500,
        "metadata": {
          "order_id": "8842",
          "channel": "shopify"
        }
      }
    },
    "metadata": {
      "order_id": "8842",
      "channel": "shopify"
    },
    "payment_intent_data": {
      "capture_method": "automatic",
      "metadata": {
        "order_id": "8842",
        "channel": "shopify"
      }
    },
    "after_completion": {
      "type": "redirect",
      "hosted_confirmation": {
        "custom_message": "Premium SPF 50 mineral sunscreen"
      },
      "redirect": {
        "url": "https://example.com"
      }
    },
    "allow_promotion_codes": false,
    "origin": "shopify",
    "tax_rate": {
      "amount": 2500
    },
    "discounts": [
      {
        "coupon_id": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "promo_code_id": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "coupon_data": {
          "applies_to": {
            "products": [
              "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
            ]
          },
          "name": "Coupon",
          "amount_off": 100,
          "duration": "once",
          "percent_off": 10,
          "max_redemptions": 100,
          "metadata": {
            "key": "value"
          }
        }
      }
    ],
    "mode": "payment",
    "setup_future_use": "on_session"
  }
}

Response

An envelope wrapping a single payment link object.

Example response

{
  "payment_link": {
    "payment_link_id": "fplink_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "label": "Example",
    "active": false,
    "line_items": [
      {
        "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "price_data": {
          "description": "Premium SPF 50 mineral sunscreen",
          "unit_amount": 2500,
          "recurring": {
            "interval": "day",
            "interval_count": 0,
            "trial_period_days": 0
          },
          "metadata": {
            "order_id": "8842",
            "channel": "shopify"
          },
          "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
          "product_data": {
            "name": "Example",
            "description": "Premium SPF 50 mineral sunscreen",
            "upc_code": "example_value",
            "gtin": "example_value",
            "reference_gtin": "example_value",
            "url": "https://example.com",
            "client_reference_id": "example_value",
            "metadata": {
              "order_id": "8842",
              "channel": "shopify"
            },
            "image_urls": [
              "https://example.com/image.png"
            ],
            "categories": [
              "string"
            ],
            "components": [
              "string"
            ]
          }
        },
        "quantity": 0,
        "shipping_options": {
          "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
          "shipping_rate_data": {
            "display_name": "Example",
            "amount": 2500,
            "metadata": {
              "order_id": "8842",
              "channel": "shopify"
            }
          }
        },
        "tax_rate": {
          "amount": 2500
        },
        "components": [
          {
            "quantity": 1,
            "dressing_mode": "MIXED",
            "component_id": "fcomp_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
            "client_reference_id": "string"
          }
        ]
      }
    ],
    "allow_promotion_codes": false,
    "shipping_address_collection": false,
    "shipping_options": {
      "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "shipping_amount": 2500,
      "display_name": "Example"
    },
    "metadata": {
      "order_id": "8842",
      "channel": "shopify"
    },
    "url": "https://example.com",
    "created_at": "2026-06-15T14:30:00Z",
    "payment_intent_data": {
      "capture_method": "automatic",
      "metadata": {
        "order_id": "8842",
        "channel": "shopify"
      }
    },
    "after_completion": {
      "type": "redirect",
      "hosted_confirmation": {
        "custom_message": "Premium SPF 50 mineral sunscreen"
      },
      "redirect": {
        "url": "https://example.com"
      }
    },
    "origin": "shopify",
    "tax_rate": {
      "amount": 2500
    },
    "discounts": [
      "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
    ],
    "setup_future_use": "on_session",
    "test_mode": false
  }
}

Changes

Nov 3, 2026eec642897a22 Revision changes
- breaking
  removed from the /// request property anyOf list
- breaking
  removed from the / request property anyOf list
- warning
  the //// request property's max was set to 2147483647.00
- warning
  the //// request property's max was set to 2147483647.00
- warning
  the //// request property's max was set to 2147483647.00
- warning
  the /// request property's max was set to 2147483647.00
- warning
  the ///////////// request property's max was set to 2147483647.00
- warning
  the //////// request property's max was set to 2147483647.00
- warning
  the /////////// request property's max was set to 2147483647.00
- warning
  the ////// request property's max was set to 2147483647.00
- warning
  the //// request property's min was set to -2147483648.00
- warning
  the //// request property's min was set to -2147483648.00
- warning
  the //// request property's min was set to -2147483648.00
- warning
  the /// request property's min was set to -2147483648.00
- warning
  the ///////////// request property's min was set to -2147483648.00
- warning
  the //////// request property's min was set to -2147483648.00
- warning
  the /////////// request property's min was set to -2147483648.00
- warning
  the ////// request property's min was set to -2147483648.00
- warning
  added the new renewal enum value to the ///// response property for the response status
- info
  added the new optional request property ///
- info
  added to the /// request property anyOf list
- info
  added to the / request property anyOf list
- info
  added the new reimbursement enum value to the request property /////
- info
  added the new renewal enum value to the request property /////
- info
  added the optional property /// to the response with the status
- info
  added to the /// response property anyOf list for the response status
- info
  removed from the /// response property anyOf list for the response status

Operation history