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 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 coupon support.

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

Endpoints

GET/v1/payment-links
POST/v1/payment-links
GET/v1/payment-links/{payment_link_id}
PATCH/v1/payment-links/{payment_link_id}
POST/v1/payment-links/{payment_link_id}/activate
POST/v1/payment-links/{payment_link_id}/custom-fields
PATCH/v1/payment-links/{payment_link_id}/custom-fields/{payment_link_custom_field_id}
DELETE/v1/payment-links/{payment_link_id}/custom-fields/{payment_link_custom_field_id}
POST/v1/payment-links/{payment_link_id}/deactivate
POST/v1/payment-links/{payment_link_id}/line-items
PATCH/v1/payment-links/{payment_link_id}/line-items/{payment_link_line_item_id}
DELETE/v1/payment-links/{payment_link_id}/line-items/{payment_link_line_item_id}
POST/v1/payment-links/{payment_link_id}/resolve

List payment links #

GET/v1/payment-links

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.

activeinactive

querystring

Search across payment link name and description.

payment_link_typeenum

Filter by payment link type.

standarddonationevent

has_planboolean

Filter by whether the payment link references a subscription plan.

sort_byenum

Sort field.

created_atupdated_at

sort_directionenum

Sort direction.

ascdesc

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

Bash

curl https://api.withflintpay.com/v1/payment-links \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

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

Create payment link #

POST/v1/payment-linksIdempotent

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

Request body

couponobject

custom_fieldsarray of object

custom_textobject

customer_collectionobject

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

image_urlstring

inactive_messagestring

legalobject

line_itemsarray of one of

max_completionsinteger

metadatamap of string

namestringrequired

payment_link_typeenum

standarddonationevent

paymentsobject

plan_idstring

redirectsobject

taxobject

themeobject

tipobject

Response · 201

dataobjectrequired

metaobject

request_idstring

Bash

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

JSON

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

Get payment link #

GET/v1/payment-links/{payment_link_id}

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. Send repeated expand parameters as the canonical form, for example expand=subscription_plan&expand=subscription_plan. Comma-separated values, expand[]=subscription_plan, and numeric expand[0]=subscription_plan are accepted for common client compatibility.

subscription_plan

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl https://api.withflintpay.com/v1/payment-links/pl_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payment link #

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

Updates the mutable template fields on a payment link. Line items and custom fields use dedicated collection mutation endpoints.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

Request body

couponobject

custom_textobject

customer_collectionobject

descriptionstring

donation_max_amount_moneyobject

Maximum donation amount. Send null to clear the maximum.

donation_min_amount_moneyobject

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

expirationobject

image_urlstring

inactive_messagestring

legalobject

max_completionsinteger

metadatamap of string

namestring

paymentsobject

redirectsobject

taxobject

themeobject

tipobject

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

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

JSON

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

Activate payment link #

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

Transitions a payment link to active status.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/payment-links/pl_123/activate \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

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

Add payment link custom fields #

POST/v1/payment-links/{payment_link_id}/custom-fieldsIdempotent

Add payment link custom fields.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

Request body

custom_fieldsarray of objectrequired

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/payment-links/pl_123/custom-fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'

JSON

{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update payment link custom field #

PATCH/v1/payment-links/{payment_link_id}/custom-fields/{payment_link_custom_field_id}Idempotent

Update payment link custom field.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

payment_link_custom_field_idstringrequired

Stable payment link custom field ID.

Request body

custom_field_typeenum

textdropdowncheckboxtextarea

keystring

labelstring

max_lengthinteger

optionsarray of string

placeholderstring

positioninteger

requiredboolean

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X PATCH https://api.withflintpay.com/v1/payment-links/pl_123/custom-fields/plcf_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'

JSON

{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete payment link custom field #

DELETE/v1/payment-links/{payment_link_id}/custom-fields/{payment_link_custom_field_id}Idempotent

Delete payment link custom field.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

payment_link_custom_field_idstringrequired

Stable payment link custom field ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X DELETE https://api.withflintpay.com/v1/payment-links/pl_123/custom-fields/plcf_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Deactivate payment link #

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

Transitions a payment link to inactive status.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/payment-links/pl_123/deactivate \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

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

Add payment link line items #

POST/v1/payment-links/{payment_link_id}/line-itemsIdempotent

Add payment link line items.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

Request body

line_itemsarray of one ofrequired

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/payment-links/pl_123/line-items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'

JSON

{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update payment link line item #

PATCH/v1/payment-links/{payment_link_id}/line-items/{payment_link_line_item_id}Idempotent

Update payment link line item.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

payment_link_line_item_idstringrequired

Stable payment link line item ID.

Request body

allow_quantity_adjustmentboolean

allow_unit_price_adjustmentboolean

descriptionstring

max_quantityinteger

Whole-number quantity; fractional quantities are not supported.

max_unit_price_moneyobject

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

min_quantityinteger

Whole-number quantity; fractional quantities are not supported.

min_unit_price_moneyobject

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

namestring

quantityinteger

Whole-number quantity; fractional quantities are not supported.

suggested_unit_price_money_optionsarray of object

taxobject

unit_price_moneyobject

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

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X PATCH https://api.withflintpay.com/v1/payment-links/pl_123/line-items/plli_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'

JSON

{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete payment link line item #

DELETE/v1/payment-links/{payment_link_id}/line-items/{payment_link_line_item_id}Idempotent

Delete payment link line item.

Path parameters

payment_link_idstringrequired

Flint payment link ID.

payment_link_line_item_idstringrequired

Stable payment link line item ID.

Response · 200

dataobjectrequired

metaobject

request_idstring

Bash

curl -X DELETE https://api.withflintpay.com/v1/payment-links/pl_123/line-items/plli_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {},
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Resolve payment link #

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

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.

unit_price_overridesmap of object

Response · 201

dataobjectrequired

Checkout-session launch result returned by one-time hosted checkout entry points.

metaobject

request_idstring

Bash

curl -X POST https://api.withflintpay.com/v1/payment-links/pl_123/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "quantity_overrides": {
      "general-admission": 2
    },
    "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"
            }
          }
        ]
      }
    }
  }'

JSON

{
  "data": {
    "checkout_session": {
      "checkout_session_id": "cs_123",
      "theme": {
        "primary_color": "#0f766e",
        "title": "Spring Gala Checkout"
      },
      "payments": {
        "enabled_payment_options": [
          "card",
          "apple_pay",
          "google_pay"
        ],
        "payment_note": "Thank you for your purchase."
      },
      "customer_collection": {
        "require_email": true
      },
      "redirects": {
        "success_redirect_url": "https://example.com/success",
        "cancel_redirect_url": "https://example.com/canceled"
      },
      "metadata": {
        "campaign": "spring_launch"
      },
      "status": "open",
      "order_id": "ord_123",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
      "source": "api",
      "coupon": {
        "enabled": true
      }
    },
    "hosted_checkout": {
      "url": "https://checkout.withflintpay.com/checkout/cs_123#checkout_token=tok_123",
      "checkout_auth_token": "csauth_123"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Rate this doc