HighLevel Transactions API

openapi: 3.2.0
info:
  title: Payments Transactions API
  description: Documentation for payments API
  version: '1.0'
  contact: {}
servers:
- url: https://services.leadconnectorhq.com
tags:
- name: Transactions
  description: Documentation for payments API
paths:
  /payments/transactions:
    get:
      operationId: list-transactions
      summary: List Transactions
      description: The "List Transactions" API allows to retrieve a paginated list of transactions. Customize your results by filtering transactions based on name, alt type, transaction status, payment mode, date range, type of source, contact, subscription id, entity id or paginate through the list using the provided query parameters. This endpoint provides a straightforward way to explore and retrieve transaction information.
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      - name: locationId
        required: false
        in: query
        description: LocationId is the id of the sub-account.
        schema:
          example: 3SwdhCu3svxI8AKsPJt6
          type: string
      - name: altId
        required: true
        in: query
        description: 'AltId is the unique identifier e.g: location id.'
        schema:
          example: 3SwdhCu3svxI8AKsPJt6
          type: string
      - name: altType
        required: true
        in: query
        description: AltType is the type of identifier.
        schema:
          example: location
          type: string
      - name: paymentMode
        required: false
        in: query
        description: Mode of payment.
        schema:
          example: live
          type: string
      - name: startAt
        required: false
        in: query
        description: Starting interval of transactions.
        schema:
          example: '2024-02-01'
          type: string
      - name: endAt
        required: false
        in: query
        description: Closing interval of transactions.
        schema:
          example: '2024-02-13'
          type: string
      - name: entitySourceType
        required: false
        in: query
        description: Source of the transactions.
        schema:
          example: funnel
          type: string
      - name: entitySourceSubType
        required: false
        in: query
        description: Source sub-type of the transactions.
        schema:
          example: two_step_order_form
          type: string
      - name: search
        required: false
        in: query
        description: The name of the transaction for searching.
        schema:
          example: Awesome transaction
          type: string
      - name: subscriptionId
        required: false
        in: query
        description: Subscription id for filtering of transactions.
        schema:
          example: sub_1KGcXDCScnf89tZoVkoEMCEL
          type: string
      - name: entityId
        required: false
        in: query
        description: Entity id for filtering of transactions.
        schema:
          example: 61dd0fe9c077f73e67f78803
          type: string
      - name: contactId
        required: false
        in: query
        description: Contact id for filtering of transactions.
        schema:
          example: XPLSw2SVagl12LMDeTmQ
          type: string
      - name: limit
        required: false
        in: query
        description: The maximum number of items to be included in a single page of results
        schema:
          default: 10
          example: 20
          type: number
      - name: offset
        required: false
        in: query
        description: The starting index of the page, indicating the position from which the results should be retrieved.
        schema:
          default: 0
          example: 0
          type: number
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTxnsResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnprocessableDTO
      tags:
      - Transactions
      security:
      - Location-Access:
        - payments/transactions.readonly
  /payments/transactions/{transactionId}:
    get:
      operationId: get-transaction-by-id
      summary: Get Transaction by ID
      description: The "Get Transaction by ID" API allows to retrieve information for a specific transaction using its unique identifier. Use this endpoint to fetch details for a single transaction based on the provided transaction ID.
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      - name: transactionId
        required: true
        in: path
        description: ID of the transaction that needs to be returned
        schema:
          example: 61dd0feac077f72010f78804
          type: string
      - name: locationId
        required: false
        in: query
        description: LocationId is the id of the sub-account.
        schema:
          example: 3SwdhCu3svxI8AKsPJt6
          type: string
      - name: altId
        required: true
        in: query
        description: 'AltId is the unique identifier e.g: location id.'
        schema:
          example: 3SwdhCu3svxI8AKsPJt6
          type: string
      - name: altType
        required: true
        in: query
        description: AltType is the type of identifier.
        schema:
          example: location
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTxnResponseSchema'
        '400':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnprocessableDTO
      tags:
      - Transactions
      security:
      - Location-Access:
        - payments/transactions.readonly
components:
  schemas:
    GetTxnResponseSchema:
      type: object
      properties:
        _id:
          type: string
          description: The unique identifier for the transaction.
          example: 61dd0feac077f72010f78804
        altType:
          type: string
          example: location
          description: AltType is the type of identifier.
        altId:
          type: string
          description: 'AltId is the unique identifier eg: location id.'
          example: 3SwdhCu3svxI8AKsPJt6
        contactId:
          type: string
          example: XPLSw2SVagl12LMDeTmQ
          description: Contact id corresponding to the transaction.
        contactSnapshot:
          type: object
          description: Contact details of the transaction.
          example: '{ last_name: "Mcclain", type: "lead", first_name_lower_case: "rogan", email: "anish+11@gohighlevel.com", last_name_lower_case: "mcclain", location_id: "o6241QsiRwUIJHyjuhos", company_name: "Jordan and Cox Trading"}'
        currency:
          type: string
          example: USD
          description: Currency in which transaction was made.
        amount:
          type: number
          example: '100'
          description: Transaction value.
        status:
          type: object
          example: succeeded
          description: Transaction status.
        liveMode:
          type: boolean
          example: 'false'
          description: Transaction is in live / test mode.
        createdAt:
          format: date-time
          type: string
          description: The creation timestamp of the transaction.
          example: '2023-11-20T10:23:36.515Z'
        updatedAt:
          format: date-time
          type: string
          description: The last update timestamp of the transaction.
          example: '2024-01-23T09:57:04.846Z'
        entityType:
          type: string
          example: order
          description: 'Entity type of transaction (eg: order).'
        entityId:
          type: string
          example: 61dd0fe9c077f73e67f78803
          description: 'Entity id for the transaction. e.g: order id'
        entitySource:
          description: Entity source details for the transaction.
          example: '{ type: "funnel", id: "BDBMEghdIUaqMPEsK349", subType: "two_step_order_form", name: "new funnel" }'
          allOf:
          - $ref: '#/components/schemas/OrderSource'
        chargeId:
          type: string
          example: in_1KGcXDCScnf89tZohCsmImwE
          description: Charge id for transaction.
        chargeSnapshot:
          type: object
          description: Charge snapshot of transaction.
          example: '{ id: "in_1KGcXDCScnf89tZohCsmImwE", object: "invoice", account_country: "US",  account_name:  "GHL-Testing" }'
        invoiceId:
          type: string
          example: in_1KGcXDCScnf89tZohCsmImwE
          description: Invoice id for the transaction.
        subscriptionId:
          type: string
          example: sub_1KGcXDCScnf89tZoVkoEMCEL
          description: Subscription id for transaction.
        paymentProvider:
          type: object
          description: Payment provider details of the transaction.
          example: '{ type: "stripe", connectedAccount: { _id: "612ca676b484b241fef9d962", accountId: "acct_1Ihw53CScnf89tZo" } }'
        ipAddress:
          type: string
          example: 107.178.194.224
          description: Ip address from where transaction was initiated.
        meta:
          type: object
          description: Meta details of the transaction.
          example: '{ stepId: "af7c731e-e36f-4152-bd1a-3f69a31d6d6d", pageId: "A8ltotc2jZxurJba4e3Y", pageUrl: "/v2/preview/A8ltotc2jZxurJba4e3Y" }'
        markAsTest:
          type: boolean
          description: Is test transaction.
          example: 'false'
        isParent:
          type: boolean
          description: Is parent transaction.
          example: 'false'
        amountRefunded:
          type: number
          example: '10'
          description: Transaction amount refunded.
        receiptId:
          type: string
          example: 6492fbea489bc07892c6defb
          description: Receipt id for transaction.
        qboSynced:
          type: boolean
          description: Is transaction qbo synced.
          example: 'false'
        qboResponse:
          type: object
          description: Qbo details of the transaction.
          example: '{ domain: "QBO", sparse: false, Id: "180", SyncToken: "0", TotalAmt: 25 }'
        traceId:
          type: string
          description: Trace id of the transaction.
          example: d3b16a92-a8ed-4e6b-8467-844750f78ed5
        mergedFromContactId:
          type: string
          example: XPLSw2SVagl12LMDeTmQ
          description: ID of the contact that was merged from.
        createdBy:
          type: string
          example: user123
          description: User ID who created the transaction.
      required:
      - _id
      - altType
      - altId
      - createdAt
      - updatedAt
    OrderSource:
      type: object
      properties:
        type:
          type: string
          enum:
          - funnel
          - website
          - invoice
          - calendar
          - text2Pay
          - document_contracts
          - membership
          - mobile_app
          - communities
          - point_of_sale
          - manual
          - form
          - survey
          - payment_link
          - external
        subType:
          type: string
          enum:
          - one_step_order_form
          - two_step_order_form
          - upsell
          - tap_to_pay
          - card_payment
          - store
          - contact_view
          - email_campaign
          - payments_dashboard
          - shopify
          - subscription_view
          - store_upsell
          - woocommerce
          - service
          - meeting
          - imported_csv
          - qr_code
          - saas_one_time
          - saas_subscription
        id:
          type: string
        name:
          type: string
        meta:
          type: object
      required:
      - type
      - id
    ListTxnsResponseDto:
      type: object
      properties:
        data:
          description: An array of transactions
          type: array
          items:
            $ref: '#/components/schemas/TxnResponseSchema'
        totalCount:
          type: number
          description: total transactions count
      required:
      - data
      - totalCount
    TxnResponseSchema:
      type: object
      properties:
        _id:
          type: string
          description: The unique identifier for the transaction.
          example: 61dd0feac077f72010f78804
        altId:
          type: string
          description: 'AltId is the unique identifier eg: location id.'
          example: 3SwdhCu3svxI8AKsPJt6
        altType:
          type: string
          example: location
          description: AltType is the type of identifier.
        contactId:
          type: string
          example: XPLSw2SVagl12LMDeTmQ
          description: Contact id corresponding to the transaction.
        mergedFromContactId:
          type: string
          example: XPLSw2SVagl12LMDeTmQ
          description: ID of the contact that was merged from.
        contactName:
          type: string
          example: James Bond
          description: Contact name corresponding to the transaction.
        contactEmail:
          type: string
          example: james.bond@gohighlevel.com
          description: Contact email corresponding to the transaction.
        currency:
          type: string
          example: USD
          description: Currency in which transaction occurred.
        amount:
          type: number
          example: '100'
          description: Transaction value.
        status:
          type: object
          description: The status of the transaction (e.g., succeeded).
          example: succeeded
        liveMode:
          type: boolean
          example: 'false'
          description: Transaction is in live / test mode.
        entityType:
          type: string
          example: order
          description: 'Entity type of transaction (eg: order).'
        entityId:
          type: string
          example: 61dd0fe9c077f73e67f78803
          description: 'Entity id for the transaction. e.g: order id'
        entitySourceType:
          type: string
          example: funnel
          description: 'Entity source type of transaction (eg: funnel).'
        entitySourceSubType:
          type: string
          example: two_step_order_form
          description: Entity source sub-type of the transactions.
        entitySourceName:
          type: string
          example: new funnel
          description: Entity source name for the transaction.
        entitySourceId:
          type: string
          description: Entity source id for the transaction.
          example: BDBMEghdIUaqMPEsK349
        entitySourceMeta:
          type: object
          description: Meta content for the entity source of transaction.
          example: '{ domain: "app.gohighlevel.com", pageId:  "rBVhyYhMsbxbO8ZqOcei", pageUrl:  "/v2/preview/rBVhyYhMsbxbO8ZqOcei", stepId:   "5a772f62-3fbc-418b-af1b-be8929dd64c2"}'
        subscriptionId:
          type: string
          example: sub_1KGcXDCScnf89tZoVkoEMCEL
          description: Subscription id for transaction.
        chargeId:
          type: string
          example: in_1KGcXDCScnf89tZohCsmImwE
          description: Charge id for transaction.
        chargeSnapshot:
          type: object
          description: Charge snapshot of transaction.
          example: '{ id: "in_1KGcXDCScnf89tZohCsmImwE", object: "invoice", account_country: "US",  account_name:  "GHL-Testing" }'
        paymentProviderType:
          type: string
          example: stripe
          description: Payment provider for transaction.
        paymentProviderConnectedAccount:
          type: string
          example: 612ca676b484b241fef9d962
          description: Payment provider  account id for transaction.
        ipAddress:
          type: string
          example: 107.178.194.224
          description: Ip address from where transaction was initiated.
        createdAt:
          format: date-time
          type: string
          description: The creation timestamp of the transaction.
          example: '2023-11-20T10:23:36.515Z'
        updatedAt:
          format: date-time
          type: string
          description: The update timestamp of the transaction.
          example: '2023-11-20T10:23:36.515Z'
        amountRefunded:
          type: number
          example: '10'
          description: Transaction amount refunded.
        paymentMethod:
          type: object
          example: '{ card: { "brand": "discover", "last4": "0012" } }'
          description: Transaction payment method details.
        fulfilledAt:
          format: date-time
          type: string
          description: The charged timestamp of the transaction.
          example: '2023-11-20T10:27:36.515Z'
        createdBy:
          type: string
          example: user123
          description: User ID who created the transaction.
      required:
      - _id
      - altId
      - altType
      - status
      - entitySourceType
      - createdAt
      - updatedAt
      - fulfilledAt
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.
      type: http
    Location-Access:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.
      type: http
    Location-Access-Only:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Sub-Account.
      type: http
    Agency-Access:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.
      type: http
    Agency-Access-Only:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Agency.
      type: http
x-tagGroups:
  name: Payments
  tags:
  - Payments
  - Integrations
  - Orders
  - Order fulfillments
  - Order Notes
  - Transactions
  - Subscriptions
  - Coupons
  - Custom Provider