HighLevel Orders API

openapi: 3.2.0
info:
  title: Payments Orders API
  description: Documentation for payments API
  version: '1.0'
  contact: {}
servers:
- url: https://services.leadconnectorhq.com
tags:
- name: Orders
  description: Documentation for payments API
paths:
  /payments/orders:
    get:
      operationId: list-orders
      summary: List Orders
      description: The "List Orders" API allows to retrieve a paginated list of orders. Customize your results by filtering orders based on name, alt type, order status, payment mode, date range, type of source, contact, funnel products or paginate through the list using the provided query parameters. This endpoint provides a straightforward way to explore and retrieve order 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: status
        required: false
        in: query
        description: Order status.
        schema:
          example: completed
          type: string
      - name: paymentStatus
        required: false
        in: query
        description: Payment Status of the Order
        schema:
          example: unpaid
          enum:
          - paid
          - unpaid
          - refunded
          - partially_paid
          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 orders.
        schema:
          example: '2024-02-01'
          type: string
      - name: endAt
        required: false
        in: query
        description: Closing interval of orders.
        schema:
          example: '2024-02-13'
          type: string
      - name: search
        required: false
        in: query
        description: The name of the order for searching.
        schema:
          example: Awesome order
          type: string
      - name: contactId
        required: false
        in: query
        description: Contact id for filtering of orders.
        schema:
          example: XPLSw2SVagl12LMDeTmQ
          type: string
      - name: funnelProductIds
        required: false
        in: query
        description: Funnel product ids separated by comma.
        schema:
          example: 61dd0c7dc077f712a5f787ff,61d6afc9d39ac5e35965c017
          type: string
      - name: sourceId
        required: false
        in: query
        description: Source id
        schema:
          example: 61dd0c7dc077f712a5f787ff
          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/ListOrdersResponseDto'
        '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:
      - Orders
      security:
      - Location-Access:
        - payments/orders.readonly
  /payments/orders/{orderId}:
    get:
      operationId: get-order-by-id
      summary: Get Order by ID
      description: The "Get Order by ID" API allows to retrieve information for a specific order using its unique identifier. Use this endpoint to fetch details for a single order based on the provided order ID.
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      - name: orderId
        required: true
        in: path
        description: ID of the order that needs to be returned
        schema:
          example: 653f5e0cde5a1314e62a837c
          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
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrderResponseSchema'
        '400':
          description: Order 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:
      - Orders
      security:
      - Location-Access:
        - payments/orders.readonly
  /payments/orders/{orderId}/record-payment:
    post:
      operationId: record-order-payment
      summary: Record Order Payment
      description: The "Record Order Payment" API allows to record a payment for an order. Use this endpoint to record payment for an order and update the order status to "Paid".
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      - name: orderId
        required: true
        in: path
        description: Order ID
        schema:
          example: 5e2d4c8e0e8b4e001c1c4f5d
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRecordOrderPaymentBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostRecordOrderPaymentResponse'
        '400':
          description: Order 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:
      - Orders
      security:
      - Location-Access:
        - payments/orders.collectPayment
components:
  schemas:
    ChequeDto:
      type: object
      properties:
        number:
          type: string
          description: check number
          example: 129-129-129-912
      required:
      - number
    GetOrderResponseSchema:
      type: object
      properties:
        _id:
          type: string
          description: The unique identifier for the order.
          example: 653f5e0cde5a1314e62a837c
        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 order.
        currency:
          type: string
          example: USD
          description: Currency in which order was created.
        amount:
          type: number
          example: '100'
          description: Order value.
        status:
          type: string
          description: The status of the order (e.g., completed).
          example: completed
        liveMode:
          type: boolean
          example: 'false'
          description: Order is in live / test mode.
        createdAt:
          format: date-time
          type: string
          description: The creation timestamp of the order.
          example: '2023-11-20T10:23:36.515Z'
        updatedAt:
          format: date-time
          type: string
          description: The last update timestamp of the order.
          example: '2024-01-23T09:57:04.846Z'
        fulfillmentStatus:
          type: string
          description: Fulfillment status of the order.
          example: unfulfilled
        contactSnapshot:
          type: object
          description: Contact details of the order.
          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"}'
        amountSummary:
          description: Amount details of the order.
          example: '{ subtotal: 100, discount: 5 }'
          allOf:
          - $ref: '#/components/schemas/AmountSummary'
        source:
          description: Source details of the order.
          example: '{ type: "invoice", id: "61dd48ff65b013bc39bb09c6" }'
          allOf:
          - $ref: '#/components/schemas/OrderSource'
        items:
          description: Item details of the order.
          example: '{ _id: 61dd33e88058b9f967ca79dc, authorizeAmount: 0, locationId: "SBAWb4yu7A4LSc0skQ6g", name: "Sample Product": price: {}, product: { name: "Testing product", productType: "SERVICE" }}'
          type: array
          items:
            type: string
        coupon:
          type: object
          description: Coupon details of the order.
          example: '{ code: "FEST10", _id: "63455e48901b43d4ef364a20" }'
        trackingId:
          type: string
          description: Tracking id of the order.
          example: 63319ef9-de0a-4c84-aebd-3585fb4a0cdf
        fingerprint:
          type: string
          description: Fingerprint id of the order.
          example: 5d51db5a-42b0-4b04-ba88-2c046c982a3a
        meta:
          type: object
          description: Meta details of the order.
          example: '{ couponSessionExpired: true }'
        markAsTest:
          type: boolean
          description: Is test order.
          example: 'false'
        traceId:
          type: string
          description: Trace id of the order.
          example: d3b16a92-a8ed-4e6b-8467-844750f78ed5
        automaticTaxesCalculated:
          type: boolean
          description: Automatic taxes applied for the Order
          example: true
        taxCalculationProvider:
          type: object
          description: Provider name for automatic tax calculation
          example: taxjar
        createdBy:
          type: string
          example: user123
          description: User ID who created the order.
      required:
      - _id
      - altId
      - altType
      - status
      - 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
    AmountSummary:
      type: object
      properties:
        subtotal:
          type: number
          example: '100'
          description: Order sub-total value.
        discount:
          type: number
          example: '10'
          description: Discount value on order.
      required:
      - subtotal
    CardDto:
      type: object
      properties:
        type:
          type: string
          enum:
          - visa
          - mastercard
          - other
          example: mastercard
        last4:
          type: string
          description: Last 4 digit of the card
          example: '1234'
      required:
      - type
      - last4
    PostRecordOrderPaymentBody:
      type: object
      properties:
        altId:
          type: string
          description: location Id / company Id based on altType
          example: 6578278e879ad2646715ba9c
        altType:
          type: string
          description: Alt Type
          enum:
          - location
          example: location
        mode:
          type: string
          description: manual payment method
          enum:
          - cash
          - card
          - cheque
          - bank_transfer
          - other
          example: card
        card:
          description: Details of Card if used for payment
          allOf:
          - $ref: '#/components/schemas/CardDto'
        cheque:
          description: Details of the Cheque if used for payment
          allOf:
          - $ref: '#/components/schemas/ChequeDto'
        notes:
          type: string
          description: Any note to be recorded with the transaction
          example: This was a direct payment
        amount:
          type: number
          description: Amount to be paid against the invoice.
          example: 100
        meta:
          type: object
          description: Meta data to be recorded with the transaction
        isPartialPayment:
          type: boolean
          description: Indicates if the order is intended to be a partial payment.
      required:
      - altId
      - altType
      - mode
    OrderResponseSchema:
      type: object
      properties:
        _id:
          type: string
          description: The unique identifier for the order.
          example: 653f5e0cde5a1314e62a837c
        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 order.
        contactName:
          type: string
          example: James Bond
          description: Contact name corresponding to the order.
        contactEmail:
          type: string
          example: james.bond@gohighlevel.com
          description: Contact email corresponding to the order.
        currency:
          type: string
          example: USD
          description: Currency in which order was created.
        amount:
          type: number
          example: '100'
          description: Order value.
        subtotal:
          type: number
          example: '100'
          description: Order sub-total value.
        discount:
          type: number
          example: '10'
          description: Discount value on order.
        status:
          type: string
          description: The status of the order (e.g., completed).
          example: completed
        liveMode:
          type: boolean
          example: 'false'
          description: Order is in live / test mode.
        totalProducts:
          type: number
          example: '5'
          description: Total products in an order.
        sourceType:
          type: string
          example: funnel
          description: 'Source type of order (eg: funnel).'
        sourceName:
          type: string
          example: onestep
          description: Source name for the order.
        sourceId:
          type: string
          description: Source id for the order.
          example: kDj7BHej9Zyyq3QakJmz
        sourceMeta:
          type: object
          description: Meta content for the source of order.
          example: '{ domain: "app.gohighlevel.com", pageId:  "rBVhyYhMsbxbO8ZqOcei", pageUrl:  "/v2/preview/rBVhyYhMsbxbO8ZqOcei", stepId:   "5a772f62-3fbc-418b-af1b-be8929dd64c2"}'
        couponCode:
          type: string
          description: Coupon code for the order.
          example: 100PER
        createdAt:
          format: date-time
          type: string
          description: The creation timestamp of the order.
          example: '2023-11-20T10:23:36.515Z'
        updatedAt:
          format: date-time
          type: string
          description: The last update timestamp of the order.
          example: '2024-01-23T09:57:04.846Z'
        sourceSubType:
          type: string
          description: Source sub-type for the order.
          example: one_step_order_form
        fulfillmentStatus:
          type: string
          description: Fulfillment status of the order.
          example: unfulfilled
        onetimeProducts:
          type: number
          example: '1'
          description: Total one time products in an order.
        recurringProducts:
          type: number
          example: '1'
          description: Total recurring time products in an order.
        createdBy:
          type: string
          example: user123
          description: User ID who created the order.
      required:
      - _id
      - altId
      - altType
      - status
      - sourceType
      - createdAt
      - updatedAt
    ListOrdersResponseDto:
      type: object
      properties:
        data:
          description: An array of orders
          type: array
          items:
            $ref: '#/components/schemas/OrderResponseSchema'
        totalCount:
          type: number
          description: total orders count
      required:
      - data
      - totalCount
    PostRecordOrderPaymentResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status of the request
          example: true
      required:
      - success
  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