Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Path Parameters

id
string
required

The payment link id (pl_…).

Body

application/json

All fields are optional; absent fields are not modified. Providing line_items requires currency and amount_total.

name
string | null
description
string | null
line_items
object[] | null

Replaces the existing line items. Requires currency and amount_total.

optional_items
object[] | null

Replaces optional items. Send an empty array to clear.

amount_total
integer | null

New total in minor units. Required when line_items is provided.

currency
string | null

New currency. Required when line_items is provided.

collect_config
object | null

Specifies which contact fields to collect at checkout and how.

custom_fields
object[] | null

Replaces custom fields. Send an empty array to clear.

submit_type
enum<string> | null
Available options:
pay,
book,
donate
Available options:
one_time,
subscription,
invoice
theme_id
string | null
branding
object | null

Visual overrides for the hosted checkout page.

success_url
string | null
cancel_url
string | null
payment_intent_data
object | null

Payment-intent configuration forwarded when a checkout session is created from this link.

inactive_message
string | null
metadata
object

Response

The updated payment link.

id
string
required

Payment link identifier (pl_…).

object
enum<string>
required
Available options:
payment_link
merchant_id
string
required
livemode
boolean
required

True for live-mode links; false for test-mode.

active
boolean
required

False when deactivated; the hosted checkout shows an inactive state.

name
string
required
description
string | null
required
url
string
required

The public checkout URL (https://buy.ionicfi.com/c/…).

currency
string
required

Three-letter ISO currency code.

amount_total
integer
required

Total in minor units.

line_items
object[]
required
collect_config
object
required

Specifies which contact fields to collect at checkout and how.

submit_type
enum<string> | null
required
Available options:
pay,
book,
donate
Available options:
one_time,
subscription,
invoice
theme_id
string | null
required
success_url
string | null
required
cancel_url
string | null
required
inactive_message
string | null
required
metadata
object
required
created_at
integer
required

Unix epoch seconds.

updated_at
integer
required
optional_items
object[]

Omitted when the link has no optional add-ons.

custom_fields
object[]

Omitted when the link has no custom fields.

branding
object | null

Omitted when no branding overrides are set.

payment_intent_data
object | null

Omitted when no payment-intent overrides are set.