Payment links API - HubSpot docs

Scope requirements

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:

Example request
Example response

{
  "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 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 below.
`additionalFormFields`	Array	Additional fields to collect from buyers at checkout. See 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.

{
  "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.

{
  "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.

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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:

{
  "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`.

{
  "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:

/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:

/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.
`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.

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 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.

​Create a payment link

​Deal configurations

​Additional form fields

​Line item create modes

​CUSTOM

​FROM_PRODUCT

​CLONE

​Retrieve payment links

​Filtering

​Sorting

​Update a payment link

​Delete a payment link

Create a payment link

Deal configurations

Additional form fields

Line item create modes

CUSTOM

FROM_PRODUCT

CLONE

Retrieve payment links

Filtering

Sorting

Update a payment link

Delete a payment link