HubSpot Commerce Payment Links API

openapi: 3.0.1
info:
  title: HubSpot Commerce Payment Links
  description: Basepom for all HubSpot Projects
  version: 2026-09
  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
tags:
- name: Basic
paths:
  /commerce/payment-links/2026-09/payment-links:
    get:
      tags:
      - Basic
      summary: Retrieve all payment links
      description: Retrieve a list of payment links from your HubSpot account. This endpoint allows you
        to filter and sort payment links based on various criteria such as creation and update timestamps.
        It supports pagination and can include archived payment links if specified.
      operationId: get-/commerce/payment-links/2026-09/payment-links
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 20
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponsePaymentLinkResponseForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - payment-links-read
    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/payment-links
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLinkCreateRequest'
        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/PaymentLinkResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - payment-links-write
  /commerce/payment-links/2026-09/payment-links/{paymentLinkId}:
    get:
      tags:
      - Basic
      summary: Retrieve payment link
      description: Retrieve details of a specific payment link using its unique identifier. This endpoint
        allows you to access information about the payment link, including its status and configuration.
        It is useful for checking the current settings or status of a payment link in your HubSpot account.
      operationId: get-/commerce/payment-links/2026-09/payment-links/{paymentLinkId}
      parameters:
      - name: paymentLinkId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLinkResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - payment-links-read
    delete:
      tags:
      - Basic
      summary: Delete a payment link
      description: Delete a specific payment link in your HubSpot account. This operation is irreversible
        and will remove the payment link identified by the provided ID. Use this endpoint to manage and
        clean up payment links that are no longer needed.
      operationId: delete-/commerce/payment-links/2026-09/payment-links/{paymentLinkId}
      parameters:
      - name: paymentLinkId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - payment-links-delete
    patch:
      tags:
      - Basic
      summary: Update a payment link
      description: Update a payment link by ID.
      operationId: patch-/commerce/payment-links/2026-09/payment-links/{paymentLinkId}_/commerce/payment-links/2026-09-beta/payment-links/{paymentLinkId}
      parameters:
      - name: paymentLinkId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLinkUpdateRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLinkResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - payment-links-write
components:
  schemas:
    CollectionResponsePaymentLinkResponseForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          description: An array of PaymentLinkResponse objects, each representing a payment link with
            its associated details.
          items:
            $ref: '#/components/schemas/PaymentLinkResponse'
    DealConfigurations:
      required:
      - createNewDealOnPurchase
      type: object
      properties:
        createNewDealOnPurchase:
          type: boolean
          description: A boolean indicating whether a new deal should be created in HubSpot upon a purchase.
            Required field.
        pipelineStageId:
          type: string
          description: The identifier for the pipeline stage where the new deal will be placed. This is
            a string value.
    DiscountRequest:
      required:
      - label
      - value
      - valueType
      type: object
      properties:
        label:
          type: string
          description: A descriptive label for the discount. This is a string.
        value:
          type: number
          description: The numerical value of the discount to be applied. This is a number.
        valueType:
          type: string
          description: The type of discount value, which can either be 'FIXED' or 'PERCENT'.
          enum:
          - FIXED
          - PERCENT
    DiscountResponse:
      required:
      - id
      type: object
      properties:
        archived:
          type: boolean
          description: Indicates whether this discount has been archived. A boolean value.
        archivedAt:
          type: string
          description: The date and time when this discount was archived, in ISO 8601 format.
          format: date-time
        createdAt:
          type: string
          description: The date and time when this discount was created, in ISO 8601 format.
          format: date-time
        id:
          type: string
          description: The unique identifier for this discount.
        label:
          type: string
          description: A descriptive label for the discount.
        updatedAt:
          type: string
          description: The date and time when this discount was last updated, in ISO 8601 format.
          format: date-time
        value:
          type: number
          description: The numerical value of the discount.
        valueType:
          type: string
          description: The type of discount value, which can be either 'FIXED' or 'PERCENT'.
          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
          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
          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
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      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
    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
          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
      description: Represents detailed information about an error that occurred in the API. This component
        is used to provide additional context and specifics about errors, typically as part of an error
        response.
    ExpirationSettings:
      type: object
      properties:
        expirationDate:
          type: string
          format: date-time
        maxPurchases:
          type: integer
          format: int32
    FeeRequest:
      required:
      - label
      - value
      - valueType
      type: object
      properties:
        label:
          type: string
          description: A descriptive label for the fee, represented as a string.
        value:
          type: number
          description: The numerical value of the fee. This is a number representing either a fixed amount
            or a percentage, depending on the valueType.
        valueType:
          type: string
          description: The type of the fee value, indicating whether it is a fixed amount or a percentage.
            Valid values include 'FIXED' and 'PERCENT'.
          enum:
          - FIXED
          - PERCENT
    FeeResponse:
      required:
      - id
      type: object
      properties:
        archived:
          type: boolean
          description: Indicates whether this fee has been archived. A boolean value.
        archivedAt:
          type: string
          description: The date and time when this fee was archived, in ISO 8601 format.
          format: date-time
        createdAt:
          type: string
          description: The date and time when this fee was created, in ISO 8601 format.
          format: date-time
        id:
          type: string
          description: The unique identifier for this fee.
        label:
          type: string
          description: A descriptive label for the fee.
        updatedAt:
          type: string
          description: The date and time when this fee was last updated, in ISO 8601 format.
          format: date-time
        value:
          type: number
          description: The monetary value of the fee. A number representing the fee amount.
        valueType:
          type: string
          description: The type of value for the fee, which can be either 'FIXED' or 'PERCENT'.
          enum:
          - FIXED
          - PERCENT
    FormFieldOption:
      required:
      - label
      - value
      type: object
      properties:
        description:
          type: string
          description: A string providing additional information or context about the form field option.
        label:
          type: string
          description: A string representing the display name of the form field option.
        value:
          type: string
          description: A string representing the underlying value associated with the form field option.
    ForwardPaging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
      description: Paging information for forward-only pagination. Contains the next page reference when
        more results are available; omitted or empty on the last page.
    LineItem:
      required:
      - id
      - name
      - pricing
      - quantity
      type: object
      properties:
        acv:
          type: number
          description: The annual contract value for the line item.
        allowBuyerSelectedQuantity:
          type: boolean
          description: Indicates whether the buyer can select the quantity of the line item.
        amount:
          type: number
          description: The total amount for the line item, calculated as price multiplied by quantity.
        archived:
          type: boolean
          description: Indicates whether the line item is archived.
        archivedAt:
          type: string
          description: The date and time when the line item was archived, in ISO 8601 format.
          format: date-time
        arr:
          type: number
          description: The annual recurring revenue for the line item.
        billingCycleAnchorDate:
          type: string
          description: The anchor date for the billing cycle, in ISO 8601 date format.
          format: date
        billingPeriodEndDate:
          type: string
          description: The end date of the billing period, in ISO 8601 date format.
          format: date
        billingPeriodStartDate:
          type: string
          description: The start date of the billing period, in ISO 8601 date format.
          format: date
        billingStartDelayDays:
          type: integer
          description: The number of days to delay the start of billing.
          format: int32
        billingStartDelayMonths:
          type: integer
          description: The number of months to delay the start of billing.
          format: int32
        billingStartDelayType:
          type: string
          description: The type of delay for the start of billing. Valid values include 'HS_BILLING_START_DELAY_DAYS',
            'HS_BILLING_START_DELAY_MONTHS', and 'HS_RECURRING_BILLING_START_DATE'.
          enum:
          - HS_BILLING_START_DELAY_DAYS
          - HS_BILLING_START_DELAY_MONTHS
          - HS_RECURRING_BILLING_START_DATE
        buyerSelectedQuantityMax:
          type: number
          description: The maximum quantity the buyer can select for the line item.
        buyerSelectedQuantityMin:
          type: number
          description: The minimum quantity the buyer can select for the line item.
        createdAt:
          type: string
          description: The date and time when the line item was created, in ISO 8601 format.
          format: date-time
        description:
          type: string
          description: A text description of the line item.
        discount:
          type: number
          description: The discount applied to the line item.
        discountPercentage:
          type: number
          description: The percentage discount applied to the line item.
        effectiveUnitPrice:
          type: number
          description: The effective price per unit after discounts.
        externalId:
          type: string
          description: An external identifier for the line item, used for integration purposes.
        id:
          type: string
          description: The unique identifier for the line item.
        images:
          type: string
          description: A URL or identifier for images associated with the line item.
        isEditablePrice:
          type: boolean
          description: Indicates whether the price of the line item is editable.
        isOptional:
          type: boolean
          description: Indicates whether the line item is optional.
        isParent:
          type: boolean
        lineItemCurrencyCode:
          type: string
          description: The currency code for the line item, following ISO 4217 format.
        mrr:
          type: number
          description: The monthly recurring revenue for the line item.
        name:
          type: string
          description: The name of the line item.
        parentLineItemId:
          type: string
        positionOnQuote:
          type: integer
          description: The position of the line item on a quote, represented as an integer.
          format: int32
        postTaxAmount:
          type: number
          description: The amount after taxes are applied.
        preDiscountAmount:
          type: number
          description: The amount before any discounts are applied.
        price:
          type: number
          description: The price of a single unit of the line item.
        priceBookId:
          type: string
          description: The identifier for the price book associated with the line item.
        pricing:
          $ref: '#/components/schemas/Pricing'
        pricingModel:
          type: string
          description: The pricing model used for the line item. Valid values include 'FLAT', 'GRADUATED',
            'STAIRSTEP', and 'VOLUME'.
          enum:
          - FLAT
          - GRADUATED
          - STAIRSTEP
          - VOLUME
        productId:
          type: string
          description: The identifier for the product associated with the line item.
        productType:
          type: string
          description: The type of product for the line item.
        quantity:
          type: number
          description: The quantity of the line item, represented as a number.
        rampKey:
          type: string
          description: A key used to identify the ramp schedule for the line item.
        recurringBillingDayOfMonth:
          type: integer
          description: The day of the month when recurring billing occurs.
          format: int32
        recurringBillingEndDate:
          type: string
          description: The end date for recurring billing, in ISO 8601 date format.
          format: date
        recurringBillingFrequency:
          type: string
          description: The frequency of recurring billing for the line item. Valid values include 'ANNUALLY',
            'BIWEEKLY', 'MONTHLY', 'PER_FIVE_YEARS', 'PER_FOUR_YEARS', 'PER_SIX_MONTHS', 'PER_THREE_YEARS',
            'PER_TWO_YEARS', 'QUARTERLY', and 'WEEKLY'.
          enum:
          - ANNUALLY
          - BIWEEKLY
          - MONTHLY
          - PER_FIVE_YEARS
          - PER_FOUR_YEARS
          - PER_SIX_MONTHS
          - PER_THREE_YEARS
          - PER_TWO_YEARS
          - QUARTERLY
          - WEEKLY
        recurringBillingNumberOfPayments:
          type: integer
          description: The number of payments for the recurring billing cycle.
          format: int32
        recurringBillingPeriod:
          type: string
          description: The period for recurring billing.
        recurringBillingStartDate:
          type: string
          description: The start date for recurring billing, in ISO 8601 date format.
          format: date
        recurringBillingTerms:
          type: string
          description: The terms of recurring billing. Valid values include 'AUTOMATICALLY_RENEW' and
            'FIXED'.
          enum:
          - AUTOMATICALLY_RENEW
          - FIXED
        richTextDescription:
          type: string
          description: A rich text formatted description of the line item.
        sku:
          type: string
          description: The stock keeping unit (SKU) identifier for the line item.
        tax:
          type: number
          description: The tax amount applied to the line item.
        taxAmount:
          type: number
        taxCategory:
          type: string
        taxRateGroupId:
          type: string
        tcv:
          type: number
          description: The total contract value for the line item.
        termInMonths:
          type: integer
          description: The term length for the line item in months.
          format: int32
        tierAmount:
          type: number
          description: The tiered amount applicable to the line item.
        totalDiscount:
          type: number
          description: The total discount amount applied to the line item.
        updatedAt:
          type: string
          description: The date and time when the line item was last updated, in ISO 8601 format.
          format: date-time
        variantId:
          type: string
          description: The identifier for the product variant associated with the line item.
    LineItemCloneCreateRequest:
      title: CLONE
      required:
      - allowBuyerSelectedQuantity
      - billingCycleAnchorDate
      - billingStartDelayDays
      - billingStartDelayMonths
      - buyerSelectedQuantityMax
      - buyerSelectedQuantityMin
      - description
      - discount
      - discountPercentage
      - externalId
      - images
      - isEditablePrice
      - isOptional
      - lineItemCurrencyCode
      - mode
      - name
      - positionOnQuote
      - priceBookId
      - pricing
      - productType
      - quantity
      - recurringBillingEndDate
      - recurringBillingFrequency
      - recurringBillingPeriod
      - recurringBillingStartDate
      - richTextDescription
      - sku
      - sourceLineItemId
      - taxCategory
      - taxRateGroupId
      - variantId
      type: object
      properties:
        allowBuyerSelectedQuantity:
          type: object
          properties: {}
          description: An object indicating whether the buyer can select the quantity of the line item.
        billingCycleAnchorDate:
          type: object
          properties: {}
          description: An object representing the anchor date for the billing cycle of the line item.
        billingStartDelayDays:
          type: object
          properties: {}
          description: An object representing the number of days to delay the start of billing for the
            line item.
        billingStartDelayMonths:
          type: object
          properties: {}
          description: An object representing the number of months to delay the start of billing for the
            line item.
        buyerSelectedQuantityMax:
          type: object
          properties: {}
          description: An object representing the maximum quantity the buyer can select for the line item.
        buyerSelectedQuantityMin:
          type: object
          properties: {}
          description: An object representing the minimum quantity the buyer can select for the line item.
        description:
          type: object
          properties: {}
          description: An object representing the description of the line item.
        discount:
          type: object
          properties: {}
          description: An object representing the discount applied to the line item.
        discountPercentage:
          type: object
          properties: {}
          description: An object representing the discount percentage applied to the line item.
        externalId:
          type: object
          properties: {}
          description: An object representing an external identifier for the line item.
        images:
          type: object
          properties: {}
          description: An object representing the images associated with the line item.
        isEditablePrice:
          type: object
          properties: {}
          description: An object indicating whether the price of the line item is editable.
        isOptional:
          type: object
          properties: {}
          description: An object indicating whether the line item is optional.
        lineItemCurrencyCode:
          type: object
          properties: {}
          description: An object representing the currency code for the line item.
        mode:
          type: string
          description: A string indicating the mode of the line item creation, which is 'CLONE' for this
            component.
          default: CLONE
          enum:
          - CLONE
        name:
          type: object
          properties: {}
          description: An object representing the name of the line item.
        positionOnQuote:
          type: object
          properties: {}
          description: An object representing the position of the line item on the quote.
        priceBookId:
          type: object
          properties: {}
          description: An object representing the price book ID associated with the line item.
        pricing:
          type: object
          properties: {}
          description: An object representing the pricing details of the line item.
        productType:
          type: object
          properties: {}
          description: An object representing the type of product for the line item.
        quantity:
          type: object
          properties: {}
          description: An object representing the quantity of the line item.
        recurringBillingEndDate:
          type: object
          properties: {}
          description: An object representing the end date for recurring billing of the line item.
        recurringBillingFrequency:
          type: object
          properties: {}
          description: An object representing the frequency of recurring billing for the line item.
        recurringBillingPeriod:
          type: object
          properties: {}
          description: An object representing the billing period for recurring billing of the line item.
        recurringBillingStartDate:
          type: object
          properties: {}
          description: An object representing the start date for recurring billing of the line item.
        richTextDescription:
          type: object
          properties: {}
          description: An object representing the rich text description of the line item.
        sku:
          type: object
          properties: {}
          description: An object representing the stock keeping unit (SKU) of the line item.
        sourceLineItemId:
          type: string
          description: A string representing the ID of the source line item being cloned.
        taxCategory:
          type: object
          properties: {}
        taxRateGroupId:
          type: object
          properties: {}
        variantId:
          type: object
          properties: {}
          description: An object representing the variant ID of the line item.
      x-hubspot-sub-type-impl: true
    LineItemCustomCreateRequest:
      title: CUSTOM
      required:
      - mode
      - name
      - pricing
      - quantity
      type: object
      properties:
        allowBuyerSelectedQuantity:
          type: boolean
          description: A boolean specifying if the buyer can select the quantity of the line item.
        billingCycleAnchorDate:
          type: string
          description: A string in date format representing the anchor date for the billing cycle.
          format: date
        billingStartDelayDays:
          type: integer
          description: An integer indicating the number of days to delay the start of billing.
          format: int32
        billingStartDelayMonths:
          type: integer
          description: An integer indicating the number of months to delay the start of billing.
          format: int32
        buyerSelectedQuantityMax:
          type: number
          description: A number indicating the maximum quantity the buyer can select.
        buyerSelectedQuantityMin:
          type: number
          description: A number indicating the minimum quantity the buyer can select.
        description:
          type: string
          description: A string providing a description of the line item.
        discount:
          type: number
          description: A number representing the discount applied to the line item.
        discountPercentage:
          type: number
          description: A number indicating the discount percentage applied to the line item.
        externalId:
          type: string
          description: A string representing an external identifier for the line item.
        images:
          type: string
          description: A string containing URLs or i

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-commerce-payment-links-api-openapi.yml