--- title: "List Subscriptions" method: GET path: "/api/v2/subscriptions" tags: ["Subscriptions"] --- # List Subscriptions `GET /api/v2/subscriptions` List all subscriptions with pagination, filtering, and sorting options. ## Query parameters - `statuses` SubscriptionStatus[], nullable — Filter by subscription status - `latest_invoice_is_paid` boolean, nullable — Filter subscriptions based on if their latest invoice is paid or partially paid - `from_date` string, date-time, nullable — datetime is created_at - `to_date` string, date-time, nullable — datetime is created_at - `current_period_start_from_date` string, date-time, nullable — Filter subscriptions with current_period_start from this date onwards - `current_period_start_to_date` string, date-time, nullable — Filter subscriptions with current_period_start up to this date - `current_period_end_from_date` string, date-time, nullable — Filter subscriptions with current_period_end from this date onwards - `current_period_end_to_date` string, date-time, nullable — Filter subscriptions with current_period_end up to this date - `from_price` union — limit list by min subscription amount inclusive - number - string - `to_price` union — limit list by max subscription amount inclusive - number - string - `organization_consumer_id` string, uuid4, nullable — filter subscriptions that belongs to organization consumer - `search_term` string, nullable — Serach by product name or description. - `product_ids` string[], nullable — Product ids that need to be in the list of subscriptions - `currencies` string, nullable — Filter subscriptions by currency codes (OR). E.g. currencies=SAR,USD - `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 - ListResourceSubscriptionDetailed - `data` SubscriptionDetailed[] - `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 subscription - `description` string, nullable — Description of the subscription - `amount` string — Total subscription amount after discounts - `original_amount` string — Original subscription amount before discounts - `item_level_discounted_amount` string — Total amount discounted at the item level - `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 - `remaining_days` integer — Number of days remaining in the current billing period - `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 — Amount in home currency (SAR) at creation - `exchange_rate_at_creation` string, nullable — Exchange rate used at subscription creation - `recurring_interval` 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' - `recurring_interval_count` integer — Number of intervals per billing cycle (e.g., 2 for bi-monthly) - `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 — End date and time of the current billing period - `current_cycle_number` integer — Current cycle number of the subscription - `cancel_at_period_end` boolean — Whether the subscription will be canceled at the end of the current period - `cancel_at_cycle_number` integer, nullable — Cycle number at which the subscription will be automatically canceled - `started_at` string, date-time, nullable — Date and time when the subscription started - `ended_at` string, date-time, nullable — Date and time when the subscription ended - `user_id` string, uuid4 — Unique identifier (UUID) of the user who created the subscription - `organization_consumer_id` string, uuid4 — Unique identifier (UUID) of the organization consumer - `latest_invoice_id` string, uuid4, nullable — Unique identifier (UUID) of the most recent invoice for this subscription - `trial_period_days` integer, nullable — Number of days for the free trial period - `trial_end` string, date-time, nullable — Date and time when the trial period ends - `organization_consumer` AppSubscriptionV2DtosOrganizationConsumer - `id` string, uuid4 — Unique identifier (UUID) of the organization consumer - `name` string — Name of the consumer - `alias` string, nullable — Alias of the consumer - `email` string, nullable — Email address of the consumer - `phone_number` string, nullable — Phone number of the consumer - `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 — VAT number for business consumers - `commercial_registration` string, nullable — Commercial registration for business consumers - `items` SubscriptionItemDto[], nullable — List of items included in the subscription - `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 subscription item - `product_id` string, uuid4 — Unique identifier (UUID) of the product - `subscription_id` string, uuid4 — Unique identifier (UUID) of the subscription - `quantity` integer — Quantity of the product in this subscription item - `original_amount` string — Original amount before discounts - `discounted_amount` string — Amount after discounts are applied - `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 - `product` ProductDto — Product response DTO. This DTO includes both legacy single-price fields and new multi-currency `prices` array for backward compatibility with existing API consumers. Legacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price and are kept for backward compatibility. New integrations should use the `prices` array. - `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 product - `name` string — Name of the product. - `description` string, nullable — Description of the product. - `type` 'RECURRING' | 'ONE_OFF' | 'METERED' - `recurring_interval` 'WEEK' | 'MONTH' | 'SEMESTER' | 'YEAR' - `recurring_interval_count` integer — The billing cycle multiple if the product is recurring - `price` string — Total price including VAT (default currency). - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAD' | 'XAF' | 'XCD' | 'XCG' | 'XOF' | 'XPF' | 'XSU' | 'XUA' | 'YER' | 'ZAR' | 'ZMW' | 'ZWG' — Default price currency of the product. - `is_price_exempt_from_vat` boolean — Is the default price exempt from VAT? - `is_price_inclusive_of_vat` boolean — [DEPRECATED] This field will be removed; non-exempt prices will be assumed inclusive. - `price_excluding_vat` string — [DEPRECATED] Default price excluding VAT. VAT will be calculated on invoice. - `vat_amount` string — [DEPRECATED] VAT amount for default price. VAT will be calculated on invoice. - `prices` ProductPriceInlineDto[] — All active prices for this product across different currencies. - `id` string, uuid4 - `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. - `amount` string - `is_active` boolean - `is_price_inclusive_of_vat` boolean — [DEPRECATED] This field will be removed; non-exempt prices will be assumed inclusive. - `is_price_exempt_from_vat` boolean - `price_excluding_vat` string — [DEPRECATED] Net amount excluding VAT. VAT will be calculated on invoice. - `vat_amount` string — [DEPRECATED] VAT amount. VAT will be calculated on invoice. - `is_active` boolean — Can this product be used in invoices or subscriptions? - `is_one_time` boolean — Shows if the product was created to be used once, and not to be added to product cataloge - `is_used_in_finalized_invoice` boolean — Is the product used in a finalized invoice? - `external_metadata` ExternalMetadataStorage - `latest_invoice` InvoiceBase — Base invoice response DTO. Multi-Currency Support: - `currency`: The currency code for the invoice (e.g., SAR, USD, EUR) - `home_currency_amount`: Total amount converted to home currency (SAR) for reporting - `home_currency_amount_actual`: Actual settled amount in home currency after payment - `exchange_rate_at_creation`: Exchange rate used at invoice creation time (for audit) For SAR invoices, `home_currency_amount` equals `total_amount` and `exchange_rate_at_creation` is 1. - `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) - `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. - `latest_freeze` FreezeSubscriptionBase - `created_at` string, date-time — Creation timestamp of the object. - `updated_at` string, date-time, nullable — Last modification timestamp of the object. - `id` string, uuid - `freeze_start_datetime` string, date-time - `freeze_end_datetime` string, date-time, nullable - `notes` string, nullable - `subscription_id` string, uuid - `invoice_id` string, uuid - `duration` integer, nullable - `override_payment_methods` SubscriptionPaymentMethodDto - `visa` boolean, nullable — override visa from global settings - `mastercard` boolean, nullable — override mastercard from global settings - `amex` boolean, nullable — override amex from global settings - `bank_transfer` boolean, nullable — override bank_transfer from global settings - `installment` boolean, nullable — override installment from global settings - `qurrah` boolean, nullable — override qurrah from global settings - `subscription_auto_renewal` boolean, nullable — Override organization's subscription auto renewal setting. If True, subscription will auto-renew at the end of each period. If False, subscription will be canceled at the end of the current period. If None (default), uses organization's subscription_auto_renewal setting. - `pending_change` PendingPlanChange — Server-computed snapshot of a deferred plan change for client display. - `id` string, uuid4 — Pending change identifier - `effective_at` string, date-time — When this change will take effect (subscription period end) - `invoice_was_reissued` boolean — True if the next-cycle invoice had to be cancelled and recreated to reflect this change - `target_items` PendingPlanChangeItemPreview[] — Items the subscription will have after the change is applied - `product_id` string, uuid4 — Product UUID - `product_name` string — Product display name - `quantity` integer — Quantity that will be billed under the new plan - `original_amount` string — Per-item original amount in subscription currency - `discounted_amount` string — Per-item amount after item-level discounts - `target_subscription_coupon_ids` string[] — Subscription-level coupons that will be active after the change - `target_recurring_interval` 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' - `target_recurring_interval_count` integer — Billing interval multiplier after the change - `target_amount` string — Total amount per cycle under the new plan - `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. - `current_amount` string — Subscription's current per-cycle amount - `delta_amount` string — target_amount - current_amount - `delta_amount_per_month` string, nullable — target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms. - `changes` PendingPlanChangeDiffEntry[] — Human-renderable, server-computed list of changes - `kind` 'PRODUCT_ADDED' | 'PRODUCT_REMOVED' | 'PRODUCT_REPLACED' | 'QUANTITY_DECREASED' | 'QUANTITY_INCREASED' | 'COUPON_ADDED' | 'COUPON_REMOVED' | 'INTERVAL_CHANGED' — Server-classified diff entry kinds for a pending plan change. - `label` string — Pre-formatted, locale-neutral label suitable for display - `product_id` string, uuid4, nullable — Affected product, if applicable - `from_value` string, nullable — Pre-change value, if applicable - `to_value` string, nullable — Post-change value, if applicable - `next_invoice_preview` NextInvoicePreview — The first invoice that will be issued under the new plan, fully precomputed. - `period_start` string, date-time — Period start of the next invoice - `period_end` string, date-time — Period end of the next invoice - `issue_at` string, date-time — When the next invoice will be issued (notification time) - `due_at` string, date-time — When the next invoice will be due - `subtotal` string — Subtotal before discounts - `discount_total` string — Sum of all discounts - `total_amount` string — Total amount payable - `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. - `beneficiaries` BeneficiaryLink[], nullable — Beneficiaries linked to this subscription - `beneficiary_id` string, uuid - `beneficiary_name` string - `fields` object — Catalog field values for this associated entity - `amount_in_smallest_unit` integer — Subscription amount in smallest currency unit (e.g. halala for SAR). - `original_amount_in_smallest_unit` integer — Original subscription amount (before discounts) 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)