> ## 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: e8cab689-cc74-424d-b9f8-7f0a48ff4735
---
# Create a payment link
> Create a new payment link in your HubSpot account. This endpoint allows you to specify various attributes for the payment link, such as accepted payment methods, currency, and additional form fields. The payment link can be configured for one-time use and can also collect shipping and billing addresses. This operation requires a valid JSON request body. Some defaults will be applied if no value provided.
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
;
};
## OpenAPI
````yaml specs/2026-09-beta/commerce-payment-links-v2026-09-beta.json POST /commerce/payment-links/2026-09-beta/payment-links
openapi: 3.0.1
info:
title: Commerce Payment Links
description: Basepom for all HubSpot Projects
version: 2026-09-beta
x-hubspot-product-tier-requirements:
marketing: FREE
sales: FREE
service: FREE
cms: FREE
commerce: FREE
crmHub: FREE
dataHub: FREE
servers:
- url: https://api.hubapi.com
security: []
tags:
- name: Basic
paths:
/commerce/payment-links/2026-09-beta/payment-links:
post:
tags:
- Basic
summary: Create a payment link
description: >-
Create a new payment link in your HubSpot account. This endpoint allows
you to specify various attributes for the payment link, such as accepted
payment methods, currency, and additional form fields. The payment link
can be configured for one-time use and can also collect shipping and
billing addresses. This operation requires a valid JSON request body.
Some defaults will be applied if no value provided.
operationId: post-/commerce/payment-links/2026-09-beta/payment-links
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPaymentLinkCreateRequest'
required: true
responses:
'201':
description: successful operation
headers:
Location:
description: URL of the newly created resource
style: simple
explode: false
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPaymentLinkResponse'
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- payment-links-write
components:
schemas:
PublicPaymentLinkCreateRequest:
required:
- acceptedPaymentMethods
- additionalFormFields
- automatedSalesTaxEnabled
- collectFullBillingAddress
- collectShippingAddress
- currencyCode
- discountCodeEnabled
- discountObjectIds
- enableDefaultCheckoutFees
- feeObjectIds
- includeEmailInSuccessRedirect
- isOneTimeUseEnabled
- lineItemObjectIds
- paymentLinkName
- state
- storePaymentMethodAtCheckout
- taxObjectIds
type: object
properties:
acceptedPaymentMethods:
type: array
description: >-
An array of strings representing the payment methods accepted for
this link. Valid values include 'CARD', 'ACH', 'SEPA', 'BACS', and
'PADS'.
items:
type: string
enum:
- CARD
- ACH
- SEPA
- BACS
- PADS
additionalFormFields:
type: array
description: >-
An array of PublicPaymentLinkFormField objects representing
additional form fields to be included in the payment link. Email is
included by default and should not be specified here.
items:
$ref: '#/components/schemas/PublicPaymentLinkFormField'
automatedSalesTaxEnabled:
type: boolean
description: >-
A boolean indicating whether automated sales tax calculation is
enabled.
businessUnitId:
type: string
description: >-
A string representing the business unit ID associated with the
payment link.
collectFullBillingAddress:
type: boolean
description: >-
A boolean indicating whether the full billing address should be
collected during checkout.
collectShippingAddress:
type: boolean
description: >-
A boolean indicating whether the shipping address should be
collected during checkout.
currencyCode:
type: string
description: The currency code for the payment, represented as a string.
dealConfigurations:
$ref: '#/components/schemas/PublicDealConfigurations'
descriptionHtml:
type: string
description: A string containing the HTML description of the payment link.
discount:
$ref: '#/components/schemas/DiscountRequest'
discountCodeEnabled:
type: boolean
description: >-
A boolean indicating whether discount codes are enabled for this
payment link.
discountObjectIds:
type: array
description: >-
An array of strings representing the object IDs of discounts
associated with the payment link.
items:
type: string
domainId:
type: string
description: >-
A string representing the domain ID associated with the payment
link.
enableDefaultCheckoutFees:
type: boolean
description: A boolean indicating whether default checkout fees are enabled.
feeObjectIds:
type: array
description: >-
An array of strings representing the object IDs of fees associated
with the payment link.
items:
type: string
includeEmailInSuccessRedirect:
type: boolean
description: >-
A boolean indicating whether to include the email in the success
redirect URL.
isOneTimeUseEnabled:
type: boolean
description: >-
A boolean indicating whether the payment link is for one-time use
only.
lineItemObjectIds:
type: array
description: >-
An array of strings representing the object IDs of line items
associated with the payment link.
items:
type: string
paymentLinkName:
type: string
description: The name of the payment link, represented as a string.
state:
type: string
description: >-
The state of the payment link, represented as a string. Valid values
are 'ON' and 'OFF'.
enum:
- 'OFF'
- 'ON'
storePaymentMethodAtCheckout:
type: boolean
description: >-
A boolean indicating whether the payment method should be stored at
checkout.
successUrl:
type: string
description: >-
A string representing the URL to redirect to upon successful
payment.
taxObjectIds:
type: array
description: >-
An array of strings representing the object IDs of taxes associated
with the payment link.
items:
type: string
PublicPaymentLinkResponse:
required:
- acceptedPaymentMethods
- additionalFormFields
- archived
- automatedSalesTaxEnabled
- checkoutFeeIds
- collectFullBillingAddress
- collectShippingAddress
- createdAt
- currencyCode
- discountCodeEnabled
- discounts
- fees
- formGuid
- id
- includeEmailInSuccessRedirect
- isOneTimeUseEnabled
- lineItems
- paymentLinkName
- paymentLinkUrl
- state
- storePaymentMethodAtCheckout
- taxes
- updatedAt
type: object
properties:
acceptedPaymentMethods:
type: array
description: >-
An array of accepted payment methods for the link, which can include
'CARD', 'ACH', 'SEPA', 'BACS', and 'PADS'.
items:
type: string
enum:
- CARD
- ACH
- SEPA
- BACS
- PADS
additionalFormFields:
type: array
description: An array of additional form fields included in the payment link.
items:
$ref: '#/components/schemas/PublicPaymentLinkFormField'
archived:
type: boolean
description: A boolean indicating if the payment link is archived.
archivedAt:
type: string
description: >-
A string representing the date and time when the payment link was
archived, in ISO 8601 format.
format: date-time
automatedSalesTaxEnabled:
type: boolean
description: A boolean indicating if automated sales tax calculation is enabled.
businessUnitId:
type: string
description: >-
A string representing the business unit ID associated with the
payment link.
checkoutFeeIds:
type: array
description: >-
An array of strings representing the IDs of checkout fees associated
with the payment link.
items:
type: string
collectFullBillingAddress:
type: boolean
description: >-
A boolean indicating if the full billing address should be collected
during checkout.
collectShippingAddress:
type: boolean
description: >-
A boolean indicating if the shipping address should be collected
during checkout.
createdAt:
type: string
description: >-
A string representing the date and time when the payment link was
created, in ISO 8601 format.
format: date-time
currencyCode:
type: string
description: The currency code for the payment link, represented as a string.
dealConfigurations:
$ref: '#/components/schemas/PublicDealConfigurations'
descriptionHtml:
type: string
description: A string containing the HTML description of the payment link.
discountCodeEnabled:
type: boolean
description: >-
A boolean indicating if discount codes are enabled for the payment
link.
discounts:
type: array
description: An array of discount objects associated with the payment link.
items:
$ref: '#/components/schemas/DiscountResponse'
domainId:
type: string
description: >-
A string representing the domain ID associated with the payment
link.
fees:
type: array
description: An array of fee objects associated with the payment link.
items:
$ref: '#/components/schemas/FeeResponse'
formGuid:
type: string
description: >-
A string representing the form GUID associated with the payment
link.
id:
type: string
description: A string representing the unique identifier of the payment link.
includeEmailInSuccessRedirect:
type: boolean
description: >-
A boolean indicating if the email should be included in the success
redirect.
isOneTimeUseEnabled:
type: boolean
description: >-
A boolean indicating if the payment link is enabled for one-time use
only.
lineItems:
type: array
description: An array of line items associated with the payment link.
items:
$ref: '#/components/schemas/LineItem'
paymentLinkName:
type: string
description: The name of the payment link, represented as a string.
paymentLinkUrl:
type: string
description: A string representing the URL of the payment link.
state:
type: string
description: >-
The current state of the payment link, which can be either 'ON' or
'OFF'.
enum:
- 'OFF'
- 'ON'
storePaymentMethodAtCheckout:
type: boolean
description: >-
A boolean indicating if the payment method should be stored at
checkout.
successUrl:
type: string
description: >-
A string representing the URL to redirect to upon successful
payment.
taxes:
type: array
description: An array of tax objects associated with the payment link.
items:
$ref: '#/components/schemas/TaxResponse'
updatedAt:
type: string
description: >-
A string representing the date and time when the payment link was
last updated, in ISO 8601 format.
format: date-time
PublicPaymentLinkFormField:
required:
- isRequired
- label
- objectType
- options
- propertyName
type: object
properties:
description:
type: string
description: >-
A description of the form field, providing additional context or
instructions, represented as a string.
isRequired:
type: boolean
description: >-
A boolean indicating whether this form field is required to be
filled out by the user.
label:
type: string
description: >-
The label for the form field, displayed to users, represented as a
string.
objectType:
type: string
description: >-
The type of object this form field is associated with, represented
as a string. Valid values include 'CONTACT' and 'COMPANY'.
enum:
- COMPANY
- CONTACT
options:
type: array
description: >-
An array of options available for this form field, applicable if the
field type supports multiple choices. Each option is defined by the
PublicFormFieldOption schema.
items:
$ref: '#/components/schemas/PublicFormFieldOption'
propertyName:
type: string
description: >-
The name of the property associated with this form field,
represented as a string.
PublicDealConfigurations:
required:
- createNewDealOnPurchase
type: object
properties:
createNewDealOnPurchase:
type: boolean
description: >-
A boolean indicating whether a new deal should be created when a
purchase is made.
pipelineStageId:
type: string
description: >-
A string representing the identifier of the pipeline stage where the
deal will be placed.
DiscountRequest:
required:
- label
- value
- valueType
type: object
properties:
label:
type: string
value:
type: number
valueType:
type: string
enum:
- FIXED
- PERCENT
DiscountResponse:
required:
- id
type: object
properties:
archived:
type: boolean
archivedAt:
type: string
createdAt:
type: string
id:
type: string
label:
type: string
updatedAt:
type: string
value:
type: number
valueType:
type: string
enum:
- FIXED
- PERCENT
FeeResponse:
required:
- id
type: object
properties:
archived:
type: boolean
archivedAt:
type: string
createdAt:
type: string
id:
type: string
label:
type: string
updatedAt:
type: string
value:
type: number
valueType:
type: string
enum:
- FIXED
- PERCENT
LineItem:
required:
- id
- name
- pricing
- quantity
type: object
properties:
acv:
type: number
allowBuyerSelectedQuantity:
type: boolean
amount:
type: number
archived:
type: boolean
archivedAt:
type: string
arr:
type: number
billingCycleAnchorDate:
type: string
billingPeriodEndDate:
type: string
billingPeriodStartDate:
type: string
billingStartDelayDays:
type: integer
format: int32
billingStartDelayMonths:
type: integer
format: int32
billingStartDelayType:
type: string
enum:
- hs_billing_start_delay_days
- hs_billing_start_delay_months
- hs_recurring_billing_start_date
buyerSelectedQuantityMax:
type: number
buyerSelectedQuantityMin:
type: number
createdAt:
type: string
description:
type: string
discount:
type: number
discountPercentage:
type: number
effectiveUnitPrice:
type: number
externalId:
type: string
id:
type: string
images:
type: string
isEditablePrice:
type: boolean
isOptional:
type: boolean
lineItemCurrencyCode:
type: string
mrr:
type: number
name:
type: string
positionOnQuote:
type: integer
format: int32
postTaxAmount:
type: number
preDiscountAmount:
type: number
price:
type: number
priceBookId:
type: string
pricing:
$ref: '#/components/schemas/Pricing'
pricingModel:
type: string
enum:
- flat
- graduated
- stairstep
- volume
productId:
type: string
productType:
type: string
quantity:
type: number
rampKey:
type: string
recurringBillingDayOfMonth:
type: integer
format: int32
recurringBillingEndDate:
type: string
recurringBillingFrequency:
type: string
enum:
- annually
- biweekly
- monthly
- per_five_years
- per_four_years
- per_six_months
- per_three_years
- per_two_years
- quarterly
- weekly
recurringBillingNumberOfPayments:
type: integer
format: int32
recurringBillingPeriod:
type: string
recurringBillingStartDate:
type: string
recurringBillingTerms:
type: string
enum:
- AUTOMATICALLY_RENEW
- FIXED
richTextDescription:
type: string
sku:
type: string
tax:
type: number
tcv:
type: number
termInMonths:
type: integer
format: int32
tierAmount:
type: number
totalDiscount:
type: number
updatedAt:
type: string
variantId:
type: string
TaxResponse:
required:
- id
type: object
properties:
archived:
type: boolean
archivedAt:
type: string
createdAt:
type: string
id:
type: string
label:
type: string
updatedAt:
type: string
value:
type: number
valueType:
type: string
enum:
- FIXED
- PERCENT
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, represented as an object with
additional properties.
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request. Include this value with any
error reports or support tickets.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
Further information about the error, represented as an array of
ErrorDetail objects.
items:
$ref: '#/components/schemas/ErrorDetail'
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs containing documentation
about the error or recommended remediation steps.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate.
example: An error occurred
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error.
example:
message: Invalid input (details will vary based on the error)
correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
category: VALIDATION_ERROR
links:
knowledge-base: https://www.hubspot.com/products/service/knowledge-base
PublicFormFieldOption:
required:
- label
- value
type: object
properties:
description:
type: string
description: >-
A string providing additional information about the form field
option. This is optional and can be used to give more context about
the option.
label:
type: string
description: >-
The display text for the form field option. It is a string that
users will see when selecting an option.
value:
type: string
description: >-
The internal value associated with the form field option. It is a
string used to identify the option programmatically.
Pricing:
required:
- prices
- pricingModel
type: object
properties:
prices:
type: array
items:
$ref: '#/components/schemas/PriceEntry'
pricingModel:
type: string
enum:
- FLAT
- GRADUATED
- STAIRSTEP
- VOLUME
ErrorDetail:
required:
- message
type: object
properties:
code:
type: string
description: The status code associated with the error detail.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, represented as an object with
additional properties that provide more details.
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: The name of the field or parameter in which the error was found.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate.
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error.
PriceEntry:
required:
- amount
- currencyCode
- price
type: object
properties:
amount:
type: number
currencyCode:
type: string
maxQuantity:
type: string
price:
type: number
responses:
Error:
description: An error occurred.
content:
'*/*':
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.hubspot.com/oauth/authorize
tokenUrl: https://api.hubapi.com/oauth/v1/token
scopes:
payment-links-delete: ''
payment-links-read: ''
payment-links-write: ''
````
{product.name} -
{product.level}
)}