API ReferencePayment Links

Create Payment Link

View as Markdown
Create a new payment link with line items. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.
namestring or nullOptional<=255 characters
Internal name for the payment link
modeenumOptionalDefaults to payment

Payment mode: ‘payment’ for one-time, ‘subscription’ for recurring, ‘setup’ for payment method collection

customer_idstring or nullOptional

Pre-assigned customer Identifier

coupon_idstring or nullOptional
ID of coupon to apply to this payment link
free_trial_daysinteger or nullOptional1-730

Free trial period in days (subscription mode only)

success_urlstringOptionalDefaults to
HTTPS URL to redirect to on successful payment. If omitted, no redirect after payment.
return_urlstring or nullOptional
HTTPS URL to redirect to on cancellation
expires_in_hoursintegerOptional1-720Defaults to 24

Hours until checkout session expires (max 30 days)

allow_cart_editbooleanOptionalDefaults to false
Allow customers to edit cart items during checkout
accepted_payment_methodslist of strings or nullOptional

List of accepted payment method types (e.g. credit_card, ach, apple_pay, google_pay). Null means all methods accepted.

line_itemslist of objects or nullOptional

List of line items for the payment link (max 100 items). Required for payment/subscription modes unless package_ids is provided.

package_idslist of strings or nullOptional

Package Identifiers for package-based links. Mutually exclusive with line_items.

metadatamap from strings to any or nullOptional
Custom metadata for the payment link

Response

Successful Response
idstring
Unique payment link identifier
secure_tokenstring
Secure token for the public URL
urlstring
Public shareable URL
modestring

Payment mode: ‘payment’, ‘subscription’, or ‘setup’

success_urlstring
URL to redirect to on successful payment
expires_in_hoursinteger
Hours until checkout session expires
allow_cart_editboolean
Whether customers can edit cart items during checkout
is_activeboolean
Whether the payment link is active
is_pinnedboolean
Whether the payment link is pinned to the top of the list
created_atdatetime
When the payment link was created
updated_atdatetime
When the payment link was last updated
namestring or nullOptional
Internal name for the payment link
customer_idstring or nullOptional

Pre-assigned customer Identifier

customer_emailstring or nullOptional
Customer email address for display
coupon_idstring or nullOptional
ID of coupon applied to this payment link
promotion_codestring or nullOptional

Promotion code string associated with the coupon (e.g., ‘HALOWEEN20’)

discountobject or nullOptional

Structured discount details when a coupon is applied. Prefer this over the bare coupon_id/promotion_code for display.

free_trial_daysinteger or nullOptional

Free trial period in days (subscription mode only)

return_urlstring or nullOptional
URL to redirect to on cancellation
accepted_payment_methodslist of strings or nullOptional
List of accepted payment method types. Null means all methods accepted.
content_typestring or nullOptional

Content type: ‘products’, ‘package’, or null (setup mode)

package_idslist of strings or nullOptional

Package Identifiers (for package-based links)

package_nameslist of strings or nullOptional

Package names for display (for package-based links)

packageslist of objects or nullOptional
Inline package details with contained products and prices
line_itemslist of objectsOptional
List of line items in the payment link
total_amount_atominteger or nullOptional
Total amount of all line items in smallest currency unit
currencyenum or nullOptional

Currency of the payment link (from line items)

metadatamap from strings to any or nullOptional
Custom metadata for the payment link

Errors

422
Unprocessable Entity Error