---
title: "List Invoices"
method: GET
path: "/api/v2/invoices"
tags: ["Invoices"]
---

# List Invoices

`GET /api/v2/invoices`

List all invoices with pagination, filtering, and sorting options.

## Query parameters

- `include_payments` boolean, nullable
- `payment_link_id` string, uuid, nullable
- `statuses` InvoiceStatusEnum[], nullable
- `payment_statuses` PaymentStatusEnum[], nullable — Invoice includes payments with the following statuses
- `search_term` string, nullable
- `from_date` string, date-time, nullable
- `to_date` string, date-time, nullable
- `due_date_from` string, date-time, nullable — Invoice's payment due date from this date onwards
- `due_date_to` string, date-time, nullable — Invoice's payment due date to this date or older
- `from_price` union
  - number
  - string
- `to_price` union
  - number
  - string
- `organization_consumer_id` string, uuid4, nullable
- `subscription_id` string, uuid4, nullable
- `metered_subscription_id` string, uuid4, nullable
- `currencies` string, nullable — Filter by invoice currency codes (OR). E.g. currencies=SAR,USD
- `payments_not_settled` boolean, nullable — When true, only include invoices with a SUCCEEDED card/wallet payment (e.g. MADA, Visa).
- `page` integer — Page number, defaults to 1.
- `limit` integer — Size of a page, defaults to 10. Maximum is 100.
- `sort_field` string, nullable — Field to sort by, e.g., 'amount', 'scheduled_on'
- `sort_direction` string, nullable — Sorting direction ('asc' or 'desc')

## Response `200`

Successful Response

- ListResourceInvoiceListItem
  - `data` InvoiceListItem[]
    - `created_at` string, date-time — Creation timestamp of the object.
    - `updated_at` string, date-time, nullable — Last modification timestamp of the object.
    - `id` string, uuid4 — Unique identifier (UUID) of the invoice
    - `payment_link_id` string, uuid4, nullable — Unique identifier (UUID) of the payment link if invoice was created from one
    - `metered_subscription_id` string, uuid4, nullable — Unique identifier (UUID) of the metered subscription billed by this invoice
    - `user_id` string, uuid4 — Unique identifier (UUID) of the user who created the invoice
    - `organization_id` string, uuid4 — Unique identifier (UUID) of the organization
    - `organization_consumer_id` string, uuid4 — Unique identifier (UUID) of the organization consumer
    - `account_id` string, uuid4 — Unique identifier (UUID) of the account
    - `branch_id` string, uuid4 — Unique identifier (UUID) of the branch
    - `org_invoice_number` integer — Organization-specific invoice number
    - `description` string, nullable — Description of the invoice
    - `total_amount` string — Total invoice amount after discounts (in invoice currency)
    - `original_amount` string — Original invoice amount before discounts (in invoice currency)
    - `item_level_discounted_amount` string — Total amount discounted at the item level
    - `total_vat_amount` string, nullable — Total VAT amount calculated from products
    - `total_price_excluding_vat` string, nullable — Total price excluding VAT
    - `coupon_calculation_metadata` CouponCalculationMetadataDto
      - `coupons` CouponMetadataDto[] — List of coupons applied and their calculation details
        - `coupon_id` string — Unique identifier of the coupon
        - `name` string — Name of the coupon
        - `is_percentage` boolean — Whether the discount is a percentage or fixed amount
        - `discount_value` string — Discount value (percentage or fixed amount)
        - `currency` string, nullable — Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons.
        - `order` integer — Order in which the coupon was applied
        - `amount_before_discount` string — Amount before applying this coupon
        - `discount_amount` string — Discount amount applied by this coupon
        - `amount_after_discount` string — Amount after applying this coupon
    - `currency` 'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR' — ISO 4217 currency codes supported by Moyasar. Includes all currencies supported by Moyasar payment gateway.
    - `home_currency_amount` string, nullable — Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices.
    - `home_currency_amount_actual` string, nullable — Actual settled amount in home currency (SAR) after payment processing.
    - `exchange_rate_at_creation` string, nullable — Exchange rate used at invoice creation time (for audit). 1 for SAR invoices.
    - `consumer_message` string, nullable — Message to display to the consumer
    - `status` 'DRAFT' | 'CREATED' | 'SENT' | 'ACCEPTED' | 'REJECTED' | 'COMPLETED' | 'CANCELED' | 'EXPIRED' — Invoice status enum representing the lifecycle/state of an invoice. Status describes the current stage of an invoice in its lifecycle (DRAFT → CREATED → ACCEPTED → COMPLETED). This changes over time as the invoice progresses. Different from InvoiceType which describes the payment structure.
    - `payment_method` 'OPENBANKING' | 'PAYMENTGATEWAY'
    - `allowed_payment_flow` 'ALL' | 'AUTO' | 'MANUAL'
    - `current_payment_flow` 'ALL' | 'AUTO' | 'MANUAL'
    - `period_start` string, date-time, nullable — Start date and time of the billing period
    - `period_end` string, date-time, nullable — End date and time of the billing period
    - `recurring_interval` 'WEEK' | 'MONTH' | 'SEMESTER' | 'YEAR'
    - `recurring_interval_count` integer, nullable — Number of intervals per billing cycle for recurring invoices
    - `type` 'ONE_OFF' | 'ONE_OFF_FUTURE' | 'RECURRING' | 'INSTALLMENTS' | 'PRORATION' — Invoice type enum representing the payment structure/pattern of an invoice. Type describes how the invoice is structured for payments (ONE_OFF, RECURRING, INSTALLMENTS, etc.). This is determined at invoice creation and typically doesn't change. Different from InvoiceStatusEnum which describes the current lifecycle state of the invoice.
    - `no_of_payments` integer, nullable — Number of payment rows on the invoice (updated when payments are added or split)
    - `remaining_amount` string, nullable — Remaining amount to be paid
    - `paid_amount` string — Total amount already paid
    - `organization_consumer` AppCommonDtosSharedOrganizationConsumer
      - `id` string, uuid4
      - `name` string
      - `alias` string, nullable
      - `email` string, email, nullable
      - `phone_number` string, phone, nullable
      - `preferred_language` 'AR' | 'EN'
      - `consumer_type` 'INDIVIDUAL' | 'BUSINESS'
      - `address` AddressResponse — Address response model.
        - `address_line_1` string — Address line 1
        - `address_line_2` string, nullable — Address line 2
        - `city` string — City
        - `postal_code` string, nullable — Postal code
        - `country` string — Country
      - `vat_number` string, nullable
      - `commercial_registration` string, nullable
      - `consumer` AppCommonDtosSharedConsumer
        - `id` string, uuid4
        - `phone_number` string, phone, nullable
        - `email` string, email, nullable
        - `preferred_language` 'AR' | 'EN'
      - `is_deleted` boolean, nullable
      - `communication_methods` ConsumerCommunicationMethod[], nullable
    - `subscription` InvoiceListSubscrptionDto
      - `id` string, uuid4 — Unique identifier (UUID) of the subscription
      - `recurring_interval` 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR'
      - `recurring_interval_count` integer — Number of intervals per billing cycle
      - `status` 'INACTIVE' | 'ACTIVE' | 'EXPIRED' | 'CANCELED' | 'FROZEN' | 'TRIALING' | 'TRIAL_PENDING'
      - `current_period_start` string, date-time — Start date and time of the current billing period
      - `current_period_end` string, date-time, nullable — End date and time of the current billing period
      - `cancel_at_period_end` boolean — Whether the subscription will be canceled at the end of the current period
    - `payments` PaymentDto[], nullable — List of payments associated with this invoice
      - `id` string, uuid4 — Unique identifier (UUID) of the payment
      - `amount` string — Payment amount
      - `currency` 'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR' — ISO 4217 currency codes supported by Moyasar. Includes all currencies supported by Moyasar payment gateway.
      - `scheduled_on` string, date-time — Scheduled date and time for the payment
      - `invoice_payment_number` integer — Payment number within the invoice
      - `type` 'INITIAL' | 'INSTALLMENT' | 'SPLIT_PREPAID' | 'SPLIT_REMAINDER'
      - `payment_method` 'MADA' | 'MASTERCARD' | 'VISA' | 'APPLE_PAY' | 'SAMSUNG_PAY' | 'AMEX' | 'CASH' | 'PGW_CARD_UNSPECIFIED' | 'BANK_TRANSFER' | 'CARD' | 'QURRAH' | 'BNPL'
      - `current_status` 'PENDING' | 'PROCESSING' | 'FAILED_INITIATION' | 'SUCCEEDED' | 'FAILED' | 'CANCELED' | 'UNDER_REVIEW' | 'EXPIRED' | 'SETTLED' | 'REFUNDED' | 'PARTIALLY_REFUNDED'
      - `payed_at` string, date-time, nullable — Date and time when the payment was completed
      - `settled_at` string, date-time, nullable — Date and time when the payment was settled
      - `refunded_at` string, date-time, nullable — Date and time when the payment was refunded
      - `amount_refunded` string — Sum of all refund rows for this payment
      - `refunds` PaymentRefundResponse[] — Refund history for this payment
        - `id` string, uuid — Unique identifier of the refund row
        - `amount_refunded` string — Amount refunded in this refund
        - `refunded_at` string, date-time — When this refund was recorded
        - `refund_reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' | 'OTHER'
        - `refund_note` string, nullable — Note explaining the refund if applicable
      - `pdf_link` string, nullable — URL to the payment PDF document
      - `paid_to_account_id` string, uuid4, nullable — Unique identifier (UUID) of the account the payment was made to
      - `amount_in_smallest_unit` integer — Payment amount in smallest currency unit (e.g. halala for SAR).
    - `total_number_of_payments` integer — Total number of payments for this invoice
    - `last_payment_paid_at` string, date-time, nullable — The date when the last payment was paid
    - `total_amount_in_smallest_unit` integer — Total invoice amount in smallest currency unit (e.g. halala for SAR).
    - `original_amount_in_smallest_unit` integer — Original invoice amount (before discounts) in smallest currency unit.
    - `remaining_amount_in_smallest_unit` integer, nullable — Remaining amount in smallest currency unit.
    - `paid_amount_in_smallest_unit` integer — Paid amount in smallest currency unit.
  - `pagination` Pagination
    - `total_count` integer
    - `max_page` integer
    - `current_page` integer
    - `limit` integer
    - `has_next_page` boolean
    - `has_previous_page` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/streampay/apis/stream-app.md) · [All operations](https://skmtc.dev/streampay/apis/stream-app/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/streampay/stream-app/revisions/515eeea7d260/schema)