HubSpot Commerce Payments API

openapi: 3.1.0
info:
  title: HubSpot Commerce Payments API
  description: |
    The HubSpot Commerce Payments API enables developers to manage commerce payment objects within 
    the HubSpot CRM. This API provides comprehensive functionality for creating, reading, updating, 
    archiving, and searching commerce payment records. It supports both individual and batch operations, 
    allowing for efficient management of payment data at scale.

    Key features include:
    - CRUD operations for individual commerce payments
    - Batch operations for processing multiple payments simultaneously
    - Advanced search capabilities with filtering and sorting
    - Property history tracking for audit purposes
    - Association management with other CRM objects
  version: 3.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
- url: https://api.hubapi.com
  description: HubSpot Production API

tags:
- name: Batch Operations
  description: Operations for processing multiple commerce payments in a single request
- name: Payment Search
  description: Advanced search operations for finding and filtering commerce payments

- name: Single Payment Operations
  description: CRUD operations for individual commerce payment records
paths:
  /crm/v3/objects/commerce_payments/batch/read:
    post:
      tags:
      - Batch Operations
      summary: Hubspot Read a Batch of Commerce Payments
      description: |
        Retrieves multiple commerce payment records by their internal IDs or unique property values 
        in a single request. This operation is optimized for bulk data retrieval and supports 
        fetching property history.
      operationId: batchReadCommercePayments
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "BatchReadCommercePaymentsSuccessExample"
      security:
      - oauth2Auth: []
      parameters:
      - $ref: '#/components/parameters/ArchivedQuery'
        example: example-value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReadRequest'
            examples:
              BatchReadCommercePaymentsRequestExample:
                $ref: '#/components/examples/BatchReadCommercePaymentsRequestExample'
      responses:
        '200':
          description: Successfully retrieved commerce payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchReadResponse'
              examples:
                BatchReadCommercePaymentsSuccessExample:
                  $ref: '#/components/examples/BatchReadCommercePaymentsSuccessExample'
        '207':
          description: Multi-status response - some payments retrieved successfully, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchReadResponse'
              examples:
                BatchReadCommercePaymentsPartialExample:
                  $ref: '#/components/examples/BatchReadCommercePaymentsPartialExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ErrorBadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchreadcommercepayments401Example:
                  summary: Default batchReadCommercePayments 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: &id001
                    - message: This is an example description.
                      code: example-value
                      in: example-value
                      subCategory: standard
                      context:
                        key: value
                    context: &id002
                      key: value
                    links: &id003
                      key: value
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Batchreadcommercepayments500Example:
                  summary: Default batchReadCommercePayments 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /crm/v3/objects/commerce_payments/batch/archive:
    post:
      tags:
      - Batch Operations
      summary: Hubspot Archive a Batch of Commerce Payments
      description: |
        Archives multiple commerce payment records by their IDs in a single request. 
        Archived payments can be restored later if needed.
      operationId: batchArchiveCommercePayments
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "BatchArchiveCommercePaymentsSuccessExample"
      security:
      - oauth2Auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchArchiveRequest'
            examples:
              BatchArchiveCommercePaymentsRequestExample:
                $ref: '#/components/examples/BatchArchiveCommercePaymentsRequestExample'
      responses:
        '204':
          description: Successfully archived commerce payments
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batcharchivecommercepayments400Example:
                  summary: Default batchArchiveCommercePayments 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batcharchivecommercepayments401Example:
                  summary: Default batchArchiveCommercePayments 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Batcharchivecommercepayments500Example:
                  summary: Default batchArchiveCommercePayments 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /crm/v3/objects/commerce_payments/batch/create:
    post:
      tags:
      - Batch Operations
      summary: Hubspot Create a Batch of Commerce Payments
      description: |
        Creates multiple commerce payment records in a single request. Each payment can include 
        properties and associations with other CRM objects.
      operationId: batchCreateCommercePayments
      x-microcks-operation:
        delay: 150
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "BatchCreateCommercePaymentsSuccessExample"
      security:
      - oauth2Auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateRequest'
            examples:
              BatchCreateCommercePaymentsRequestExample:
                $ref: '#/components/examples/BatchCreateCommercePaymentsRequestExample'
      responses:
        '201':
          description: Successfully created commerce payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateResponse'
              examples:
                BatchCreateCommercePaymentsSuccessExample:
                  $ref: '#/components/examples/BatchCreateCommercePaymentsSuccessExample'
        '207':
          description: Multi-status response - some payments created successfully, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateResponse'
              examples:
                Batchcreatecommercepayments207Example:
                  summary: Default batchCreateCommercePayments 207 response
                  x-microcks-default: true
                  value:
                    status: PENDING
                    results: &id009
                    - id: '500123'
                      properties: &id004
                        key: value
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                      archived: true
                      archivedAt: '2025-03-15T14:30:00Z'
                      associations: &id005
                        key: value
                      propertiesWithHistory: &id006
                        key: value
                    requestedAt: '2025-03-15T14:30:00Z'
                    startedAt: '2025-03-15T14:30:00Z'
                    completedAt: '2025-03-15T14:30:00Z'
                    numErrors: 100
                    errors: &id010
                    - status: active
                      id: '500123'
                      category: standard
                      message: This is an example description.
                      errors:
                      - {}
                      context:
                        key: value
                      links:
                        key: value
                      subCategory: standard
                    links: &id011
                      key: value
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchcreatecommercepayments400Example:
                  summary: Default batchCreateCommercePayments 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchcreatecommercepayments401Example:
                  summary: Default batchCreateCommercePayments 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Batchcreatecommercepayments500Example:
                  summary: Default batchCreateCommercePayments 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /crm/v3/objects/commerce_payments/batch/update:
    post:
      tags:
      - Batch Operations
      summary: Hubspot Update a Batch of Commerce Payments
      description: |
        Updates multiple commerce payment records in a single request. Only the specified 
        properties will be updated; other properties remain unchanged.
      operationId: batchUpdateCommercePayments
      x-microcks-operation:
        delay: 150
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "BatchUpdateCommercePaymentsSuccessExample"
      security:
      - oauth2Auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateRequest'
            examples:
              BatchUpdateCommercePaymentsRequestExample:
                $ref: '#/components/examples/BatchUpdateCommercePaymentsRequestExample'
      responses:
        '200':
          description: Successfully updated commerce payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateResponse'
              examples:
                BatchUpdateCommercePaymentsSuccessExample:
                  $ref: '#/components/examples/BatchUpdateCommercePaymentsSuccessExample'
        '207':
          description: Multi-status response - some payments updated successfully, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateResponse'
              examples:
                Batchupdatecommercepayments207Example:
                  summary: Default batchUpdateCommercePayments 207 response
                  x-microcks-default: true
                  value:
                    status: PENDING
                    results: &id012
                    - id: '500123'
                      properties: *id004
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                      archived: true
                      archivedAt: '2025-03-15T14:30:00Z'
                      associations: *id005
                      propertiesWithHistory: *id006
                    requestedAt: '2025-03-15T14:30:00Z'
                    startedAt: '2025-03-15T14:30:00Z'
                    completedAt: '2025-03-15T14:30:00Z'
                    numErrors: 100
                    errors: &id013
                    - status: active
                      id: '500123'
                      category: standard
                      message: This is an example description.
                      errors:
                      - {}
                      context:
                        key: value
                      links:
                        key: value
                      subCategory: standard
                    links: &id014
                      key: value
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchupdatecommercepayments400Example:
                  summary: Default batchUpdateCommercePayments 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Batchupdatecommercepayments401Example:
                  summary: Default batchUpdateCommercePayments 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Batchupdatecommercepayments500Example:
                  summary: Default batchUpdateCommercePayments 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /crm/v3/objects/commerce_payments:
    get:
      tags:
      - Single Payment Operations
      summary: Hubspot List Commerce Payments
      description: |
        Retrieves a paginated list of all commerce payments. Use query parameters to control 
        which properties are returned and to filter results.
      operationId: listCommercePayments
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "ListCommercePaymentsSuccessExample"
      security:
      - oauth2Auth: []
      parameters:
      - $ref: '#/components/parameters/LimitQuery'
        example: example-value
      - $ref: '#/components/parameters/AfterQuery'
        example: example-value
      - $ref: '#/components/parameters/PropertiesQuery'
        example: example-value
      - $ref: '#/components/parameters/PropertiesWithHistoryQuery'
        example: example-value
      - $ref: '#/components/parameters/AssociationsQuery'
        example: example-value
      - $ref: '#/components/parameters/ArchivedQuery'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved commerce payments list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercePaymentCollection'
              examples:
                ListCommercePaymentsSuccessExample:
                  $ref: '#/components/examples/ListCommercePaymentsSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listcommercepayments400Example:
                  summary: Default listCommercePayments 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listcommercepayments401Example:
                  summary: Default listCommercePayments 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Listcommercepayments500Example:
                  summary: Default listCommercePayments 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
    post:
      tags:
      - Single Payment Operations
      summary: Hubspot Create a Commerce Payment
      description: |
        Creates a new commerce payment record with the specified properties. Optionally, 
        associations with other CRM objects can be established at creation time.
      operationId: createCommercePayment
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "CreateCommercePaymentSuccessExample"
      security:
      - oauth2Auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommercePaymentInput'
            examples:
              CreateCommercePaymentRequestExample:
                $ref: '#/components/examples/CreateCommercePaymentRequestExample'
      responses:
        '201':
          description: Successfully created commerce payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercePayment'
              examples:
                CreateCommercePaymentSuccessExample:
                  $ref: '#/components/examples/CreateCommercePaymentSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createcommercepayment400Example:
                  summary: Default createCommercePayment 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createcommercepayment401Example:
                  summary: Default createCommercePayment 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Createcommercepayment500Example:
                  summary: Default createCommercePayment 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
  /crm/v3/objects/commerce_payments/{commercePaymentId}:
    get:
      tags:
      - Single Payment Operations
      summary: Hubspot Retrieve a Commerce Payment
      description: |
        Retrieves a specific commerce payment by its ID. Include optional query parameters 
        to control which properties are returned.
      operationId: getCommercePaymentById
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "GetCommercePaymentSuccessExample"
      security:
      - oauth2Auth: []
      parameters:
      - $ref: '#/components/parameters/CommercePaymentIdPath'
        example: example-value
      - $ref: '#/components/parameters/PropertiesQuery'
        example: example-value
      - $ref: '#/components/parameters/PropertiesWithHistoryQuery'
        example: example-value
      - $ref: '#/components/parameters/AssociationsQuery'
        example: example-value
      - $ref: '#/components/parameters/ArchivedQuery'
        example: example-value
      - $ref: '#/components/parameters/IdPropertyQuery'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved commerce payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercePayment'
              examples:
                GetCommercePaymentSuccessExample:
                  $ref: '#/components/examples/GetCommercePaymentSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcommercepaymentbyid400Example:
                  summary: Default getCommercePaymentById 400 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcommercepaymentbyid401Example:
                  summary: Default getCommercePaymentById 401 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '404':
          description: Commerce payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcommercepaymentbyid404Example:
                  summary: Default getCommercePaymentById 404 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

              examples:
                Getcommercepaymentbyid500Example:
                  summary: Default getCommercePaymentById 500 response
                  x-microcks-default: true
                  value:
                    category: standard
                    correlationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: This is an example description.
                    subCategory: standard
                    errors: *id001
                    context: *id002
                    links: *id003
    patch:
      tags:
      - Single Payment Operations
      summary: Hubspot Update a Commerce Payment
      description: |
        Performs a partial update of a commerce payment identified by its ID. Only the 
        specified properties will be updated. Read-only and non-existent properties are ignored.
      operationId: updateCommercePaymentById
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
        dispatcherRules: |
          def response = mockRequest.requestContent
          return "UpdateCommercePaymentSuccessExample"
      security:
      - oauth2Auth: []
      parameters:
      - $ref: '#/components/parameters/CommercePaymentIdPath'
        example: example-value
      - $ref: '#/components/parameters/IdPropertyQuery'
        example: example-value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommercePaymentPatch'
            examples:
              UpdateCommercePaymentRequestExample:
                $ref: '#/components/examples/UpdateCommercePaymentRequestExample'
      responses:
        '200':
          description: Successfully updated commerce payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercePayment'
              examples:
                UpdateCommercePaymentSuccessExample:
                  $ref: '#/components/examples/UpdateCommercePaymentSuccessExample'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updatecommercepaymentbyid400Example:
                  summary: Default updateCommercePaymentById 400 response
                  x-microcks-default: tr

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