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

# List Products (v3)

> List active products with their flat category, product config, and effective merchant pricing (COALESCE(merchant override, default)). Products of an inactive flat category and products disabled for the merchant are excluded. Flat category filter priority: category_flat_code > category_code > command. Use product_config_code to list the denoms of one product config (e.g. one game) from list-product-config.



## OpenAPI

````yaml https://biller-b2b.singapay.id/docs post /api/v3/list-product
openapi: 3.0.0
info:
  title: B2B Biller API
  description: >-
    API documentation for the B2B Biller service. Provides endpoints for bill
    payments (postpaid/prepaid), transaction management, balance checking, and
    authentication.
  version: 1.0.0
servers:
  - url: https://sandbox-biller-b2b.singapay.id
    description: Sandbox
  - url: https://biller-b2b.singapay.id
    description: Production
security: []
tags:
  - name: Authentication
    description: OAuth2 token generation
  - name: General
    description: Bill transaction listing, detail, balance, and utilities
  - name: Postpaid V1
    description: Postpaid bill inquiry and payment (V1)
  - name: Prepaid V1
    description: Prepaid inquiry and payment — PLN Token, Pulsa, Paket Data (V1)
  - name: Postpaid V2
    description: Postpaid bill inquiry and payment (V2)
  - name: Prepaid V2
    description: Prepaid inquiry, payment, and game topup (V2)
  - name: Postpaid V3
    description: >-
      Postpaid bill inquiry and payment with flat category validation (V3) —
      adds educ, prop, pbb
  - name: Prepaid V3
    description: >-
      Prepaid inquiry, payment, and game topup with flat category validation
      (V3) — adds strmg, emoney, ewallet, cashwd
  - name: Product V3
    description: >-
      Product, flat category, synthetic category tree, and product config
      listing (V3)
  - name: General V3
    description: >-
      Transaction detail with flat category (V3). check-balance,
      list-bill-transaction and list-bill-statement stay on v1;
      reset-customer-id has no version (/api/reset-customer-id).
paths:
  /api/v3/list-product:
    post:
      tags:
        - Product V3
      summary: List Products (v3)
      description: >-
        List active products with their flat category, product config, and
        effective merchant pricing (COALESCE(merchant override, default)).
        Products of an inactive flat category and products disabled for the
        merchant are excluded. Flat category filter priority: category_flat_code
        > category_code > command. Use product_config_code to list the denoms of
        one product config (e.g. one game) from list-product-config.
      operationId: listProductV3
      parameters:
        - name: X-PARTNER-ID
          in: header
          description: Your unique partner API key
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - command
              properties:
                command:
                  type: string
                  enum:
                    - list-product
                  example: list-product
                data:
                  properties:
                    category_flat_code:
                      description: >-
                        Flat category code (PULSA, DATA, TOPUPG, ...) — highest
                        priority
                      type: string
                      example: PULSA
                    category_code:
                      description: Alias of category_flat_code
                      type: string
                    command:
                      description: >-
                        Biller command (pulsa, topupg, ...) resolved to its flat
                        category; used only when the two above are empty
                      type: string
                      maxLength: 20
                    brand:
                      description: >-
                        Exact match (telkomsel, xl, ...); use search for partial
                        text
                      type: string
                      maxLength: 100
                      example: telkomsel
                    product_config_code:
                      description: Exact match (e.g. game code MLTP)
                      type: string
                      maxLength: 100
                    province_code:
                      description: Exact match (PDAM province)
                      type: string
                      maxLength: 10
                    search:
                      description: Matches product name or code
                      type: string
                      maxLength: 100
                    code:
                      description: Product code, partial match
                      type: string
                      maxLength: 50
                    name:
                      description: Product name, partial match
                      type: string
                      maxLength: 100
                    is_active:
                      description: >-
                        Only active products are returned, so false yields an
                        empty list
                      type: boolean
                    denomination_min:
                      type: integer
                      minimum: 0
                    denomination_max:
                      type: integer
                      minimum: 0
                    min_price:
                      description: >-
                        Minimum effective price (deposit_price for deposit
                        merchants, else selling_price)
                      type: number
                      minimum: 0
                    max_price:
                      description: Maximum effective price (same column as min_price)
                      type: number
                      minimum: 0
                    sort_by:
                      type: string
                      default: created_at
                      enum:
                        - name
                        - code
                        - selling_price
                        - deposit_price
                        - denomination
                        - created_at
                    sort_order:
                      type: string
                      default: desc
                      enum:
                        - asc
                        - desc
                    page:
                      type: integer
                      default: 1
                      minimum: 1
                    per_page:
                      type: integer
                      default: 10
                      maximum: 100
                      minimum: 1
                  type: object
              type: object
            examples:
              Basic:
                summary: First page
                value:
                  command: list-product
                  data:
                    page: 1
                    per_page: 20
              By brand:
                summary: Telkomsel pulsa, cheapest first
                value:
                  command: list-product
                  data:
                    category_flat_code: PULSA
                    brand: telkomsel
                    sort_by: selling_price
                    sort_order: asc
              Game denoms:
                summary: Mobile Legends denoms (by command + product config)
                value:
                  command: list-product
                  data:
                    command: topupg
                    product_config_code: MLTP
                    min_price: 10000
                    max_price: 50000
              PDAM by province:
                summary: PDAM products of one province
                value:
                  command: list-product
                  data:
                    category_flat_code: PDAM
                    province_code: '32'
      responses:
        '200':
          description: Products retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListV3Response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '422':
          description: Validation error (04)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Failed to fetch products (99)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillerErrorV3Response'
              example:
                command: list-product
                response_code: '99'
                response_text: Failed to fetch products
      security:
        - bearerAuth: []
components:
  schemas:
    ProductListV3Response:
      description: V3 product listing response with flat category and effective pricing
      properties:
        command:
          type: string
          example: list-product
        response_code:
          type: string
          example: '00'
        response_text:
          type: string
          example: Operation completed successfully
        data:
          properties:
            payment_agreement:
              type: string
              enum:
                - selling
                - deposit
              example: selling
            products:
              type: array
              items:
                $ref: '#/components/schemas/ProductListItemV3'
            pagination:
              $ref: '#/components/schemas/PaginationMeta'
          type: object
      type: object
    UnauthorizedErrorResponse:
      description: Unauthorized error response (HTTP 401)
      required:
        - status
        - success
        - error
      properties:
        status:
          type: integer
          example: 401
        success:
          type: boolean
          example: false
        error:
          properties:
            code:
              type: integer
              example: 401
            message:
              type: string
              example: Unauthorized merchant, please sign in
          type: object
      type: object
    ValidationErrorResponse:
      description: Validation error response (HTTP 422)
      required:
        - command
        - response_code
        - response_text
        - data
      properties:
        command:
          type: string
          example: detail-bill-transaction
        response_code:
          type: string
          example: '04'
        response_text:
          type: string
          example: Rejected Format Error
        data:
          description: Field-level error messages
          type: object
          example:
            data: The data field is required.
            data.transaction_id: The data.transaction id field is required.
          additionalProperties:
            type: string
      type: object
    BillerErrorV3Response:
      description: >-
        V3 biller error response. Common codes: 04 invalid argument / wrong
        password / missing reference_number (422), payment product_code or
        customer_id differ from the inquiry (400), 06 product not found, product
        or flat category inactive, reference_number used or expired (404) — or
        product not in the flat category of the command / wrong payment type /
        unknown command (400), 16 credential not found (422), 17 insufficient
        balance (400), 22/89 vendor error (503), 99 internal error (500). Full
        list: docs/feature-flow/RESPONSE_CODE_ALL.md.
      required:
        - command
        - response_code
        - response_text
      properties:
        command:
          type: string
          example: plnpos
        response_code:
          description: Error code (see schema description)
          type: string
          example: '06'
        response_text:
          type: string
          example: 'Product SPPLNPOS is not available: product is inactive'
      type: object
    ProductListItemV3:
      description: Product item in V3 listing with effective pricing and flat category
      properties:
        id:
          type: integer
          example: 1
        code:
          type: string
          example: SPTLKMAS10
        name:
          type: string
          example: Telkomsel Pulsa 10K
        product_category_id:
          description: Legacy hierarchy category FK
          type: integer
          example: 15
          nullable: true
        product_category_flat_id:
          description: Flat category FK
          type: integer
          example: 1
        brand:
          type: string
          example: telkomsel
          nullable: true
        product_config_code:
          description: >-
            FK ke product_configs.code — berisi config brand ini (image,
            request_fields, platform). Null untuk produk yang tidak butuh config
            khusus (PULSA, DATA, dll).
          type: string
          example: MLTP
          nullable: true
        product_config_id:
          description: FK product_configs.id; null kalau product_config_code null.
          type: integer
          example: 12
          nullable: true
        province_code:
          type: string
          example: null
          nullable: true
        denomination:
          type: integer
          example: 10000
        description:
          type: string
          example: null
          nullable: true
        is_active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: '2026-08-20T06:00:00.000000Z'
        effective_selling_price:
          description: COALESCE(merchant_override, default)
          type: string
          example: '11500'
        effective_admin_fee:
          type: string
          example: '0'
        effective_deposit_price:
          type: string
          example: '10800'
        effective_settlement_price:
          type: string
          example: '10500'
        has_custom_price:
          description: True if merchant has custom pricing override
          type: boolean
          example: false
        default_selling_price:
          type: string
          example: '11500'
        default_admin_fee:
          type: string
          example: '0'
        default_deposit_price:
          type: string
          example: '10800'
        default_settlement_price:
          type: string
          example: '10500'
        category_flat:
          description: Flat category of the product (only active categories are listed)
          properties:
            id:
              type: integer
              example: 1
            code:
              type: string
              example: PULSA
            name:
              type: string
              example: Pulsa Prabayar
            payment_type:
              type: string
              enum:
                - prepaid
                - postpaid
              example: prepaid
          type: object
        product_config:
          description: >-
            Config table untuk brand/platform ini: image, platform,
            request_fields, sort_order. Null untuk produk tanpa config khusus
            (PULSA, DATA). Gunakan brand filter di list-product untuk filter per
            brand; product_config hanya untuk baca metadata.
          properties:
            id:
              type: integer
              example: 12
            code:
              type: string
              example: MLTP
            name:
              type: string
              example: Topup Mobile Legend
            name_en:
              type: string
              example: Mobile Legends
              nullable: true
            image:
              type: string
              example: mltp.png
              nullable: true
            platform:
              type: string
              example: mobile
              nullable: true
          type: object
          nullable: true
        category:
          description: Legacy category (backward compat)
          properties:
            id:
              type: integer
              example: 15
            code:
              type: string
              example: TELASP
            name:
              type: string
              example: Telkomsel/AS
            parent_id:
              type: integer
              example: 5
              nullable: true
            parent:
              properties:
                id:
                  type: integer
                  example: 5
                code:
                  type: string
                  example: PULSA
                name:
                  type: string
                  example: Pulsa
              type: object
              nullable: true
          type: object
          nullable: true
      type: object
    PaginationMeta:
      description: Pagination metadata
      properties:
        current_page:
          type: integer
          example: 1
        last_page:
          type: integer
          example: 5
        per_page:
          type: integer
          example: 10
        total:
          type: integer
          example: 50
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: JWT Bearer token obtained from /api/v1.0/access-token/b2b
      bearerFormat: JWT
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.