API Reference

Payment Links

Payment Links allow you to create a shareable, hosted payment page for your products or services. This is a simple way to sell online without writing any front-end code. This section details how to create and manage Payment Links using the SDK.
For more information on the items that go into a payment link, see the Products & Prices documentation.
The Payment Link Object#A PaymentLink object contains all the information needed to present a payment page to a customer. Here are some of its key attributes:
Attribute
Type
Description
id
string
Unique identifier for the payment link.
active
boolean
Whether the payment link is currently active and can be used for payments.
name
string
The internal name of the payment link, not visible to customers.
line_items
Array<Object>
The items being sold. Each object must contain a price_id and quantity.
currency_id
string
The three-letter ISO currency code.
after_completion
Object
Behavior after a successful payment. Can be a redirect to a URL or a hosted_confirmation page.
allow_promotion_codes
boolean
Toggles the ability for customers to apply promotion codes.
custom_fields
Array<Object>
A list of custom fields to collect from the customer.
billing_address_collection
string
Specifies whether to collect the customer's billing address. Can be 'auto' or 'required'.
metadata
Object
A set of key-value pairs that you can attach to an object. Useful for storing additional information.

Create a Payment Link#Creates a new payment link.
Parameters#Name
Type
Description
name
string
Required. The internal name for the payment link.
currency_id
string
Required. The currency for the payment.
line_items
Array<Object>
Required. A list of items for purchase. Each item is an object containing price_id (string) and quantity (number).
active
boolean
Whether the link is active. Defaults to true.
after_completion
Object
Defines what happens after a successful payment. Set { "type": "redirect", "redirect": { "url": "https://yoursite.com/success" } } to redirect the customer.
allow_promotion_codes
boolean
Enables or disables the use of promotion codes. Defaults to false.
billing_address_collection
string
Set to 'required' to always collect the customer's billing address. Defaults to 'auto'.
custom_fields
Array<Object>
Collect custom information from your customer. See the CustomField type for the object structure.
metadata
Record<string, any>
Key-value data to associate with the payment link.
Returns#Returns a PaymentLink object if the call is successful.
Example#async function createPaymentLink() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      name: 'Monthly Subscription Box',
      currency_id: 'usd',
      line_items: [
        {
          price_id: 'price_12345',
          quantity: 1,
        },
      ],
      after_completion: {
        type: 'redirect',
        redirect: {
          url: 'https://example.com/thanks',
        },
      },
      metadata: {
        order_id: '6735',
      },
    });
    console.log(paymentLink);
  } catch (error) {
    console.error('Error creating payment link:', error);
  }
}

createPaymentLink();Response Example#{
  "id": "pl_abc123",
  "active": true,
  "livemode": false,
  "name": "Monthly Subscription Box",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "currency_id": "usd",
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com/thanks"
    }
  },
  "allow_promotion_codes": false,
  "custom_fields": [],
  "customer_creation": "if_required",
  "billing_address_collection": "auto",
  "submit_type": "auto",
  "metadata": {
    "order_id": "6735"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
Retrieve a Payment Link#Retrieves the details of an existing payment link.
Parameters#Name
Type
Description
id
string
Required. The ID of the payment link to retrieve.
Returns#Returns a PaymentLink object, but with associated resources like line_items expanded.
Example#async function retrievePaymentLink(paymentLinkId) {
  try {
    const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);
    console.log(paymentLink);
  } catch (error) {
    console.error('Error retrieving payment link:', error);
  }
}

retrievePaymentLink('pl_abc123');Response Example#{
  "id": "pl_abc123",
  "active": true,
  "livemode": false,
  "name": "Monthly Subscription Box",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "currency_id": "usd",
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com/thanks"
    }
  },
  "allow_promotion_codes": false,
  "custom_fields": [],
  "customer_creation": "if_required",
  "billing_address_collection": "auto",
  "submit_type": "auto",
  "metadata": {
    "order_id": "6735"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2023-10-27T10:00:00.000Z"
}
Update a Payment Link#Updates a payment link by setting the values of the parameters passed.
Parameters#Name
Type
Description
id
string
Required. The ID of the payment link to update.
data
Object
Required. An object containing the fields to update. You can update fields like active, metadata, or line_items.
Returns#Returns the updated PaymentLink object.
Example#async function updatePaymentLink(paymentLinkId) {
  try {
    const updatedLink = await payment.paymentLinks.update(paymentLinkId, {
      metadata: { order_id: '6735-updated' },
      active: false
    });
    console.log(updatedLink);
  } catch (error) {
    console.error('Error updating payment link:', error);
  }
}

updatePaymentLink('pl_abc123');Response Example#{
  "id": "pl_abc123",
  "active": false,
  "metadata": {
    "order_id": "6735-updated"
  }
}
Archive a Payment Link#Archives a payment link, making it inactive. This action is equivalent to updating the link with active: false.
Parameters#Name
Type
Description
id
string
Required. The ID of the payment link to archive.
Returns#Returns the archived PaymentLink object.
Example#async function archivePaymentLink(paymentLinkId) {
  try {
    const archivedLink = await payment.paymentLinks.archive(paymentLinkId);
    console.log('Archived:', archivedLink.active);
  } catch (error) {
    console.error('Error archiving payment link:', error);
  }
}

archivePaymentLink('pl_abc123');Response Example#{
  "id": "pl_abc123",
  "active": false,
  "livemode": false,
  "name": "Monthly Subscription Box",
  "metadata": {
    "order_id": "6735-updated"
  },
  "updated_at": "2023-10-27T10:05:00.000Z"
}
List all Payment Links#Returns a paginated list of your payment links.
Parameters#Name
Type
Description
page
number
The page number for pagination. Defaults to 1.
pageSize
number
The number of items per page. Defaults to 20.
order
Array<string>
An array to specify sorting order, e.g., ['created_at', 'DESC'].
starting_after
string
A cursor for pagination. Returns objects after this ID.
ending_before
string
A cursor for pagination. Returns objects before this ID.
Returns#Returns a paginated object containing a list of PaymentLink objects and the total count.
Example#async function listPaymentLinks() {
  try {
    const paymentLinks = await payment.paymentLinks.list({ pageSize: 5 });
    console.log(`Found ${paymentLinks.count} links.`);
    paymentLinks.list.forEach(link => {
      console.log(`- ${link.name} (ID: ${link.id})`);
    });
  } catch (error) {
    console.error('Error listing payment links:', error);
  }
}

listPaymentLinks();Response Example#{
  "count": 50,
  "list": [
    {
      "id": "pl_abc123",
      "name": "Monthly Subscription Box",
      "active": false
    },
    {
      "id": "pl_def456",
      "name": "One-Time Consultation",
      "active": true
    }
  ]
}With these tools, you can programmatically manage your payment links. To see how a payment link is used to initiate a customer purchase, please see the Checkout Sessions documentation.

Attribute	Type	Description
`id`	`string`	Unique identifier for the payment link.
`active`	`boolean`	Whether the payment link is currently active and can be used for payments.
`name`	`string`	The internal name of the payment link, not visible to customers.
`line_items`	`Array<Object>`	The items being sold. Each object must contain a `price_id` and `quantity`.
`currency_id`	`string`	The three-letter ISO currency code.
`after_completion`	`Object`	Behavior after a successful payment. Can be a `redirect` to a URL or a `hosted_confirmation` page.
`allow_promotion_codes`	`boolean`	Toggles the ability for customers to apply promotion codes.
`custom_fields`	`Array<Object>`	A list of custom fields to collect from the customer.
`billing_address_collection`	`string`	Specifies whether to collect the customer's billing address. Can be `'auto'` or `'required'`.
`metadata`	`Object`	A set of key-value pairs that you can attach to an object. Useful for storing additional information.

Name	Type	Description
`name`	`string`	Required. The internal name for the payment link.
`currency_id`	`string`	Required. The currency for the payment.
`line_items`	`Array<Object>`	Required. A list of items for purchase. Each item is an object containing `price_id` (string) and `quantity` (number).
`active`	`boolean`	Whether the link is active. Defaults to `true`.
`after_completion`	`Object`	Defines what happens after a successful payment. Set `{ "type": "redirect", "redirect": { "url": "https://yoursite.com/success" } }` to redirect the customer.
`allow_promotion_codes`	`boolean`	Enables or disables the use of promotion codes. Defaults to `false`.
`billing_address_collection`	`string`	Set to `'required'` to always collect the customer's billing address. Defaults to `'auto'`.
`custom_fields`	`Array<Object>`	Collect custom information from your customer. See the `CustomField` type for the object structure.
`metadata`	`Record<string, any>`	Key-value data to associate with the payment link.

Name	Type	Description
`id`	`string`	Required. The ID of the payment link to update.
`data`	`Object`	Required. An object containing the fields to update. You can update fields like `active`, `metadata`, or `line_items`.

Name	Type	Description
`page`	`number`	The page number for pagination. Defaults to `1`.
`pageSize`	`number`	The number of items per page. Defaults to `20`.
`order`	`Array<string>`	An array to specify sorting order, e.g., `['created_at', 'DESC']`.
`starting_after`	`string`	A cursor for pagination. Returns objects after this ID.
`ending_before`	`string`	A cursor for pagination. Returns objects before this ID.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Payment Links

The Payment Link Object#

Create a Payment Link#

Parameters#

Returns#

Example#

Response Example#

Retrieve a Payment Link#

Parameters#

Returns#

Example#

Response Example#

Update a Payment Link#

Parameters#

Returns#

Example#

Response Example#

Archive a Payment Link#

Parameters#

Returns#

Example#

Response Example#

List all Payment Links#

Parameters#

Returns#

Example#

Response Example#

Payment Methods

Checkout Sessions