> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 03690608-fb36-43ef-a401-f855cc4a284f
---
# Payment links API
> Create and manage payment links programmatically.
export const BetaDisclaimerBanner = () =>
This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.
;
export const RequiredIndicator = () => {
return
required
;
};
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Use the payment links API to create and manage shareable checkout pages that accept payment without requiring a shopping cart or custom checkout flow. Each payment link is a hosted page pre-loaded with line items, accepted payment methods, and configurable checkout options.
## Create a payment link
To create a payment link, make a `POST` request to `/commerce/payment-links/2026-09-beta/payment-links`.
The request body must include `paymentLinkName` and `currencyCode`. At least one line item is required, provided via `lineItemObjectIds` or the `lineItems` array.
The following example request body would create a simple payment link that accepts card payments in USD and includes a single line item:
```json theme={null}
{
"paymentLinkName": "Test payment link",
"currencyCode": "USD",
"acceptedPaymentMethods": ["CREDIT_OR_DEBIT_CARD"],
"lineItemObjectIds": ["24560145794","24560153926"]
}
```
| Field | Type | Description |
| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `paymentLinkName` | String | The name displayed on the checkout page. |
| `currencyCode` | String | Three-letter ISO 4217 currency code (e.g., `USD`). |
| `acceptedPaymentMethods` | Array | Payment methods to accept at checkout. Allowed values: `CREDIT_OR_DEBIT_CARD`, `ACH`, `SEPA`, `BACS`, `PADS`. |
| `lineItemObjectIds` | Array | IDs of existing items to include on the checkout page. |
| `lineItems` | Array | Create new line items at the time of payment link creation. Supports `CUSTOM`, `FROM_PRODUCT`, and `CLONE` modes. See [line item create modes](#line-item-create-modes) below. |
| `state` | String | Initial state of the link. Defaults to `ON`. Allowed values: `ON`, `OFF`. |
| `isOneTimeUseEnabled` | Boolean | When `true`, the link can only be used once. Defaults to `false`. |
| `storePaymentMethodAtCheckout` | Boolean | When `true`, stores the buyer's payment method for future use. Defaults to `false`. |
| `collectShippingAddress` | Boolean | When `true`, prompts the buyer for a shipping address. Defaults to `false`. |
| `collectFullBillingAddress` | Boolean | When `true`, prompts the buyer for a full billing address. Defaults to `false`. |
| `discountCodeEnabled` | Boolean | When `true`, allows buyers to enter discount codes at checkout. Defaults to `false`. |
| `automatedSalesTaxEnabled` | Boolean | When `true`, automatically calculates and applies sales tax. Defaults to `false`. |
| `includeEmailInSuccessRedirect` | Boolean | When `true`, appends the buyer's email as a query parameter on the `successUrl`. Defaults to `false`. |
| `enableDefaultCheckoutFees` | Boolean | When `true`, applies the portal's default checkout fees to this payment link. Defaults to `false`. |
| `taxObjectIds` | Array | IDs of existing `TAX` CRM objects to apply. |
| `feeObjectIds` | Array | IDs of existing `FEE` CRM objects to apply. |
| `discountObjectIds` | Array | IDs of existing `DISCOUNT` CRM objects to apply. |
| `successUrl` | String | URL to redirect buyers to after a successful payment. |
| `descriptionHtml` | String | HTML content displayed on the checkout page below the line items. |
| `dealConfigurations` | Object | Options for creating a deal on purchase. See [deal configurations](#deal-configurations) below. |
| `additionalFormFields` | Array | Additional fields to collect from buyers at checkout. See [additional form fields](#additional-form-fields) below. |
| `domainId` | String | ID of a custom domain to use for the generated payment link URL. |
| `businessUnitId` | String | Business unit ID for multi-brand portals. |
```json expandable theme={null}
{
"paymentLinkName": "Test payment link",
"currencyCode": "USD",
"acceptedPaymentMethods": [
"CREDIT_OR_DEBIT_CARD"
],
"state": "ON",
"isOneTimeUseEnabled": false,
"includeEmailInSuccessRedirect": false,
"successUrl": null,
"descriptionHtml": "",
"dealConfigurations": {
"createNewDealOnPurchase": false,
"pipelineStageId": null
},
"domainId": null,
"businessUnitId": "0",
"additionalFormFields": [],
"discountCodeEnabled": false,
"storePaymentMethodAtCheckout": false,
"collectShippingAddress": false,
"collectFullBillingAddress": false,
"automatedSalesTaxEnabled": false,
"id": "419720801589",
"lineItems": [
{
"name": "My line item",
"description": null,
"pricing": {
"pricingModel": "FLAT",
"tierRanges": [],
"tierPrices": [],
"flatPrice": 150.0
},
"quantity": 1,
"richTextDescription": null,
"productId": null,
"id": "24560153926",
"discount": null,
"lineItemCurrencyCode": "USD",
"customConfiguration": null,
"tax": null,
"recurringBillingTerms": null
},
{
"name": "My other line item",
"description": null,
"pricing": {
"pricingModel": "FLAT",
"tierRanges": [],
"tierPrices": [],
"flatPrice": 100.0
},
"quantity": 1,
"richTextDescription": null,
"productId": null,
"id": "24560145794",
"discount": null,
"lineItemCurrencyCode": "USD",
"customConfiguration": null,
"tax": null,
"recurringBillingTerms": null
}
],
"formGuid": "a12b3cde-1ef2-4567-8912-490f1be4ee47",
"checkoutFeeIds": [],
"taxes": [],
"fees": [],
"discounts": [],
"paymentLinkUrl": "https://payments-na1.hubspot.com/payments/1a2b3cdEfGh4",
"createdAt": "2026-06-29T19:38:42.138Z",
"updatedAt": "2026-06-29T19:38:42.138Z",
"archivedAt": null,
"archived": false
}
```
All request fields are returned in the response along with the following additional read-only fields:
| Field | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | Unique identifier for the payment link. |
| `paymentLinkUrl` | String | The URL buyers use to access the checkout page. |
| `lineItems` | Array | Line items on the checkout page. These are stamped at the time of creation — changes made to the underlying CRM `LINE_ITEM` objects after creation are not reflected here. |
| `formGuid` | String | GUID of the payment form associated with this payment link. |
| `checkoutFeeIds` | Array | IDs of checkout fees applied to this payment link, stamped at the time of creation. |
| `taxes` | Array | Tax objects applied to this payment link. |
| `fees` | Array | Fee objects applied to this payment link. |
| `discounts` | Array | Discount objects applied to this payment link. |
| `createdAt` | String | ISO 8601 datetime when the payment link was created. |
| `updatedAt` | String | ISO 8601 datetime when the payment link was last updated. |
| `archivedAt` | String | ISO 8601 datetime when the payment link was archived. `null` if not archived. |
| `archived` | Boolean | Whether the payment link has been archived. |
### Deal configurations
To create a deal in HubSpot when a buyer completes a purchase, include a `dealConfigurations` object in the request body.
```json highlight={6-9} theme={null}
{
"paymentLinkName": "Payment link with deal configuration",
"currencyCode": "USD",
"acceptedPaymentMethods": ["CREDIT_OR_DEBIT_CARD", "ACH"],
"lineItemObjectIds": ["123456789"],
"dealConfigurations": {
"createNewDealOnPurchase": true,
"pipelineStageId": "closedwon"
}
}
```
| Field | Type | Description |
| ----------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `createNewDealOnPurchase` | Boolean | When `true`, creates a new deal each time a payment is completed through this link. |
| `pipelineStageId` | String | The ID of the pipeline stage to place the new deal in. Retrieve stage IDs using the [pipelines API](/docs/api-reference/latest/crm/pipelines/guide). |
### Additional form fields
To collect extra information from buyers at checkout, include an `additionalFormFields` array. A buyer's email is always collected by default and does not need to be specified.
```json highlight={5-13} theme={null}
{
"paymentLinkName": "Payment link with additional form fields",
"currencyCode": "USD",
"lineItemObjectIds": ["24560252587"],
"additionalFormFields": [
{
"propertyName": "city",
"label": "City",
"objectType": "CONTACT",
"isRequired": true,
"description": "The city you reside in."
}
]
}
```
| Field | Type | Description |
| ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `propertyName` | String | The internal CRM property name (e.g., `hs_phone_number`). |
| `objectType` | String | The CRM object type to store the collected value on. Allowed values: `CONTACT`, `COMPANY`. |
| `label` | String | The label shown to the buyer on the checkout page. Defaults to the property's display name. |
| `isRequired` | Boolean | When `true`, the buyer must complete this field to submit payment. Defaults to `false`. |
| `description` | String | Help text displayed below the field label. |
| `options` | Array | For dropdown fields, the selectable choices. Each option requires a `label` string and a `value` string, and accepts an optional `description`. |
### Line item create modes
Instead of referencing existing line items via `lineItemObjectIds`, you can create line items inline by including a `lineItems` array. Each object in the array must include a `mode` field that determines how the line item is created. The supported modes are:
* `CUSTOM`: creates a line item with fully custom values.
* `FROM_PRODUCT`: creates a line item based on a product in the HubSpot product library.
* `CLONE`: copies an existing `LINE_ITEM` CRM object, optionally overriding specific fields.
#### CUSTOM
Use `CUSTOM` to define a line item from scratch without referencing an existing product or line item.
```json theme={null}
{
"lineItems": [
{
"mode": "CUSTOM",
"name": "Consulting services",
"quantity": 2,
"pricing": {
"pricingModel": "FLAT",
"prices": [
{ "currencyCode": "USD", "price": 500.00 }
]
}
}
]
}
```
| Field | Type | Description |
| -------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | String | Must be `CUSTOM`. |
| `name` | String | The display name of the line item. |
| `quantity` | Number | The quantity of the line item. |
| `pricing` | Object | Pricing details. Must include `pricingModel` (allowed values: `FLAT`, `GRADUATED`, `STAIRSTEP`, `VOLUME`) and `prices` (an array of objects with `currencyCode` and `price`). |
#### FROM\_PRODUCT
Use `FROM_PRODUCT` to create a line item based on a product in the HubSpot product library. The line item inherits the product's name, price, and other properties, which can be overridden by including additional fields.
```json theme={null}
{
"lineItems": [
{
"mode": "FROM_PRODUCT",
"productId": "12345678"
}
]
}
```
| Field | Type | Description |
| --------------------------------- | ------ | ----------------------------------------------------- |
| `mode` | String | Must be `FROM_PRODUCT`. |
| `productId` | String | The ID of the product in the HubSpot product library. |
#### CLONE
Use `CLONE` to copy an existing `LINE_ITEM` CRM object. Any additional fields included alongside `sourceLineItemId` will override the corresponding values from the source line item.
```json theme={null}
{
"lineItems": [
{
"mode": "CLONE",
"sourceLineItemId": "24560145794"
}
]
}
```
| Field | Type | Description |
| ---------------------------------------- | ------ | ---------------------------------------------- |
| `mode` | String | Must be `CLONE`. |
| `sourceLineItemId` | String | The ID of the `LINE_ITEM` CRM object to clone. |
## Retrieve payment links
There are two ways to retrieve payment links via the API:
* To retrieve all payment links, make a `GET` request to `/commerce/payment-links/2026-09-beta/payment-links`
* To retrieve a single payment link, make a `GET` request to `/commerce/payment-links/2026-09-beta/payment-links/{paymentLinkId}`.
For example, if you retrieve an individual payment link with the ID of `418872603783`, your response would resemble the following:
```json theme={null}
{
"id": "418872603783",
"paymentLinkName": "Annual subscription",
"currencyCode": "USD",
"acceptedPaymentMethods": [
"CREDIT_OR_DEBIT_CARD"
],
"state": "ON",
"isOneTimeUseEnabled": false,
"storePaymentMethodAtCheckout": false,
"collectShippingAddress": false,
"collectFullBillingAddress": false,
"discountCodeEnabled": false,
"automatedSalesTaxEnabled": false,
"includeEmailInSuccessRedirect": false,
"successUrl": null,
"descriptionHtml": null,
"dealConfigurations": {
"createNewDealOnPurchase": true,
"pipelineStageId": null
},
"domainId": null,
"businessUnitId": "0",
"additionalFormFields": [],
"lineItems": [
{
"id": "1243557166",
"name": "Annual platform license",
"description": null,
"pricing": {
"pricingModel": "FLAT",
"tierRanges": [],
"tierPrices": [],
"flatPrice": 1200
},
"quantity": 1,
"richTextDescription": null,
"productId": null,
"discount": null,
"lineItemCurrencyCode": "USD",
"customConfiguration": null,
"tax": null,
"recurringBillingTerms": null
}
],
"formGuid": "b4ce42d2-4f12-4f44-8194-780f6ac3a346",
"checkoutFeeIds": [],
"taxes": [],
"fees": [],
"discounts": [],
"paymentLinkUrl": "https://payments.hubspot.com/payments/TMWGTPhrzyzMyH",
"createdAt": "2026-09-15T14:22:18.431Z",
"updatedAt": "2026-09-15T14:22:18.431Z",
"archivedAt": null,
"archived": false
}
```
When retrieving all payment links, you can use the following query parameters to paginate through results.
| Parameter | Type | Description |
| ---------- | ------- | ----------------------------------------------------------------------------------- |
| `limit` | Integer | Maximum number of results per page. Defaults to `20`. |
| `after` | String | Pagination cursor. Use the value from `paging.next.after` in the previous response. |
| `archived` | Boolean | When `true`, returns only archived payment links. Defaults to `false`. |
```json theme={null}
{
"results": [
{
"id": "987654321",
"paymentLinkName": "Annual subscription",
"currencyCode": "USD",
"acceptedPaymentMethods": ["CREDIT_OR_DEBIT_CARD"],
"state": "ON",
"paymentLinkUrl": "https://payments.hubspot.com/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"createdAt": "2026-09-15T14:22:18.431Z",
"updatedAt": "2026-09-15T14:22:18.431Z",
"archived": false
...
}
],
"paging": {
"next": {
"after": "Mgo%3D",
"link": "?after=Mgo%3D&limit=10"
}
}
}
```
### Filtering
To filter results when retrieving all payment links, you can include the following query parameters to filter the results based on the date of creation or last update. All filter values are Unix timestamps in milliseconds.
| Parameter | Type | Description |
| --------------- | ------- | ------------------------------------------------------------- |
| `createdAt` | Integer | Filter to payment links created at this exact timestamp. |
| `createdAfter` | Integer | Filter to payment links created after this timestamp. |
| `createdBefore` | Integer | Filter to payment links created before this timestamp. |
| `updatedAt` | Integer | Filter to payment links last updated at this exact timestamp. |
| `updatedAfter` | Integer | Filter to payment links last updated after this timestamp. |
| `updatedBefore` | Integer | Filter to payment links last updated before this timestamp. |
For example, to retrieve payment links created between June 1 and July 1, 2026:
```shell wrap theme={null}
/commerce/payment-links/2026-09-beta/payment-links?createdAfter=1780272000000&createdBefore=1782864000000
```
### Sorting
By default, results are listed by create date in descending order. To sort results when retrieving all payment links, include the `sort` query parameter. This parameter accepts the following values:
* `createdAt`
* `-createdAt` (descending)
* `updatedAt`
* `-updatedAt` (descending)
For example, to retrieve payment links sorted by most recently created:
```shell wrap theme={null}
/commerce/payment-links/2026-09-beta/payment-links?sort=-createdAt
```
## Update a payment link
To update a payment link, make a `PATCH` request to `/commerce/payment-links/2026-09-beta/payment-links/{paymentLinkId}`.
All fields are optional. Include only the fields you want to change. The response includes the full updated payment link object.
To explicitly clear a nullable field, set its value to `null` in the request body. The following fields support this: `successUrl`, `descriptionHtml`, `dealConfigurations`, `domainId`, and `businessUnitId`.
| Field | Type | Description |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `paymentLinkName` | String | The name displayed on the checkout page. |
| `currencyCode` | String | Three-letter ISO 4217 currency code (e.g., `USD`). |
| `acceptedPaymentMethods` | Array | Payment methods to accept at checkout. Allowed values: `CREDIT_OR_DEBIT_CARD`, `ACH`, `SEPA`, `BACS`, `PADS`. |
| `state` | String | State of the link. Allowed values: `ON`, `OFF`. |
| `isOneTimeUseEnabled` | Boolean | When `true`, the link can only be used once. |
| `storePaymentMethodAtCheckout` | Boolean | When `true`, stores the buyer's payment method for future use. |
| `collectShippingAddress` | Boolean | When `true`, prompts the buyer for a shipping address. |
| `collectFullBillingAddress` | Boolean | When `true`, prompts the buyer for a full billing address. |
| `discountCodeEnabled` | Boolean | When `true`, allows buyers to enter discount codes at checkout. |
| `automatedSalesTaxEnabled` | Boolean | When `true`, automatically calculates and applies sales tax. |
| `includeEmailInSuccessRedirect` | Boolean | When `true`, appends the buyer's email as a query parameter on the `successUrl`. |
| `enableDefaultCheckoutFees` | Boolean | When `true`, applies the portal's default checkout fees to this payment link. |
| `lineItemObjectIds` | Array | IDs of existing `LINE_ITEM` CRM objects to include on the checkout page. |
| `taxObjectIds` | Array | IDs of existing `TAX` CRM objects to apply. |
| `feeObjectIds` | Array | IDs of existing `FEE` CRM objects to apply. |
| `discountObjectIds` | Array | IDs of existing `DISCOUNT` CRM objects to apply. |
| `successUrl` | String | URL to redirect buyers to after a successful payment. Set to `null` to clear. |
| `descriptionHtml` | String | HTML content displayed on the checkout page below the line items. Set to `null` to clear. |
| `dealConfigurations` | Object | Options for creating a deal on purchase. Set to `null` to clear. See [deal configurations](#deal-configurations). |
| `domainId` | String | ID of a custom domain to use for the generated payment link URL. Set to `null` to clear. |
| `businessUnitId` | String | Business unit ID for multi-brand portals. Set to `null` to clear. |
| `additionalFormFields` | Array | Additional fields to collect from buyers at checkout. See [additional form fields](#additional-form-fields). |
## Delete a payment link
**Please note:** archived payment links cannot be restored via the API or in HubSpot.
To delete a payment link, make a `DELETE` request to `/commerce/payment-links/2026-09-beta/payment-links/{paymentLinkId}`.
Deleting a payment link archives it permanently. Archived payment links are no longer accessible to buyers and are excluded from [retrieve](#retrieve-payment-links) responses by default. A successful request returns `204 No Content`.
You can retrieve deleted payment links by including the `archived=true` query parameter in the [GET request](#retrieve-payment-links).