Update a payment link

Payment Links

Payment Link

Updates a payment link.

Parameters

activeboolean
Whether the payment link’s url is active. If false, customers visiting the URL will be shown a page saying that the link has been deactivated.

line_itemsarray of objects
The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.
- line_items.idstringRequired
  The ID of an existing line item on the payment link.
- line_items.adjustable_quantityobject
  When set, provides configuration for this item’s quantity to be adjusted by the customer during checkout.
  line_items.adjustable_quantity.enabledbooleanRequired
  Set to true if the quantity can be adjusted to any non-negative Integer.
  line_items.adjustable_quantity.maximuminteger
  The maximum quantity the customer can purchase. By default this value is 99. You can specify a value up to 999.
  line_items.adjustable_quantity.minimuminteger
  The minimum quantity the customer can purchase. By default this value is 0. If there is only one item in the cart then that item’s quantity cannot go down to 0.
- line_items.quantityinteger
  The quantity of the line item being purchased.

metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. Metadata associated with this Payment Link will automatically be copied to checkout sessions created by this payment link.

More parameters

after_completionobject
Behavior after the purchase is complete.
- after_completion.typeenumRequired
  The specified behavior after the purchase is complete. Either redirect or hosted_confirmation.
  Possible enum values
  hosted_confirmation
  Displays a message on the hosted surface after the purchase is complete.
  redirect
  Redirects the customer to the specified url after the purchase is complete.
- after_completion.hosted_confirmationobject
  Configuration when type=hosted_confirmation.
  after_completion.hosted_confirmation.custom_messagestring
  A custom message to display to the customer after the purchase is complete.
- after_completion.redirectobject
  Configuration when type=redirect.
  after_completion.redirect.urlstringRequired
  The URL the customer will be redirected to after the purchase is complete. You can embed {CHECKOUT_SESSION_ID} into the URL to have the id of the completed checkout session included.

allow_promotion_codesboolean
Enables user redeemable promotion codes.

automatic_taxobject

Configuration for automatic tax collection.

automatic_tax.enabledbooleanRequired
Set to true to calculate tax automatically using the customer’s location.
Enabling this parameter causes the payment link to collect any billing address information necessary for tax calculation.

automatic_tax.liabilityobjectConnect only

The account that’s liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account.

automatic_tax.liability.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

automatic_tax.liability.accountstringRequired only if type is account
The connected account being referenced when type is account.

billing_address_collectionenum

Configuration for collecting the customer’s billing address. Defaults to auto.

Possible enum values

auto

Checkout will only collect the billing address when necessary. When using automatic_tax, Checkout will collect the minimum number of fields required for tax calculation.

required

Checkout will always collect the customer’s billing address.

custom_fieldsarray of objects
Collect additional information from your customer using custom fields. Up to 3 fields are supported.
- custom_fields.keystringRequired
  String of your choice that your integration can use to reconcile this field. Must be unique to this field, alphanumeric, and up to 200 characters.
- custom_fields.labelobjectRequired
  The label for the field, displayed to the customer.
  custom_fields.label.customstringRequired
  Custom text for the label, displayed to the customer. Up to 50 characters.
  custom_fields.label.typeenumRequired
  The type of the label.
  Possible enum values
  custom
  Set a custom label for the field.
- custom_fields.typeenumRequired
  The type of the field.
  Possible enum values
  dropdown
  Provide a list of options for your customer to select.
  numeric
  Collect a numbers-only field from your customer.
  text
  Collect a string field from your customer.
- custom_fields.dropdownobject
  Configuration for type=dropdown fields.
  custom_fields.dropdown.optionsarray of objectsRequired
  The options available for the customer to select. Up to 200 options allowed.
  custom_fields.dropdown.options.labelstringRequired
  The label for the option, displayed to the customer. Up to 100 characters.
  custom_fields.dropdown.options.valuestringRequired
  The value for this option, not displayed to the customer, used by your integration to reconcile the option selected by the customer. Must be unique to this option, alphanumeric, and up to 100 characters.
- custom_fields.numericobject
  Configuration for type=numeric fields.
  custom_fields.numeric.maximum_lengthinteger
  The maximum character length constraint for the customer’s input.
  custom_fields.numeric.minimum_lengthinteger
  The minimum character length requirement for the customer’s input.
- custom_fields.optionalboolean
  Whether the customer is required to complete the field before completing the Checkout Session. Defaults to false.
- custom_fields.textobject
  Configuration for type=text fields.
  custom_fields.text.maximum_lengthinteger
  The maximum character length constraint for the customer’s input.
  custom_fields.text.minimum_lengthinteger
  The minimum character length requirement for the customer’s input.

custom_textobject
Display additional text for your customers using custom text.
- custom_text.after_submitobject
  Custom text that should be displayed after the payment confirmation button.
  custom_text.after_submit.messagestringRequired
  Text may be up to 1200 characters in length.
- custom_text.shipping_addressobject
  Custom text that should be displayed alongside shipping address collection.
  custom_text.shipping_address.messagestringRequired
  Text may be up to 1200 characters in length.
- custom_text.submitobject
  Custom text that should be displayed alongside the payment confirmation button.
  custom_text.submit.messagestringRequired
  Text may be up to 1200 characters in length.
- custom_text.terms_of_service_acceptanceobject
  Custom text that should be displayed in place of the default terms of service agreement text.
  custom_text.terms_of_service_acceptance.messagestringRequired
  Text may be up to 1200 characters in length.

customer_creationenum

Configures whether checkout sessions created by this payment link create a Customer.

Possible enum values

always

The Checkout Session will always create a Customer when a Session confirmation is attempted.

if_required

The Checkout Session will only create a Customer if it is required for Session confirmation. Currently, only subscription mode Sessions and payment mode Sessions with post-purchase invoices enabled require a Customer.

inactive_messagestring
The custom message to be displayed to a customer when a payment link is no longer active.

invoice_creationobject

Generate a post-purchase Invoice for one-time payments.

invoice_creation.enabledbooleanRequired
Whether the feature is enabled

invoice_creation.invoice_dataobject

Invoice PDF configuration.

invoice_creation.invoice_data.account_tax_idsarray of strings
The account tax IDs associated with the invoice.

invoice_creation.invoice_data.custom_fieldsarray of objects
Default custom fields to be displayed on invoices for this customer.
- invoice_creation.invoice_data.custom_fields.namestringRequired
  The name of the custom field. This may be up to 40 characters.
- invoice_creation.invoice_data.custom_fields.valuestringRequired
  The value of the custom field. This may be up to 140 characters.

invoice_creation.invoice_data.descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users.

invoice_creation.invoice_data.footerstring
Default footer to be displayed on invoices for this customer.

invoice_creation.invoice_data.issuerobjectConnect only

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

invoice_creation.invoice_data.issuer.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

invoice_creation.invoice_data.issuer.accountstringRequired only if type is account
The connected account being referenced when type is account.

invoice_creation.invoice_data.metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

invoice_creation.invoice_data.rendering_optionsobject
Default options for invoice PDF rendering for this customer.
- invoice_creation.invoice_data.rendering_options.amount_tax_displayenum
  How line-item prices and amounts will be displayed with respect to tax on invoice PDFs. One of exclude_tax or include_inclusive_tax. include_inclusive_tax will include inclusive tax (and exclude exclusive tax) in invoice PDF amounts. exclude_tax will exclude all tax (inclusive and exclusive alike) from invoice PDF amounts.
  Possible enum values
  exclude_tax
  include_inclusive_tax

payment_intent_dataobject
A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode.
- payment_intent_data.descriptionstring
  An arbitrary string attached to the object. Often useful for displaying to users.
- payment_intent_data.metadataobject
  Set of key-value pairs that will declaratively set metadata on Payment Intents generated from this payment link. Unlike object-level metadata, this field is declarative. Updates will clear prior values.
- payment_intent_data.statement_descriptorstring
  Text that appears on the customer’s statement as the statement descriptor for a non-card charge. This value overrides the account’s default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs.
  Setting this value for a card charge returns an error. For card charges, set the statement_descriptor_suffix instead.
- payment_intent_data.statement_descriptor_suffixstring
  Provides information about a card charge. Concatenated to the account’s statement descriptor prefix to form the complete statement descriptor that appears on the customer’s statement.
- payment_intent_data.transfer_groupstringConnect only
  A string that identifies the resulting payment as part of a group. See the PaymentIntents use case for connected accounts for details.

payment_method_collectionenum
Specify whether Checkout should collect a payment method. When set to if_required, Checkout will not collect a payment method when the total due for the session is 0.This may occur if the Checkout Session includes a free trial or a discount.
Can only be set in subscription mode. Defaults to always.
If you’d like information on how to collect a payment method outside of Checkout, read the guide on configuring subscriptions with a free trial.
Possible enum values
always
The Checkout Session will always collect a PaymentMethod.
if_required
The Checkout Session will only collect a PaymentMethod if there is an amount due.

payment_method_typesarray of enums
The list of payment method types that customers can use. Pass an empty string to enable dynamic payment methods that use your payment method settings.

restrictionsobject
Settings that restrict the usage of a payment link.
- restrictions.completed_sessionsobjectRequired
  Configuration for the completed_sessions restriction type.
  restrictions.completed_sessions.limitintegerRequired
  The maximum number of checkout sessions that can be completed for the completed_sessions restriction to be met.

shipping_address_collectionobject
Configuration for collecting the customer’s shipping address.
- shipping_address_collection.allowed_countriesarray of enumsRequired
  An array of two-letter ISO country codes representing which countries Checkout should provide as options for shipping locations.
  Possible enum values
  AC
  AD
  AE
  AF
  AG
  AI
  AL
  AM
  AO
  AQ
  Show 227 more

submit_typeenum

Describes the type of transaction being performed in order to customize relevant text on the page, such as the submit button. Changing this value will also affect the hostname in the url property (example: donate.stripe.com).

Possible enum values

auto

Default value. pay will used in all scenarios

book

Recommended when offering bookings. Submit button includes a ‘Book’ label and URLs use the book.stripe.com hostname

donate

Recommended when accepting donations. Submit button includes a ‘Donate’ label and URLs use the donate.stripe.com hostname

pay

Submit button includes a ‘Buy’ label and URLs use the buy.stripe.com hostname

subscribe

Submit button includes a ‘Subscribe’ label and URLs use the buy.stripe.com hostname

subscription_dataobject

When creating a subscription, the specified configuration data will be used. There must be at least one line item with a recurring price to use subscription_data.

subscription_data.invoice_settingsobject

All invoices will be billed using the specified settings.

subscription_data.invoice_settings.issuerobjectConnect only

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

subscription_data.invoice_settings.issuer.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

subscription_data.invoice_settings.issuer.accountstringRequired only if type is account
The connected account being referenced when type is account.

subscription_data.metadataobject
Set of key-value pairs that will declaratively set metadata on Subscriptions generated from this payment link. Unlike object-level metadata, this field is declarative. Updates will clear prior values.

subscription_data.trial_settingsobject

Settings related to subscription trials.

subscription_data.trial_settings.end_behaviorobjectRequired

Defines how the subscription should behave when the user’s free trial ends.

subscription_data.trial_settings.end_behavior.missing_payment_methodenumRequired

Indicates how the subscription should change when the trial ends if the user did not provide a payment method.

Possible enum values

cancel

Cancel the subscription if a payment method is not attached when the trial ends.

create_invoice

Create an invoice when the trial ends, even if the user did not set up a payment method.

pause

Pause the subscription if a payment method is not attached when the trial ends.

tax_id_collectionobject
Controls tax ID collection during checkout.
- tax_id_collection.enabledbooleanRequired
  Enable tax ID collection during checkout. Defaults to false.
- tax_id_collection.requiredenum
  Describes whether a tax ID is required during checkout. Defaults to never.
  Possible enum values
  if_supported
  A tax ID will be required if collection is supported for the selected billing address country.
  never
  Tax ID collection is never required.

Returns

Updated payment link.

POST /v1/payment_links/:id

Server-side language

curl https://api.stripe.com/v1/payment_links/plink_1MoC3ULkdIwHu7ixZjtGpVl2 \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735

Response

{
  "id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
  "object": "payment_link",
  "active": true,
  "after_completion": {
    "hosted_confirmation": {
      "custom_message": null
    },
    "type": "hosted_confirmation"
  },
  "allow_promotion_codes": false,
  "application_fee_amount": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": null
  },
  "billing_address_collection": "auto",
  "consent_collection": null,
  "currency": "usd",
  "custom_fields": [],
  "custom_text": {
    "shipping_address": null,
    "submit": null
  },
  "customer_creation": "if_required",
  "invoice_creation": {
    "enabled": false,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": null,
      "metadata": {},
      "rendering_options": null
    }
  },
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "on_behalf_of": null,
  "payment_intent_data": null,
  "payment_method_collection": "always",
  "payment_method_types": null,
  "phone_number_collection": {
    "enabled": false
  },
  "shipping_address_collection": null,
  "shipping_options": [],
  "submit_type": "auto",
  "subscription_data": {
    "description": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "trial_period_days": null
  },
  "tax_id_collection": {
    "enabled": false
  },
  "transfer_data": null,
  "url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}

Update a payment link

Parameters

activeboolean

line_itemsarray of objects

line_items.idstringRequired

line_items.adjustable_quantityobject

line_items.adjustable_quantity.enabledbooleanRequired

line_items.adjustable_quantity.maximuminteger

line_items.adjustable_quantity.minimuminteger

line_items.quantityinteger

metadataobject

More parametersCollapse all

after_completionobject

after_completion.typeenumRequired

after_completion.hosted_confirmationobject

after_completion.hosted_confirmation.custom_messagestring

after_completion.redirectobject

after_completion.redirect.urlstringRequired

allow_promotion_codesboolean

automatic_taxobject

automatic_tax.enabledbooleanRequired

automatic_tax.liabilityobjectConnect only

automatic_tax.liability.typeenumRequired

automatic_tax.liability.accountstringRequired only if type is account

billing_address_collectionenum

custom_fieldsarray of objects

custom_fields.keystringRequired

custom_fields.labelobjectRequired

custom_fields.label.customstringRequired

custom_fields.label.typeenumRequired

custom_fields.typeenumRequired

custom_fields.dropdownobject

custom_fields.dropdown.optionsarray of objectsRequired

custom_fields.dropdown.options.labelstringRequired

custom_fields.dropdown.options.valuestringRequired

custom_fields.numericobject

custom_fields.numeric.maximum_lengthinteger

custom_fields.numeric.minimum_lengthinteger

custom_fields.optionalboolean

custom_fields.textobject

custom_fields.text.maximum_lengthinteger

custom_fields.text.minimum_lengthinteger

custom_textobject

custom_text.after_submitobject

custom_text.after_submit.messagestringRequired

custom_text.shipping_addressobject

custom_text.shipping_address.messagestringRequired

custom_text.submitobject

custom_text.submit.messagestringRequired

custom_text.terms_of_service_acceptanceobject

custom_text.terms_of_service_acceptance.messagestringRequired

customer_creationenum

inactive_messagestring

invoice_creationobject

invoice_creation.enabledbooleanRequired

invoice_creation.invoice_dataobject

invoice_creation.invoice_data.account_tax_idsarray of strings

invoice_creation.invoice_data.custom_fieldsarray of objects

invoice_creation.invoice_data.custom_fields.namestringRequired

invoice_creation.invoice_data.custom_fields.valuestringRequired

invoice_creation.invoice_data.descriptionstring

invoice_creation.invoice_data.footerstring

invoice_creation.invoice_data.issuerobjectConnect only

invoice_creation.invoice_data.issuer.typeenumRequired

invoice_creation.invoice_data.issuer.accountstringRequired only if type is account

invoice_creation.invoice_data.metadataobject

invoice_creation.invoice_data.rendering_optionsobject

invoice_creation.invoice_data.rendering_options.amount_tax_displayenum

payment_intent_dataobject

payment_intent_data.descriptionstring

payment_intent_data.metadataobject

payment_intent_data.statement_descriptorstring

payment_intent_data.statement_descriptor_suffixstring

payment_intent_data.transfer_groupstringConnect only

payment_method_collectionenum

payment_method_typesarray of enums

restrictionsobject

restrictions.completed_sessionsobjectRequired

restrictions.completed_sessions.limitintegerRequired

shipping_address_collectionobject

More parameters