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

# List orders

> `payment_url` / `checkout_url` are the hosted pay page on the store
domain (custom domain or free subdomain).
This endpoint does not start a gateway session. Use get-one for a
live Duitku payment URL.




## OpenAPI

````yaml /openapi.yaml get /orders
openapi: 3.1.0
info:
  title: Kawan Digital Public API
  version: 1.0.0
  summary: Store-scoped Order API
  description: >
    External systems can create and read **store orders** using API keys, and

    receive lifecycle events via signed webhooks.


    - **Access:** Growth and Scale stores only

    - **Auth:** `Authorization: Bearer {API_KEY}`

    - **Manage keys / webhooks:** [Dashboard → Developer
    API](https://kawan.digital/dashboard/settings/developers)

    - **Tutorial:** [Integrasi API](/integrasi)

    - **Webhooks:** [Dokumentasi webhook](/webhooks)

    - **Docs hub:** [Ringkasan](/)


    All JSON responses use `{ "success": true, "data": … }` or

    `{ "success": false, "error": { "code", "message" } }`.


    Amounts are IDR integers. Keys are scoped to **one store**.
  contact:
    name: Kawan Digital
    email: halo@kawan.digital
    url: https://kawan.digital/kontak
servers:
  - url: https://api.kawan.digital/v1
    description: Production
  - url: http://api.lvh.me:3000/v1
    description: Local (requires NEXT_PUBLIC_ROOT_DOMAIN=lvh.me)
security:
  - bearerAuth: []
tags:
  - name: Catalog
    description: Published products and bundles for the authenticated store.
  - name: Payments
    description: Checkout methods available for the store.
  - name: Orders
    description: Create and read store orders.
  - name: Webhooks
    description: |
      Signed HTTPS callbacks for order lifecycle events.
      See [Webhook documentation](/webhooks).
paths:
  /orders:
    get:
      tags:
        - Orders
      summary: List orders
      description: |
        `payment_url` / `checkout_url` are the hosted pay page on the store
        domain (custom domain or free subdomain).
        This endpoint does not start a gateway session. Use get-one for a
        live Duitku payment URL.
      operationId: listOrders
      parameters:
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/OrderStatus'
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Inclusive created_at lower bound (ISO 8601).
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: Inclusive created_at upper bound (ISO 8601).
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Order page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    OrderStatus:
      type: string
      enum:
        - pending
        - awaiting_verification
        - paid
        - failed
        - expired
        - refunded
    OrderListResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
            - orders
            - has_more
          properties:
            orders:
              type: array
              items:
                $ref: '#/components/schemas/Order'
            has_more:
              type: boolean
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/OrderStatus'
        payment_reference:
          type:
            - string
            - 'null'
        amount:
          type: integer
        subtotal:
          type: integer
        currency:
          type: string
          const: IDR
        settlement_channel:
          type: string
        payment_provider:
          type:
            - string
            - 'null'
        payment_method:
          type:
            - string
            - 'null'
        buyer:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
              format: email
            phone:
              type:
                - string
                - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        checkout_url:
          type:
            - string
            - 'null'
          format: uri
          description: Kawan hosted pay page on the store custom domain or free subdomain.
        payment_url:
          type:
            - string
            - 'null'
          format: uri
          description: |
            Best URL to send the buyer to pay. On create / get-one this is the
            Duitku payment URL. List and webhook payloads use the hosted
            checkout page.
        requires_payment:
          type: boolean
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - UNAUTHORIZED
                - FORBIDDEN
                - PLAN_REQUIRED
                - NOT_FOUND
                - CONFLICT
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
    OrderItem:
      type: object
      properties:
        type:
          type: string
          enum:
            - product
            - bundle
        title:
          type: string
        quantity:
          type: integer
        unit_price:
          type: integer
        line_total:
          type: integer
        product_id:
          type:
            - string
            - 'null'
          format: uuid
        bundle_id:
          type:
            - string
            - 'null'
          format: uuid
  parameters:
    Offset:
      in: query
      name: offset
      schema:
        type: integer
        minimum: 0
        default: 0
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
  responses:
    InvalidRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: INVALID_REQUEST
              message: Invalid JSON body.
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Missing or invalid Authorization header.
    PlanRequired:
      description: Public API is not on this store's plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PLAN_REQUIRED
              message: Public API is not available on this store's plan.
    RateLimited:
      description: Rate limit exceeded (Retry-After header)
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the client may retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from Dashboard → Developer API. Shown once when created.

````