---
title: "Create Invoice"
method: POST
path: "/api/v2/invoices"
tags: ["Invoices"]
---

# Create Invoice

`POST /api/v2/invoices`

Create a new invoice with items and payment details.

Important: For most use cases, use the Checkout/Payment Link API (`/v2/payment_links`) instead.
It generates a payment link that you can embed in your own web page or redirect to.

Use Cases:
- Create an invoice and manually mark it as paid for reference
- Automated invoice generation

## Request body

- InvoiceCreate — DTO for creating a new invoice. Multi-Currency Support: - The `currency` field is optional and defaults to 'SAR' for backward compatibility. - When a currency is specified, products must have a price in that currency. - If no ProductPrice exists for the currency, falls back to product.price (legacy).
  - `notify_consumer` boolean — Whether to send a notification to the consumer about the invoice
  - `description` string, nullable — Invoice description or notes
  - `items` InvoiceItemCreateDto[], required — List of products or services to include in the invoice
    - `product_id` string, uuid4, required — UUID of the product to include
    - `quantity` integer, required — Quantity of the product
    - `coupons` string[], nullable — List of coupon UUIDs to apply for discounts on this specific item
  - `payment_methods` InvoicePaymentMethodDto, required
    - `mada` boolean, required — Enable Mada payment method
    - `visa` boolean, required — Enable Visa payment method
    - `mastercard` boolean, required — Enable Mastercard payment method
    - `amex` boolean, required — Enable American Express payment method
    - `bank_transfer` boolean, required — Enable bank transfer payment method
    - `installment` boolean, required — Enable installment payment option
    - `qurrah` boolean — Enable Qurrah payment method
    - `bnpl` boolean — Enable BNPL (e.g. Tamara) for this invoice
  - `coupons` string[], nullable — List of coupon UUIDs to apply for discounts
  - `organization_consumer_id` string, uuid4, required — UUID of the consumer who will pay this invoice
  - `organization_consumer_beneficiaries` string[], nullable — UUID of the beneficiaries to the consumer who will pay this invoice
  - `scheduled_on` string, date-time, required — Payment due date. After this date, the invoice will be marked as overdue
  - `exclude_coupons_if_installments` boolean — If enabled, all coupons (invoice-level and item-level) will be excluded when the payer chooses installments. The payer will need to pay the full amount without discounts when paying by installments.
  - `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.

## Response `200`

Successful Response

- InvoiceDetailed
  - `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)
  - `invoice_number` integer — Global unique invoice number
  - `remaining_amount` string — Remaining amount to be paid
  - `paid_amount` string — Total amount already paid
  - `exclude_coupons_if_installments` boolean — Whether coupons are excluded when paying by installments
  - `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
  - `items` InvoiceItemDto[] — List of items included in the invoice
    - `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 item
    - `product_id` string, uuid4 — Unique identifier (UUID) of the product
    - `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
    - `quantity` integer — Quantity of the product in this invoice 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
    - `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.
    - `unit_price` string, nullable — Snapshotted unit price at invoice creation (for historical accuracy)
    - `product_price_id` string, uuid4, nullable — Reference to the ProductPrice used for this item (for traceability)
    - `original_amount_in_smallest_unit` integer — Original item amount in smallest currency unit.
    - `discounted_amount_in_smallest_unit` integer — Discounted item amount in smallest currency unit.
  - `branch` BranchDto
    - `id` string, uuid4 — Unique identifier (UUID) of the branch
    - `name` string — Name of the branch
  - `payments` PaymentDto[] — 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).
  - `subscription_id` string, uuid4, nullable — Unique identifier (UUID) of the subscription if this invoice is part of a subscription
  - `subscription` 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.
  - `payment_methods` InvoicePaymentMethodDto
    - `mada` boolean, required — Enable Mada payment method
    - `visa` boolean, required — Enable Visa payment method
    - `mastercard` boolean, required — Enable Mastercard payment method
    - `amex` boolean, required — Enable American Express payment method
    - `bank_transfer` boolean, required — Enable bank transfer payment method
    - `installment` boolean, required — Enable installment payment option
    - `qurrah` boolean — Enable Qurrah payment method
    - `bnpl` boolean — Enable BNPL (e.g. Tamara) for this invoice
  - `bnpl_eligibility` BnplEligibilityDto
    - `eligible` boolean
    - `provider_name` string
    - `message` string, nullable
  - `recurrence_pattern` 'Hour' | 'Day' | 'Week' | 'Fortnight' | 'Month' | 'Quarter' | 'Half-Year' | 'Year'
  - `parent_id` string, uuid4, nullable — Parent invoice ID for recurring invoices
  - `url` string — URL to access the invoice
  - `beneficiaries` BeneficiaryLink[], nullable — Beneficiaries linked to this invoice
    - `beneficiary_id` string, uuid
    - `beneficiary_name` string
    - `fields` object — Catalog field values for this associated entity
  - `adjustments` InvoiceAdjustmentDto[] — Credit, debit, and amendment history for this invoice
    - `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
    - `type` 'CREDIT' | 'DEBIT' | 'AMENDMENT'
    - `adjustment_reason` 'ERROR_IN_PRICING' | 'CHANGE_IN_PRODUCT_OR_SERVICE' | 'CHANGE_IN_TERM_AND_CONDITIONS' | 'OTHER'
    - `net_amount_change` string
    - `changed_by` 'USER'
    - `changed_by_user_id` string, uuid, nullable
    - `products` InvoiceAdjustmentProductDto[]
      - `side` 'OLD' | 'NEW'
      - `product_id` string, uuid
      - `quantity` integer
      - `coupons` InvoiceAdjustmentProductCouponDto[]
        - `coupon_id` string, uuid
        - `order` integer
    - `coupons` InvoiceAdjustmentCouponDto[]
      - `side` 'OLD' | 'NEW'
      - `coupon_id` string, uuid
      - `order` integer
  - `total_credited` string — Sum of credit adjustment amounts (absolute value of negative net changes)
  - `total_debited` string — Sum of debit adjustment amounts
  - `total_refunded` string — Sum of payment refunds on this invoice
  - `net_received` string — Sum of paid payment amounts minus total_refunded
  - `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 — Remaining amount in smallest currency unit.
  - `paid_amount_in_smallest_unit` integer — Paid amount in smallest currency unit.

## 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)