---
title: "Create Payment Link"
method: POST
path: "/v1/payment_links"
tags: ["Payment Links"]
---

# Create Payment Link

`POST /v1/payment_links`

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.

## Request body

- PaymentLinkBodyForCreatePaymentLink — An envelope wrapping a single payment link object.
  - `payment_link` CreatePaymentLink, required — Parameters for creating a payment link.
    - `line_items` NewLineItem[], nullable — The line items representing what is being sold. Required for payment/subscription modes. Must be empty or omitted for setup mode.
      - `price` string, nullable — The ID of the Price object. One of price or price_data is required.
      - `price_data` NewPriceRequest — Parameters for creating a price. Reference an existing product with `product`, or create one inline with `product_data`.
        - `description` string, nullable — A brief description of the price.
        - `unit_amount` integer, required — A positive integer in cents (or 0 for a free price) representing how much to charge.
        - `recurring` Recurring — Describes how a recurring price bills over time. Present on prices of type `recurring`; `null` for one-time prices.
          - `interval` 'day' | 'week' | 'month' | 'year', required — The frequency at which a recurring price bills.
          - `interval_count` integer, nullable — The number of intervals
          - `trial_period_days` integer, nullable — The number of trial period days before the customer is charged for the first time. Whole days only. For a precise trial-end timestamp (e.g. non-integer days), use `subscription_data.trial_end` on the Create Checkout Session request instead.
        - `metadata` object, nullable — Metadata to attach to the price.
        - `product` string — The ID of the product that this price will belong to.
        - `product_data` CreateProductRequest — Parameters for creating a product. HSA/FSA eligibility is determined automatically by Flex from the name, description, and identifiers you provide, and cannot be set directly.
          - `name` string, required — The product's name, meant to be displayed to the customer.
          - `description` string, nullable — The product's description, a short blurb meant to be displayed to the customer.
          - `upc_code` string, nullable — The product's UPC code. If provided, this will be used to check whether the product is on the eligible product list.
          - `gtin` string, nullable — The product's GTIN. If provided, this will be used to check whether the product is on the eligible product list.
          - `reference_gtin` string, nullable — If the product is HSA/FSA eligible through private label, this should be provided.
          - `url` string, nullable — A URL of a publicly-accessible image of the product.
          - `client_reference_id` string, nullable — An optional identifier for the product set by the client. Immutable after creation.
          - `metadata` object, nullable — Set of key-value pairs that you can attach to a product. This can be useful for storing additional information about the product in a structured format.
          - `image_urls` string[], nullable — URLs of publicly-accessible product images for eligibility determination.
          - `categories` string[], nullable — Product categories (e.g., "Vitamins", "First Aid").
          - `components` string[], nullable — Product components or ingredients (e.g., "Vitamin C", "Zinc").
      - `quantity` integer, required — The quantity of the line item being purchased.
      - `shipping_options` ShippingRateOptionsRequest — Specifies the shipping rate to apply, either by referencing an existing rate or by providing inline data to create one. Provide one of `shipping_rate_id` or `shipping_rate_data`; at least one is required.
        - `shipping_rate_id` string, nullable — ID of an existing shipping rate to apply. Provide this or `shipping_rate_data`.
        - `shipping_rate_data` CreateShippingRateRequest — Parameters for creating a shipping rate.
          - `display_name` string, required — The name shown to the customer at checkout (e.g., `Standard Shipping`). Must be at least 2 characters.
          - `amount` integer, required — The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD.
          - `metadata` object, nullable — Set of key-value pairs you can attach to the shipping rate for storing additional structured information.
      - `tax_rate` TaxRate — A fixed tax amount to apply to a Checkout Session or line item. Use this to pass a tax figure you have calculated yourself, rather than having Flex compute it.
        - `amount` integer, required — The tax amount to apply, in the smallest currency unit (e.g., `175` = $1.75 USD).
    - `label` string, nullable — Custom name shown for the payment link. When omitted, a label is auto-generated from the first line item's product (e.g. "Product name and 2 more"). Required for setup mode, where there are no products to derive a name from.
    - `shipping_address_collection` boolean, nullable — Whether to collect a shipping address from the customer at checkout. Defaults to `false`.
    - `shipping_options` ShippingRateOptionsRequest — Specifies the shipping rate to apply, either by referencing an existing rate or by providing inline data to create one. Provide one of `shipping_rate_id` or `shipping_rate_data`; at least one is required.
      - `shipping_rate_id` string, nullable — ID of an existing shipping rate to apply. Provide this or `shipping_rate_data`.
      - `shipping_rate_data` CreateShippingRateRequest — Parameters for creating a shipping rate.
        - `display_name` string, required — The name shown to the customer at checkout (e.g., `Standard Shipping`). Must be at least 2 characters.
        - `amount` integer, required — The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD.
        - `metadata` object, nullable — Set of key-value pairs you can attach to the shipping rate for storing additional structured information.
    - `metadata` object, nullable — Set of key-value pairs you can attach to the payment link for storing additional structured information.
    - `payment_intent_data` PaymentIntentData — Indicates the parameters to be passed to PaymentIntent creation during checkout
      - `capture_method` 'automatic' | 'automatic_async' | 'manual', required — Controls when funds are captured: automatically once the payment is confirmed, or manually at a later time.
      - `metadata` object, nullable — Set of key-value pairs attached to the PaymentIntent created during checkout, for storing additional structured information.
    - `after_completion` AfterCompletion — Configures what the customer sees after completing a checkout session generated from a payment link.
      - `type` 'redirect' | 'hosted_confirmation', required — What happens after a payment link checkout completes: a redirect to your URL, or a Flex-hosted confirmation page.
      - `hosted_confirmation` HostedConfirmation — Hosted confirmation page shown after a completed checkout when `after_completion.type` is `hosted_confirmation`.
        - `custom_message` string, nullable — A custom message displayed to the customer on the hosted confirmation page.
      - `redirect` Redirect — Redirect behavior applied after a completed checkout when `after_completion.type` is `redirect`.
        - `url` string, uri, required — The URL the customer is redirected to after completing the checkout.
    - `allow_promotion_codes` boolean, nullable — Whether customers may enter promotion codes at checkout. Defaults to `false`.
    - `origin` 'shopify' | 'shopline' | 'prepurchase' | 'postpurchase' — Origin of where the checkout session was generated
    - `tax_rate` TaxRate — A fixed tax amount to apply to a Checkout Session or line item. Use this to pass a tax figure you have calculated yourself, rather than having Flex compute it.
      - `amount` integer, required — The tax amount to apply, in the smallest currency unit (e.g., `175` = $1.75 USD).
    - `discounts` DiscountType[], nullable — Discounts to apply when generating checkout sessions. Supports existing coupon IDs or inline coupon creation via coupon_data.
      - `coupon_id` string — ID of an existing Coupon to apply.
      - `promo_code_id` string — ID of an existing PromoCode to apply. The discount is sourced from the coupon the promotion code references.
      - `coupon_data` CreateCouponRequest — Parameters for creating a coupon. Exactly one of `amount_off` or `percent_off` must be set.
        - `applies_to` union — What a coupon's discount is restricted to.
          - object
            - `products` string[], required — The product that this coupon applies to.
          - object
            - `prices` string[], required — The price that this coupon applies to.
          - object
            - `fee_types` FeeType[], required — The fee types that this coupon applies to.
          - 'shipping' — The coupon applies to shipping.
        - `name` string, required — Name of the coupon displayed to customers.
        - `amount_off` integer, nullable — A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed).
        - `duration` 'once' | 'repeating' | 'forever' — - `once`: Applies to the first charge from a subscription with this coupon applied. - `repeating`: Applies to charges in the first duration_in_months months from a subscription with this coupon applied. - `forever`: Applies to all charges from a subscription with this coupon applied.
        - `duration_in_months` integer, nullable — Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect.
        - `percent_off` number, double, nullable — A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).
        - `max_redemptions` integer, nullable — A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid.
        - `metadata` object, nullable — Metadata to attach to this coupon.
    - `mode` 'payment' | 'subscription' | 'off_session' | 'setup' — The mode of the checkout session, which determines what happens on completion: a one-time payment, starting a subscription, charging a saved payment method off-session, or saving a payment method for future use.
    - `setup_future_use` 'on_session' | 'off_session' — - `on_session`: Standard payments requiring customer auth - `off_session`: Allows payments without the customer present in the flow

## Response `200`

An envelope wrapping a single payment link object.

- PaymentLinkBodyForPaymentLink — An envelope wrapping a single payment link object.
  - `payment_link` PaymentLink, required — A Payment Link represents a shareable URL that generates a checkout session each time a customer opens it. Use it to sell products or collect a payment method without building your own checkout page.
    - `payment_link_id` string, required — Unique identifier for the Payment Link
    - `label` string, nullable — Provided or generated label for the payment link.
    - `active` boolean, required — Whether the payment link is currently active. If false, the link can no longer be used to generate checkout sessions and customers visiting the URL will be shown a not-found page.
    - `line_items` NewLineItem[], nullable — The line items representing what is being sold.
      - `price` string, nullable — The ID of the Price object. One of price or price_data is required.
      - `price_data` NewPriceRequest — Parameters for creating a price. Reference an existing product with `product`, or create one inline with `product_data`.
        - `description` string, nullable — A brief description of the price.
        - `unit_amount` integer, required — A positive integer in cents (or 0 for a free price) representing how much to charge.
        - `recurring` Recurring — Describes how a recurring price bills over time. Present on prices of type `recurring`; `null` for one-time prices.
          - `interval` 'day' | 'week' | 'month' | 'year', required — The frequency at which a recurring price bills.
          - `interval_count` integer, nullable — The number of intervals
          - `trial_period_days` integer, nullable — The number of trial period days before the customer is charged for the first time. Whole days only. For a precise trial-end timestamp (e.g. non-integer days), use `subscription_data.trial_end` on the Create Checkout Session request instead.
        - `metadata` object, nullable — Metadata to attach to the price.
        - `product` string — The ID of the product that this price will belong to.
        - `product_data` CreateProductRequest — Parameters for creating a product. HSA/FSA eligibility is determined automatically by Flex from the name, description, and identifiers you provide, and cannot be set directly.
          - `name` string, required — The product's name, meant to be displayed to the customer.
          - `description` string, nullable — The product's description, a short blurb meant to be displayed to the customer.
          - `upc_code` string, nullable — The product's UPC code. If provided, this will be used to check whether the product is on the eligible product list.
          - `gtin` string, nullable — The product's GTIN. If provided, this will be used to check whether the product is on the eligible product list.
          - `reference_gtin` string, nullable — If the product is HSA/FSA eligible through private label, this should be provided.
          - `url` string, nullable — A URL of a publicly-accessible image of the product.
          - `client_reference_id` string, nullable — An optional identifier for the product set by the client. Immutable after creation.
          - `metadata` object, nullable — Set of key-value pairs that you can attach to a product. This can be useful for storing additional information about the product in a structured format.
          - `image_urls` string[], nullable — URLs of publicly-accessible product images for eligibility determination.
          - `categories` string[], nullable — Product categories (e.g., "Vitamins", "First Aid").
          - `components` string[], nullable — Product components or ingredients (e.g., "Vitamin C", "Zinc").
      - `quantity` integer, required — The quantity of the line item being purchased.
      - `shipping_options` ShippingRateOptionsRequest — Specifies the shipping rate to apply, either by referencing an existing rate or by providing inline data to create one. Provide one of `shipping_rate_id` or `shipping_rate_data`; at least one is required.
        - `shipping_rate_id` string, nullable — ID of an existing shipping rate to apply. Provide this or `shipping_rate_data`.
        - `shipping_rate_data` CreateShippingRateRequest — Parameters for creating a shipping rate.
          - `display_name` string, required — The name shown to the customer at checkout (e.g., `Standard Shipping`). Must be at least 2 characters.
          - `amount` integer, required — The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD.
          - `metadata` object, nullable — Set of key-value pairs you can attach to the shipping rate for storing additional structured information.
      - `tax_rate` TaxRate — A fixed tax amount to apply to a Checkout Session or line item. Use this to pass a tax figure you have calculated yourself, rather than having Flex compute it.
        - `amount` integer, required — The tax amount to apply, in the smallest currency unit (e.g., `175` = $1.75 USD).
    - `allow_promotion_codes` boolean, required — Whether promo codes are enabled
    - `shipping_address_collection` boolean, required — Whether we want to collect shipping details at checkout time
    - `shipping_options` ShippingRateOptions — A resolved shipping option attached to a checkout session or payment link, capturing the applied shipping rate and its cost.
      - `shipping_rate_id` string, required — ID of the applied shipping rate.
      - `shipping_amount` integer, required — The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD.
      - `display_name` string, nullable — The display name of the shipping rate (e.g., "Standard Shipping", "Express").
    - `metadata` object, nullable — Metadata to attach to the payment session
    - `url` string, required — The public URL that can be shared with customers.
    - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
    - `payment_intent_data` PaymentIntentData — Indicates the parameters to be passed to PaymentIntent creation during checkout
      - `capture_method` 'automatic' | 'automatic_async' | 'manual', required — Controls when funds are captured: automatically once the payment is confirmed, or manually at a later time.
      - `metadata` object, nullable — Set of key-value pairs attached to the PaymentIntent created during checkout, for storing additional structured information.
    - `after_completion` AfterCompletion, required — Configures what the customer sees after completing a checkout session generated from a payment link.
      - `type` 'redirect' | 'hosted_confirmation', required — What happens after a payment link checkout completes: a redirect to your URL, or a Flex-hosted confirmation page.
      - `hosted_confirmation` HostedConfirmation — Hosted confirmation page shown after a completed checkout when `after_completion.type` is `hosted_confirmation`.
        - `custom_message` string, nullable — A custom message displayed to the customer on the hosted confirmation page.
      - `redirect` Redirect — Redirect behavior applied after a completed checkout when `after_completion.type` is `redirect`.
        - `url` string, uri, required — The URL the customer is redirected to after completing the checkout.
    - `origin` 'shopify' | 'shopline' | 'prepurchase' | 'postpurchase' — Origin of where the checkout session was generated
    - `tax_rate` TaxRate — A fixed tax amount to apply to a Checkout Session or line item. Use this to pass a tax figure you have calculated yourself, rather than having Flex compute it.
      - `amount` integer, required — The tax amount to apply, in the smallest currency unit (e.g., `175` = $1.75 USD).
    - `discounts` string[], nullable — Pre-stored coupon IDs to apply as discounts when generating checkout sessions
    - `setup_future_use` 'on_session' | 'off_session', required — - `on_session`: Standard payments requiring customer auth - `off_session`: Allows payments without the customer present in the flow
    - `test_mode` boolean, required — Whether the payment link was created in test mode

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too Many Requests

---

[API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)