Payment links

Payment links are reusable hosted payment pages you can share with any number of buyers, unlike a checkout session, which is single-use and tied to one buyer. A link supports three modes: standard for fixed line items or subscription signup via subscription_plan_id, donation for variable buyer-chosen amounts, and event for ticket-tier sales. Each completed checkout through a link creates its own order behind the scenes, keeping payment links inside the orders-first model.

Links stay active until you deactivate them, they expire, or they hit an optional completion limit. Line items can come from your catalog (variants or bundles) or be defined ad hoc, with optional quantity and amount adjustment controls, custom fields, tipping, and promotion support.

The public read, GET /v1/payment-links/{payment_link_id}/public, returns the merchant's current display name. If Flint can't load the merchant, the read fails with 500 INTERNAL_ERROR instead of returning a placeholder name; retry it.

A catalog-backed line item stores only the reference, so reads add resolved_name and resolved_unit_price_money to show what the catalog says right now, and is_catalog_item_unavailable when the variant or bundle is missing, deleted, or inactive. These are current catalog values, not a stored snapshot: checkout resolves the catalog again when a buyer opens the link, so a later catalog edit changes what the buyer pays. They are read-only and ignored on writes.

Start with the Payment links guide. For choosing between hosted surfaces, see Payment links vs checkout sessions vs invoices.

The link's version covers its template, image, and delivery selection. Set delivery_method_ids on create or replace the array on PATCH with expected_version. PATCH requires that version when line_items, custom_fields, or delivery_method_ids is present. Omit an array to leave it unchanged; send [] to clear delivery methods or custom fields. Null and duplicate delivery method IDs are invalid. A link without delivery methods offers settings.checkout.default_delivery_method_ids when its order has items to deliver, so buyers can still choose shipping or pickup. A stale save returns PAYMENT_LINK_CHANGED; retrieve the link before retrying. Use promotion_config.codes_enabled to control promotion-code entry.

The Payment link object#

Every field on a payment link, as returned by retrieve and carried by the endpoints below.

Attributes

completed_countintegerRequired

created_atstring

RFC3339 timestamp.

custom_fieldsarray of object

custom_textobject

customer_collectionobject

delivery_method_idsarray of string

Delivery methods the link offers. Empty when the link has none, and then its checkouts offer settings.checkout.default_delivery_method_ids when the order has items to deliver.

descriptionstring

donation_max_amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

donation_min_amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

donation_suggested_amount_money_optionsarray of object

event_configobject

expirationobject

external_reference_idstring

Caller-owned identifier for this resource in an external system.

imageobject

inactive_messagestring

inventory_routing_sourceone of

legalobject

line_itemsarray of one of

max_completionsinteger

merchant_idstring

metadatamap of string

namestringRequired

payment_link_idstringRequired

payment_link_typeenum

standard
donation
event

paymentsobject

promotion_configobject

redirectsobject

statusenumRequired

active
inactive

subscription_planobject or null

subscription_plan_idstring

taxobject

themeobject

tipobject

total_quantity_soldinteger

Whole-number quantity; fractional quantities are not supported.

updated_atstring

RFC3339 timestamp.

urlstringRequired

versionintegerRequired

JSON

{
  "completed_count": 3,
  "created_at": "2026-03-17T14:30:00Z",
  "custom_fields": [
    {
      "custom_field_type": "dropdown",
      "key": "meal_preference",
      "label": "Meal preference",
      "options": [
        "Vegetarian",
        "Chicken",
        "Fish"
      ],
      "payment_link_custom_field_id": "plcf_123",
      "required": true
    }
  ],
  "description": "Event checkout",
  "event_config": {
    "event_at": "2026-05-12T19:00:00Z",
    "max_total_quantity": 500,
    "send_ticket_emails": true,
    "ticket_prefix": "GAL",
    "venue": "Pier 57, New York"
  },
  "image": {
    "alt": "Spring gala",
    "height": 900,
    "url": "https://images.withflintpay.com/ia_spring_gala/original",
    "width": 1600
  },
  "line_items": [
    {
      "is_catalog_item_unavailable": false,
      "key": "general-admission",
      "name": "General Admission",
      "payment_link_line_item_id": "plli_123",
      "quantity": 1,
      "unit_price_money": {
        "amount": 2500,
        "currency": "USD"
      }
    }
  ],
  "merchant_id": "mer_123",
  "metadata": {
    "campaign": "spring-gala"
  },
  "name": "Spring Gala",
  "payment_link_id": "pl_123",
  "payment_link_type": "event",
  "payments": {
    "enabled_payment_options": [
      "card",
      "apple_pay",
      "google_pay"
    ]
  },
  "status": "active",
  "total_quantity_sold": 42,
  "updated_at": "2026-03-17T14:30:00Z",
  "url": "https://checkout.withflintpay.com/pay/pl_123",
  "version": 1
}

List payment links#

GET/v1/payment-links

Requires scope checkouts.payment_links.read or checkouts.payment_links.write

Returns a paginated list of payment links for the authenticated merchant.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by payment link status.

active
inactive

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

querystring

Search across payment link ID, external reference ID, name, and description. Text fields match any part of the value, and %, _ and \ are ordinary characters, not wildcards. IDs match from the start and need the type prefix, such as ord_01.

payment_link_typeenum

Filter by payment link type.

standard
donation
event

has_planboolean

Filter by whether the payment link references a subscription plan.

sort_byenum

Sort field.

created_at
updated_at

sort_directionenum

Sort direction.

asc
desc

created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/payment-links \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": [
    {
      "completed_count": 3,
      "created_at": "2026-03-17T14:30:00Z",
      "custom_fields": [
        {
          "custom_field_type": "dropdown",
          "key": "meal_preference",
          "label": "Meal preference",
          "options": [
            "Vegetarian",
            "Chicken",
            "Fish"
          ],
          "payment_link_custom_field_id": "plcf_123",
          "required": true
        }
      ],
      "description": "Event checkout",
      "event_config": {
        "event_at": "2026-05-12T19:00:00Z",
        "max_total_quantity": 500,
        "send_ticket_emails": true,
        "ticket_prefix": "GAL",
        "venue": "Pier 57, New York"
      },
      "image": {
        "alt": "Spring gala",
        "height": 900,
        "url": "https://images.withflintpay.com/ia_spring_gala/original",
        "width": 1600
      },
      "line_items": [
        {
          "is_catalog_item_unavailable": false,
          "key": "general-admission",
          "name": "General Admission",
          "payment_link_line_item_id": "plli_123",
          "quantity": 1,
          "unit_price_money": {
            "amount": 2500,
            "currency": "USD"
          }
        }
      ],
      "merchant_id": "mer_123",
      "metadata": {
        "campaign": "spring-gala"
      },
      "name": "Spring Gala",
      "payment_link_id": "pl_123",
      "payment_link_type": "event",
      "payments": {
        "enabled_payment_options": [
          "card",
          "apple_pay",
          "google_pay"
        ]
      },
      "status": "active",
      "total_quantity_sold": 42,
      "updated_at": "2026-03-17T14:30:00Z",
      "url": "https://checkout.withflintpay.com/pay/pl_123",
      "version": 1
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create payment link#

POST/v1/payment-linksIdempotent

Requires scope checkouts.payment_links.write

Creates a payment link for the authenticated merchant. Line items may use fixed prices, buyer-adjustable amounts, and buyer-adjustable quantities.

Request body

custom_fieldsarray of object

custom_textobject

customer_collectionobject

delivery_method_idsarray of string

Complete delivery method selection for the link. A link without delivery methods offers settings.checkout.default_delivery_method_ids when its order has items to deliver. Send an empty array to clear the selection. Omit it on PATCH to leave the selection unchanged. Null and duplicate IDs are not accepted.

descriptionstring

donation_max_amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

donation_min_amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

donation_suggested_amount_money_optionsarray of object

event_configobject

expirationobject

external_reference_idstring

Caller-owned identifier for this resource in an external system.

imageobject

inactive_messagestring

inventory_routing_sourceone of

legalobject

line_itemsarray of one of

max_completionsinteger

metadatamap of string

Metadata pairs plus custom fields must not exceed 44; 6 of the order's 50 pairs are reserved for Flint. Metadata keys and values, custom_field_ keys and largest possible answers, and Flint metadata must fit within 32768 UTF-8 bytes. Text answers are budgeted at four bytes per Unicode code point, including optional fields. If the combined budget is exceeded, lower max_length on some fields, use fewer custom fields, or reduce metadata. These limits apply to standard and plan links and are checked against the merged configuration on update.

namestringRequired

payment_link_typeenum

standard
donation
event

paymentsobject

promotion_configobject

redirectsobject

subscription_plan_idstring

taxobject

themeobject

tipobject

Response · 201

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/payment-links \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "custom_fields": [
      {
        "custom_field_type": "dropdown",
        "key": "meal_preference",
        "label": "Meal preference",
        "options": [
          "Vegetarian",
          "Chicken",
          "Fish"
        ],
        "required": true
      }
    ],
    "event_config": {
      "event_at": "2026-05-12T19:00:00Z",
      "max_total_quantity": 500,
      "send_ticket_emails": true,
      "ticket_prefix": "GAL",
      "venue": "Pier 57, New York"
    },
    "line_items": [
      {
        "name": "General Admission",
        "quantity": 1,
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      },
      {
        "allow_unit_price_adjustment": true,
        "key": "donation",
        "max_unit_price_money": {
          "amount": 10000,
          "currency": "USD"
        },
        "min_unit_price_money": {
          "amount": 100,
          "currency": "USD"
        },
        "name": "Optional Donation",
        "quantity": 1,
        "suggested_unit_price_money_options": [
          {
            "amount": 500,
            "currency": "USD"
          },
          {
            "amount": 1000,
            "currency": "USD"
          },
          {
            "amount": 2500,
            "currency": "USD"
          }
        ]
      }
    ],
    "metadata": {
      "campaign": "spring-gala"
    },
    "name": "Spring Gala",
    "payment_link_type": "event",
    "payments": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ]
    }
  }'

Get payment link#

GET/v1/payment-links/{payment_link_id}

Requires scope checkouts.payment_links.read or checkouts.payment_links.write

Returns a single payment link by ID.

Path parameters

payment_link_idstringRequired

Flint payment link ID.

Query parameters

expandarray of enum

Supported expansions: subscription_plan. Expansion requires checkouts.payment_links.read plus commerce.subscription_plans.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=subscription_plan&expand=subscription_plan, or pass one comma-separated value.

subscription_plan

Response · 200

Same response as Create payment link.

curl https://api.withflintpay.com/v1/payment-links/pl_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "completed_count": 3,
    "created_at": "2026-03-17T14:30:00Z",
    "custom_fields": [
      {
        "custom_field_type": "dropdown",
        "key": "meal_preference",
        "label": "Meal preference",
        "options": [
          "Vegetarian",
          "Chicken",
          "Fish"
        ],
        "payment_link_custom_field_id": "plcf_123",
        "required": true
      }
    ],
    "description": "Event checkout",
    "event_config": {
      "event_at": "2026-05-12T19:00:00Z",
      "max_total_quantity": 500,
      "send_ticket_emails": true,
      "ticket_prefix": "GAL",
      "venue": "Pier 57, New York"
    },
    "image": {
      "alt": "Spring gala",
      "height": 900,
      "url": "https://images.withflintpay.com/ia_spring_gala/original",
      "width": 1600
    },
    "line_items": [
      {
        "is_catalog_item_unavailable": false,
        "key": "general-admission",
        "name": "General Admission",
        "payment_link_line_item_id": "plli_123",
        "quantity": 1,
        "unit_price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      }
    ],
    "merchant_id": "mer_123",
    "metadata": {
      "campaign": "spring-gala"
    },
    "name": "Spring Gala",
    "payment_link_id": "pl_123",
    "payment_link_type": "event",
    "payments": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ]
    },
    "status": "active",
    "total_quantity_sold": 42,
    "updated_at": "2026-03-17T14:30:00Z",
    "url": "https://checkout.withflintpay.com/pay/pl_123",
    "version": 1
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update payment link#

PATCH/v1/payment-links/{payment_link_id}Idempotent

Requires scope checkouts.payment_links.write

Updates a payment link. To replace line items, custom fields, or delivery methods, send the complete array with `expected_version`.

Path parameters

payment_link_idstringRequired

Flint payment link ID.

Request body

custom_fieldsarray of object

Replaces all custom fields atomically. Include an existing payment_link_custom_field_id to retain that member, omit the ID to create a member, and omit a previous member to remove it. Send an empty array to clear all custom fields, omit custom_fields to leave it unchanged, and do not send null.

custom_textobject

customer_collectionobject

delivery_method_idsarray of string

descriptionstring

donation_max_amount_moneyobject or null

Maximum donation amount. Send null to clear the maximum.

donation_min_amount_moneyobject or null

Minimum donation amount. Send null to clear the minimum.

donation_suggested_amount_money_optionsarray of object

Suggested donation amounts. Send an empty array to clear suggested amounts.

event_configobject

expected_versioninteger

Payment link version last read by the caller. Required when line_items, custom_fields, or delivery_method_ids is present.

expirationobject

external_reference_idstring

Caller-owned identifier for this resource in an external system.

imageobject or null

inactive_messagestring

inventory_routing_sourceone of

legalobject

line_itemsarray of one of

Replaces all line items atomically. Include an existing payment_link_line_item_id to retain that member, omit the ID to create a member, and omit a previous member to remove it. Omit line_items to leave it unchanged. Null is not accepted.

max_completionsinteger

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API. Metadata pairs plus custom fields must not exceed 44; 6 of the order's 50 pairs are reserved for Flint. Metadata keys and values, custom_field_ keys and largest possible answers, and Flint metadata must fit within 32768 UTF-8 bytes. Text answers are budgeted at four bytes per Unicode code point, including optional fields. If the combined budget is exceeded, lower max_length on some fields, use fewer custom fields, or reduce metadata. These limits apply to standard and plan links and are checked against the merged configuration on update.

namestring

paymentsobject

promotion_configobject

redirectsobject

statusenum

active
inactive

taxobject

themeobject

tipobject

Response · 200

Same response as Create payment link.

curl -X PATCH https://api.withflintpay.com/v1/payment-links/pl_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "description": "Updated public description",
    "event_config": {
      "venue": "Pier 59, New York"
    },
    "expected_version": 3,
    "inactive_message": "Sales are currently paused.",
    "max_completions": 100,
    "payments": {
      "enabled_payment_options": [
        "card",
        "apple_pay",
        "google_pay"
      ]
    }
  }'

Get public payment link#

GET/v1/payment-links/{payment_link_id}/public

No API key required

Returns the sanitized buyer-facing payment-link snapshot and a private resolution context for this browser operation.

Path parameters

payment_link_idstringRequired

Flint payment link ID.

Response · 200

dataobjectRequired

metaobject

request_idstring

curl https://api.withflintpay.com/v1/payment-links/pl_123/public \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "checkout_theme": {
      "accent_color": "#f59e0b",
      "primary_color": "#0f766e"
    },
    "merchant_icon": {
      "alt": "Merchant icon",
      "height": 256,
      "url": "https://images.withflintpay.com/ia_merchant_icon/original",
      "width": 256
    },
    "merchant_logo": {
      "alt": "Merchant logo",
      "height": 512,
      "url": "https://images.withflintpay.com/ia_merchant_logo/original",
      "width": 512
    },
    "merchant_name": "Cedar & Stone Coffee",
    "payment_link": {
      "completed_count": 3,
      "custom_fields": [
        {
          "custom_field_type": "dropdown",
          "key": "roast_preference",
          "label": "Roast preference",
          "options": [
            "Light",
            "Medium",
            "Dark"
          ],
          "payment_link_custom_field_id": "plcf_123",
          "required": true
        }
      ],
      "description": "Monthly coffee membership",
      "image": {
        "alt": "Monthly roast box",
        "height": 800,
        "url": "https://images.withflintpay.com/ia_roast_box/original",
        "width": 1200
      },
      "name": "Roaster's club membership",
      "payment_link_id": "pl_123",
      "payment_link_type": "standard",
      "payments": {
        "enabled_payment_options": [
          "card",
          "apple_pay",
          "google_pay"
        ]
      },
      "status": "active",
      "subscription_plan_id": "plan_01JZEXAMPLEPLAN1234567890",
      "version": 1
    },
    "resolution_context": "plrc_v1.example_signed_resolution_context",
    "resolution_context_expires_at": "2026-05-13T19:00:00Z",
    "resolution_context_start_deadline_at": "2026-05-13T18:58:00Z",
    "subscription_preview": {
      "billing_interval": "monthly",
      "billing_interval_count": 1,
      "contract_term_months": 12,
      "delivery_required": false,
      "early_termination_fee_money": {
        "amount": 5000,
        "currency": "USD"
      },
      "plan_image": {
        "alt": "Monthly roast box",
        "height": 800,
        "url": "https://images.withflintpay.com/ia_roast_box/original",
        "width": 1200
      },
      "plan_name": "Roaster's club",
      "recurring_total_money": {
        "amount": 2400,
        "currency": "USD"
      },
      "setup_fee_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "trial_period_days": 14
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Resolve payment link#

POST/v1/payment-links/{payment_link_id}/resolveIdempotent

No API key required

Creates a buyer checkout session from an active payment link. Catalog-backed modifier availability is frozen onto the checkout session and selected modifiers are resolved onto the backing order.

Path parameters

payment_link_idstringRequired

Flint payment link ID.

Request body

custom_field_valuesmap of string

modifiersmap of object

quantity_overridesmap of integer

Map of keys to whole-number quantity overrides; fractional quantities are not supported.

resolution_contextstringRequired

unit_price_overridesmap of object

Response · 201

dataobjectRequired

The checkout session and the credential to operate it. For hosted checkout, send the buyer to checkout_session.url. For embedded checkout, pass checkout_access.checkout_auth_token to your checkout client.

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/payment-links/pl_123/resolve \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "custom_field_values": {
      "meal_preference": "Vegetarian"
    },
    "modifiers": {
      "general-admission": {
        "modifiers": [
          {
            "modifier_id": "mod_01JZEXAMPLEMODIFIER123456",
            "quantity": 1
          },
          {
            "text": {
              "modifier_group_id": "mg_01JZEXAMPLEGROUP1234567",
              "value": "Extra hot"
            }
          }
        ]
      }
    },
    "quantity_overrides": {
      "general-admission": 2
    },
    "resolution_context": "plrc_v1.example_signed_resolution_context"
  }'

Was this helpful?