A valid request URL is required to generate request examples{
"id": "<string>",
"object": "payment_link",
"merchant_id": "<string>",
"livemode": true,
"active": true,
"name": "<string>",
"description": "<string>",
"url": "<string>",
"currency": "<string>",
"amount_total": 123,
"line_items": [
{
"price_id": "<string>",
"quantity": 2,
"adjustable_quantity": {
"minimum": 123,
"maximum": 123
}
}
],
"collect_config": {
"email": "required",
"name": "required",
"phone": "required",
"address": "required",
"require_full_billing_address": true,
"require_shipping_address": true,
"require_phone": true,
"wallet_billing_mode": "min"
},
"submit_type": "pay",
"link_type": "one_time",
"theme_id": "<string>",
"success_url": "<string>",
"cancel_url": "<string>",
"inactive_message": "<string>",
"metadata": {},
"created_at": 123,
"updated_at": 123,
"optional_items": [
{
"price_id": "<string>",
"quantity": 2,
"adjustable_quantity": {
"minimum": 123,
"maximum": 123
}
}
],
"custom_fields": [
{
"key": "<string>",
"label": "<string>",
"field_type": "text",
"required": true,
"options": [
"<string>"
]
}
],
"branding": {
"logo_url": "<string>",
"icon_url": "<string>",
"primary_color": "<string>",
"background_color": "<string>",
"font_family": "Inter",
"border_radius": "rounded"
},
"payment_intent_data": {
"capture_method": "automatic",
"setup_future_usage": "on_session",
"description": "<string>",
"reference": "<string>",
"metadata": {}
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "currency and amount_total are required when updating line_items"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "PAYMENT_LINK_NOT_FOUND",
"message": "payment link not found"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Update a payment link
Updates mutable fields on an existing payment link. All fields are optional;
only those present in the request body are changed. When line_items is
provided, currency and amount_total are also required. Sending an empty
array for optional_items or custom_fields clears those lists.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "payment_link",
"merchant_id": "<string>",
"livemode": true,
"active": true,
"name": "<string>",
"description": "<string>",
"url": "<string>",
"currency": "<string>",
"amount_total": 123,
"line_items": [
{
"price_id": "<string>",
"quantity": 2,
"adjustable_quantity": {
"minimum": 123,
"maximum": 123
}
}
],
"collect_config": {
"email": "required",
"name": "required",
"phone": "required",
"address": "required",
"require_full_billing_address": true,
"require_shipping_address": true,
"require_phone": true,
"wallet_billing_mode": "min"
},
"submit_type": "pay",
"link_type": "one_time",
"theme_id": "<string>",
"success_url": "<string>",
"cancel_url": "<string>",
"inactive_message": "<string>",
"metadata": {},
"created_at": 123,
"updated_at": 123,
"optional_items": [
{
"price_id": "<string>",
"quantity": 2,
"adjustable_quantity": {
"minimum": 123,
"maximum": 123
}
}
],
"custom_fields": [
{
"key": "<string>",
"label": "<string>",
"field_type": "text",
"required": true,
"options": [
"<string>"
]
}
],
"branding": {
"logo_url": "<string>",
"icon_url": "<string>",
"primary_color": "<string>",
"background_color": "<string>",
"font_family": "Inter",
"border_radius": "rounded"
},
"payment_intent_data": {
"capture_method": "automatic",
"setup_future_usage": "on_session",
"description": "<string>",
"reference": "<string>",
"metadata": {}
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "currency and amount_total are required when updating line_items"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "PAYMENT_LINK_NOT_FOUND",
"message": "payment link not found"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Path Parameters
The payment link id (pl_…).
Body
All fields are optional; absent fields are not modified. Providing line_items requires currency and amount_total.
New display name shown on the hosted checkout.
New description shown on the checkout page.
Replaces the existing line items. Requires currency and amount_total.
Show child attributes
Show child attributes
Replaces optional items. Send an empty array to clear.
Show child attributes
Show child attributes
New total in minor units. Required when line_items is provided.
New currency. Required when line_items is provided.
Specifies which contact fields to collect at checkout and how.
Show child attributes
Show child attributes
Replaces custom fields. Send an empty array to clear.
Show child attributes
Show child attributes
Label for the checkout submit button.
pay, book, donate The kind of payment the link collects: one_time, subscription, or invoice.
one_time, subscription, invoice Theme id to apply to the checkout page.
Visual overrides for the hosted checkout page.
Show child attributes
Show child attributes
URL to redirect to after a successful payment.
URL to redirect to if the buyer cancels.
Payment-intent configuration forwarded when a checkout session is created from this link.
Show child attributes
Show child attributes
Message shown on the checkout when the link is inactive.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
Response
The updated payment link.
Payment link identifier (pl_…).
payment_link ID of the account that owns the payment link (mer_…).
True for live-mode links; false for test-mode.
False when deactivated; the hosted checkout shows an inactive state.
Display name shown on the hosted checkout.
Description shown on the checkout page.
The public checkout URL (https://buy.ionicfi.com/c/…).
Three-letter ISO currency code.
Total in minor units.
Price references that make up the order.
Show child attributes
Show child attributes
Specifies which contact fields to collect at checkout and how.
Show child attributes
Show child attributes
Label for the checkout submit button.
pay, book, donate The kind of payment the link collects: one_time, subscription, or invoice.
one_time, subscription, invoice Theme id applied to the checkout page.
URL to redirect to after a successful payment.
URL to redirect to if the buyer cancels.
Message shown on the checkout when the link is inactive.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
Unix epoch seconds.
Unix epoch seconds when the link was last updated.
Omitted when the link has no optional add-ons.
Show child attributes
Show child attributes
Omitted when the link has no custom fields.
Show child attributes
Show child attributes
Omitted when no branding overrides are set.
Show child attributes
Show child attributes
Omitted when no payment-intent overrides are set.
Show child attributes
Show child attributes