> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cheqpay.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# List payment links

> List payment links with pagination, filtering, and sorting. Results are automatically filtered by the authenticated merchant unless a different merchantId is provided in the filter.



## OpenAPI

````yaml /api-reference/link-product-openapi.json post /payment-links/list
openapi: 3.0.0
info:
  title: Link Product API
  description: RESTful API for managing payment links, customers, and invoices
  version: 1.0.0
servers:
  - url: https://api.sandbox.cheqpay.mx/lps
    description: Sandbox environment
  - url: https://prod.cheqpay.mx/lps
    description: Production environment
security: []
tags:
  - name: Payment Links
    description: Operations related to payment links
  - name: Invoices
    description: Invoice creation and retrieval
  - name: Products
    description: Product management operations
paths:
  /payment-links/list:
    post:
      tags:
        - Payment Links
      summary: List payment links
      description: >-
        List payment links with pagination, filtering, and sorting. Results are
        automatically filtered by the authenticated merchant unless a different
        merchantId is provided in the filter.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPaymentLinksRequest'
            example:
              page: 1
              limit: 10
              filter:
                search: Premium
                isEnabled: true
              sort:
                field: createdAt
                order: desc
      responses:
        '200':
          description: Payment links retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentLinksResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ListPaymentLinksRequest:
      type: object
      description: Request to list payment links with pagination and filters
      properties:
        page:
          type: integer
          minimum: 1
          default: 1
          description: Page number (1-indexed)
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Number of items per page
        filter:
          type: object
          description: Filter criteria
          properties:
            search:
              type: string
              description: Search term to filter by payment link name (case-insensitive)
            merchantId:
              type: string
              pattern: ^[a-f\d]{24}$
              description: >-
                Merchant ID to filter by (defaults to authenticated merchant if
                not provided)
            isEnabled:
              type: boolean
              description: Filter by enabled status
        sort:
          type: object
          description: Sort criteria
          properties:
            field:
              type: string
              enum:
                - createdAt
              default: createdAt
              description: Field to sort by
            order:
              type: string
              enum:
                - asc
                - desc
              default: desc
              description: Sort order
    ListPaymentLinksResponse:
      type: object
      description: Paginated response containing payment links
      required:
        - data
        - currentPage
        - totalPages
        - totalCount
        - limit
      properties:
        data:
          type: array
          description: Array of payment links
          items:
            $ref: '#/components/schemas/PaymentLink'
        currentPage:
          type: integer
          description: Current page number
          example: 1
        totalPages:
          type: integer
          description: Total number of pages
          example: 5
        totalCount:
          type: integer
          description: Total number of payment links matching the filter
          example: 47
        limit:
          type: integer
          description: Number of items per page
          example: 10
    ValidationError:
      type: object
      description: Validation error response
      properties:
        message:
          type: string
          description: Error message
          example: Validation failed
    UnauthorizedError:
      type: object
      description: Unauthorized error response
      properties:
        message:
          type: string
          description: Error message
          example: Unauthorized
    InternalError:
      type: object
      description: Internal server error response
      properties:
        message:
          type: string
          description: Error message
          example: Internal server error
    PaymentLink:
      type: object
      description: Payment link entity
      required:
        - id
        - merchantId
        - type
        - currency
        - totals
        - paymentMethods
        - isDraft
        - isEnabled
      properties:
        _id:
          type: string
          description: MongoDB ObjectId
        name:
          type: string
          maxLength: 255
          description: Payment link name
        url:
          type: string
          description: Payment link URL
        id:
          type: string
          description: Unique payment link identifier
        merchantId:
          type: string
          description: Merchant identifier
        type:
          type: string
          enum:
            - products_subscriptions
            - customer_choice
            - products
            - subscription
          description: Payment link type
        products:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkProduct'
          description: Products in the payment link
        plans:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/SubscriptionPlan'
          description: Subscription plans (required when type is subscription, max 1)
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: Currency code (3 letters)
        totals:
          $ref: '#/components/schemas/PaymentLinkTotals'
        options:
          type: object
          description: Payment link options
          properties:
            collectShippingAddress:
              type: boolean
              default: false
              description: Whether to collect shipping address
            taxIdCollection:
              type: object
              description: Tax ID collection settings for checkout
              properties:
                enabled:
                  type: boolean
                  description: Whether checkout should ask for tax ID
                required:
                  type: boolean
                  default: false
                  description: When enabled is true, whether tax ID is mandatory
              required:
                - enabled
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
          minItems: 1
          maxItems: 20
          description: Additional questions to ask the customer at checkout
        numberOfPayments:
          type: number
          minimum: 1
          description: Number of payments for subscription
        paymentMethods:
          type: array
          items:
            type: string
            enum:
              - card
              - spei
              - cie_cash_net
              - paycash
          minItems: 1
          description: Available payment methods
        isDraft:
          type: boolean
          description: Whether the payment link is a draft
        isEnabled:
          type: boolean
          description: Whether the payment link is enabled
        redirectUrl:
          type: string
          description: URL to redirect after payment completion
        cancelUrl:
          type: string
          format: uri
          nullable: true
          description: URL the customer returns to when cancelling the checkout
        reference:
          type: string
          maxLength: 128
          description: Merchant reference for the payment link
        invoiceNumber:
          type: string
          maxLength: 64
          description: >-
            Merchant-provided invoice number shown to customers instead of the
            system order number when present. Free-form, not unique. Forwarded
            to the payment order on charge.
        description:
          type: string
          maxLength: 500
          description: >-
            Payment link description. Forwarded to the payment order on charge
            unless overridden in the charge request.
        externalId:
          type: string
          maxLength: 128
          description: External identifier for idempotent payment link creation
        defaults:
          type: object
          description: Default values for customer choice payment links
          properties:
            persistPaymentMethod:
              type: boolean
              description: >-
                Whether to persist the customer's payment method for future
                purchases
              default: false
            billingAddress:
              $ref: '#/components/schemas/BillingAddress'
            shippingAddress:
              $ref: '#/components/schemas/Address'
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata
        expiresAt:
          type: string
          format: date-time
          description: Expiration date
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
    PaymentLinkProduct:
      type: object
      description: Product in a payment link
      required:
        - name
        - qty
        - price
        - total
      properties:
        id:
          type: string
          description: Product identifier (optional for new products)
        name:
          type: string
          description: Product name
        description:
          type: string
          description: Product description
        qty:
          type: number
          minimum: 1
          description: Product quantity
        price:
          type: number
          minimum: 0
          description: Product price
        total:
          type: number
          minimum: 0
          description: Total price for this product
        imageUrl:
          type: string
          description: Product image URL
        isQtyAdjustable:
          type: boolean
          description: Whether the quantity is adjustable by the customer
        minQty:
          type: number
          description: Minimum quantity if adjustable
        maxQty:
          type: number
          description: Maximum quantity if adjustable
    SubscriptionPlan:
      type: object
      description: Full subscription plan details
      properties:
        id:
          type: string
          description: Plan identifier
        merchantId:
          type: string
          description: Merchant identifier
        externalId:
          type: string
          description: External identifier
        name:
          type: string
          description: Plan name
        description:
          type: string
          description: Plan description
        amount:
          type: number
          description: Plan amount
        currency:
          type: string
          enum:
            - MXN
            - USD
          description: Plan currency
        interval:
          type: string
          enum:
            - DAY
            - WEEK
            - MONTH
            - YEAR
          description: Billing interval
        intervalCount:
          type: number
          description: Number of intervals between billings
        trialDays:
          type: number
          description: Number of trial days
        active:
          type: boolean
          description: Whether the plan is active
        metadata:
          type: object
          description: Additional metadata
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
    PaymentLinkTotals:
      type: object
      description: Payment link totals
      required:
        - total
      properties:
        total:
          type: number
          minimum: 0
          description: Total amount
        taxes:
          type: number
          minimum: 0
          description: Tax amount
        shipping:
          type: number
          minimum: 0
          description: Shipping amount
        fees:
          type: number
          minimum: 0
          description: Fees amount
        discounts:
          type: number
          minimum: 0
          description: Discount amount
    CustomField:
      type: object
      description: >-
        Custom field asked of the customer at checkout. `options` is required
        when `type` is `radio`, `checkbox`, or `select`, and must be omitted for
        all other types.
      required:
        - type
        - label
      properties:
        type:
          type: string
          enum:
            - text
            - number
            - email
            - phone
            - date
            - switch
            - radio
            - checkbox
            - select
          description: Field input type
        label:
          type: string
          minLength: 1
          maxLength: 255
          description: Label shown to the customer
        required:
          type: boolean
          default: false
          description: Whether the customer must provide a value
        options:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
          minItems: 1
          maxItems: 50
          description: Available choices; required for `radio`, `checkbox`, and `select`
    BillingAddress:
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            isSameAsShipping:
              type: boolean
              description: Whether billing address is same as shipping
    Address:
      type: object
      description: Address information
      properties:
        firstName:
          type: string
          description: First name
        lastName:
          type: string
          description: Last name
        organizationName:
          type: string
          description: Organization name
        email:
          type: string
          format: email
          description: Email address
        phone:
          type: string
          description: Phone number
        addressLine1:
          type: string
          description: Street address
        addressLine2:
          type: string
          description: Additional address information (apartment, suite, unit, etc.)
        city:
          type: string
          description: City
        state:
          type: string
          description: State
        postalCode:
          type: string
          description: Postal code
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: Country code (2 letters)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for merchant authentication

````