# Stream App API Documentation

> Complete API documentation and guides for Stream App

This file contains all documentation content in a single document following the llmstxt.org standard.

## Getting Started with Stream


Welcome to **Stream**, your partner for seamless and secure online payments.
This guide walks you through the essentials to integrate our **checkout experience** into your website or app.

The full payment flow:

> Your site → Stream Secure Checkout → Redirect to your success or failure page

## Overview: Integration Steps

1. [Authorization](#authorization)
1. [Create a Customer (Consumer)](#create-a-customer-consumer)
1. [Creating a Payment Link](#creating-a-payment-link)
1. [Handling Payment Redirects](#handling-payment-redirects)
1. [Retrieve Payment or Subscription Status](#retrieve-payment-or-subscription-status)

---

## Authorization

All API calls require authentication using your Stream API Key Pair (`api-key` + `api-secret`).

1. Navigate to Stream <FrontendUrl path="/settings/api-keys">API Settings</FrontendUrl>.
1. Click **Create Key Pair** and store the keys securely.

To authenticate your requests, encode your API key and secret as a Base64-encoded token. Use the following command (replace `api-key` and `api-secret` with your actual values):

```bash
echo -n 'api-key:api-secret' | base64
```

Include this Base64-encoded token in the `x-api-key` authentication header for all API requests:

```
x-api-key: <your-base64-token>
```

---

## Create a Customer (Consumer)

Before you can generate a payment link for a specific customer, you must first create a customer (consumer) record in Stream. This step registers the customer in your organization and returns a unique identifier that you'll use to tie payment links to that customer.

### Why Create a Customer First?

- **Personalized checkout**: When you attach a customer to a payment link, Stream skips the customer-details form during checkout because the customer's information is already known.
- **Customer tracking**: Every invoice, subscription, and payment is linked back to the customer record, making reconciliation straightforward.
- **Repeat billing**: For recurring products, the customer record is required to manage the subscription lifecycle.

### Step 1: Prepare the Customer Data

Decide which contact fields to include. The only **required** field is `name`. All other fields are optional but recommended for a complete integration.

| Field                     | Type       | Required | Description                                                                 |
| ------------------------- | ---------- | -------- | --------------------------------------------------------------------------- |
| `name`                    | string     | **Yes**  | Full name of the customer                                                   |
| `phone_number`            | string     | No       | Phone number (E.164 format, e.g., `+966501234567`)                          |
| `email`                   | string     | No       | Email address                                                               |
| `external_id`             | string     | No       | Your own system's ID for this customer (useful for cross-referencing)        |
| `iban`                    | string     | No       | IBAN (max 34 characters) for bank-related operations                        |
| `alias`                   | string     | No       | Short alias or display name                                                 |
| `comment`                 | string     | No       | Internal notes about the customer                                           |
| `preferred_language`      | string     | No       | Customer's preferred language for communications                            |
| `communication_methods`   | string[]   | No       | Preferred channels: `WHATSAPP`, `EMAIL`, `SMS` (can include multiple)       |

> **Tip**: Always include at least `phone_number` or `email` so Stream can send payment notifications to the customer.

### Step 2: Send the Create Request

- **Endpoint**: `POST /api/v2/consumers`
- **Auth**: `x-api-key: <base64(api-key:api-secret)>`

**cURL example:**

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/consumers \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmad Ali",
    "email": "ahmad@example.com",
    "phone_number": "+966501234567",
    "external_id": "cust_12345",
    "communication_methods": ["EMAIL", "SMS"]
  }'
```

### Step 3: Handle the Response

A successful response (`200 OK`) returns the full customer record. The most important field is `id` — this is the `organization_consumer_id` you'll use when creating payment links.

**Example response (simplified):**

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Ahmad Ali",
  "email": "ahmad@example.com",
  "phone_number": "+966501234567",
  "external_id": "cust_12345",
  "is_deleted": false,
  "created_at": "2025-06-15T10:30:00Z",
  "communication_methods": ["EMAIL", "SMS"],
  "preferred_language": "ar"
}
```

> See the full response schema in the [Create Consumer API Reference](/api/v2-consumers-create).

### Step 4: Handle Errors

If the request fails validation, the API returns a `422` status with an array of error details:

```json
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

Each object in the `detail` array contains `type` (error kind), `loc` (field path), and `msg` (human-readable message). Common error scenarios:

| `type` / Scenario | `loc` | `msg` (example) | Resolution |
| ------------------ | ----- | ---------------- | ---------- |
| `missing` | `["body", "name"]` | `"Field required"` | Include the required `name` field in the request body |
| `value_error` | `["body", "phone_number"]` | `"value is not a valid phone number"` | Use E.164 format: `+<country-code><number>` (e.g., `+966501234567`) |
| `value_error` | `["body", "email"]` | `"value is not a valid email address"` | Provide a properly formatted email address |

The API may also return a non-validation error with a top-level error code instead of a `detail` array. The most common one:

| Error Code | Cause | Resolution |
| ---------- | ----- | ---------- |
| `DUPLICATE_CONSUMER` | A consumer with the same phone number or email already exists | Use [Get All Consumers](/api/v2-consumers-list) to find the existing record and use its `id` instead |

> **Tip**: Always check for an existing consumer before creating a new one to avoid `DUPLICATE_CONSUMER` errors. You can list consumers with `GET /api/v2/consumers` or match by `external_id` in your own system.

### Step 5: Use the Customer ID in a Payment Link

Once you have the customer `id` from the response, pass it as `organization_consumer_id` when [creating a payment link](#creating-a-payment-link). This ties the payment to the specific customer and skips the customer-details step at checkout.

> **Note**: If you omit `organization_consumer_id`, the payment link will collect customer details during checkout and create a new customer record automatically. Use this approach for general-purpose links shared with multiple customers.

### Managing Existing Customers

After creating customers, you can manage them with these endpoints. The `{consumer_id}` path parameter is the `id` returned by `POST /api/v2/consumers` — the same value you pass as `organization_consumer_id` when creating payment links.

| Action     | Method   | Endpoint                             | API Reference                         |
| ---------- | -------- | ------------------------------------ | ------------------------------------- |
| List all   | `GET`    | `/api/v2/consumers`                  | [Get All Consumers](/api/v2-consumers-list)   |
| Get one    | `GET`    | `/api/v2/consumers/{consumer_id}`    | [Get Consumer](/api/v2-consumers-get)         |
| Delete     | `DELETE` | `/api/v2/consumers/{consumer_id}`    | [Delete Consumer](/api/v2-consumers-delete)   |

Before creating a new customer, you can check for an existing record by listing consumers or using your `external_id` to avoid duplicates.

---

## Creating a Payment Link

Create a checkout/payment link using the [Payment Link API](/api/v2-payment-links-create).

- **Endpoint**: `POST /api/v2/payment_links`
- **Auth**: `x-api-key: <base64(api-key:api-secret)>`

Payment links redirect customers to Stream's secure checkout page. They support two use cases:

1. **For multiple customers**: Create a general-purpose link that anyone can use. Each customer enters their information during checkout. Perfect for events, group purchases, or public product sales.

1. **For one specific customer**: Create a link tied to a specific customer by setting `organization_consumer_id`. The checkout page will skip the customer details collection step since the customer information is already known. Use this when charging a known customer.

When a customer pays through a payment link, the behavior depends on the product types you include:

- **One-time products**: When the payment link is paid, Stream creates an invoice with the products. The payment can be split into multiple installments, but the product itself is a one-time purchase (not recurring).

- **Recurring products**: When the payment link is paid, Stream creates a subscription (with recurring billing) and an initial invoice. The subscription will automatically generate invoices for future billing cycles based on the recurring interval.

> **Important**: You cannot mix one-time and recurring products in the same payment link. All products must be either one-time or all must be recurring.

### Strategy: Single Order with Both One-Time + Recurring Items

If a cart contains both one-time and recurring products, split it into **two payment links** and guide the customer through a short two-step checkout. This keeps each payment link valid while preserving a single “order” in your system.

**General approach**

- Create one link that contains only **one-time** items and a separate link that contains only **recurring** items.
- Treat both links as part of the same internal order (e.g., by storing a shared order reference in metadata or your database).
- Present the links sequentially (or based on your business preference) so the customer completes both steps.

- Confirm both outcomes via your normal status checks or webhooks before marking the order as complete.

> **Note**: You'll need existing products to create payment links. See the [Products API](/api/v2-products-create) for creating products. If you want to link a payment to a specific customer, you'll also need to create a customer first using the [Consumers API](/api/v2-consumers-create).

### Example: Payment Link for Multiple Customers

This example creates a payment link that can be used by multiple different customers. Each customer will enter their information when they visit the checkout page.

```json
{
  "name": "Event Registration",
  "description": "Annual conference registration",
  "items": [
    {
      "product_id": "your-product-uuid-here",
      "quantity": 1
    }
  ],
  "contact_information_type": "PHONE",
  "currency": "SAR",
  "max_number_of_payments": 100,
  "success_redirect_url": "https://example.com/success",
  "failure_redirect_url": "https://example.com/failure",
  "custom_metadata": {
    "event_id": "conf_2025",
    "campaign_source": "email_marketing"
  }
}
```

**Code snippet (general-purpose, one-time product):**

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/payment_links \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Event Registration",
    "description": "Annual conference registration",
    "items": [
      { "product_id": "your-product-uuid-here", "quantity": 1 }
    ],
    "contact_information_type": "PHONE",
    "currency": "SAR",
    "max_number_of_payments": 100,
    "success_redirect_url": "https://example.com/success",
    "failure_redirect_url": "https://example.com/failure"
  }'
```

> **Note**: `organization_consumer_id` is **not set**, so the link will collect customer information from each payer.

### Example: Payment Link for One Specific Customer

This example creates a payment link for a specific customer. When you specify `organization_consumer_id`, the checkout page will skip the customer details collection step since the customer information is already known.

```json
{
  "name": "Product Purchase",
  "description": "One-time payment for product order",
  "items": [
    {
      "product_id": "your-product-uuid-here",
      "quantity": 1
    }
  ],
  "contact_information_type": "PHONE",
  "currency": "SAR",
  "max_number_of_payments": 1,
  "organization_consumer_id": "your-customer-uuid-here",
  "success_redirect_url": "https://example.com/success",
  "failure_redirect_url": "https://example.com/failure",
  "custom_metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_789"
  }
}
```

> **Note**: `organization_consumer_id` **is set**, so the checkout page will skip the customer details collection step. The `max_number_of_payments` is typically set to `1` when targeting a specific customer.

### Example: Payment Link for a Recurring Product (New Subscription)

Use this when you want a customer to start a subscription from checkout. The product itself must be **recurring** (e.g., monthly), which is configured when you create the product via the [Products API](/api/v2-products-create). The payment link request is **the same endpoint** as one-time links:

- **Endpoint**: `POST /api/v2/payment_links`
- **Auth**: `x-api-key: <base64(api-key:api-secret)>`

When the customer completes payment, Stream automatically creates a **subscription** and an **initial invoice**. Future invoices are generated based on the product's recurring interval. You can retrieve the created subscription via the [Subscriptions API](/api/v2-subscriptions-list).

```json
{
  "name": "Premium Plan Subscription",
  "description": "Monthly recurring plan",
  "items": [
    {
      "product_id": "recurring-product-uuid-here",
      "quantity": 1
    }
  ],
  "contact_information_type": "EMAIL",
  "currency": "SAR",
  "max_number_of_payments": 1,
  "organization_consumer_id": "your-customer-uuid-here",
  "success_redirect_url": "https://example.com/success",
  "failure_redirect_url": "https://example.com/failure",
  "custom_metadata": {
    "plan": "premium_monthly",
    "source": "pricing_page"
  }
}
```

**cURL example:**

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/payment_links \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Plan Subscription",
    "description": "Monthly recurring plan",
    "items": [
      { "product_id": "recurring-product-uuid-here", "quantity": 1 }
    ],
    "contact_information_type": "EMAIL",
    "currency": "SAR",
    "max_number_of_payments": 1,
    "organization_consumer_id": "your-customer-uuid-here",
    "success_redirect_url": "https://example.com/success",
    "failure_redirect_url": "https://example.com/failure"
  }'
```

> **Notes**:
> - The recurring behavior is defined on the **product**, not the payment link.
> - Do not mix one-time and recurring products in the same payment link.
> - If `organization_consumer_id` is omitted, the checkout will collect customer details and the subscription will be created for that newly created customer.

### Response

The API returns a payment link object. The most important field is `url`, which you'll redirect customers to:

```json
{
  "url": "https://streampay.sa/s/...",
  "id": "payment-link-uuid",
  "status": "ACTIVE",
  "amount": "2500.00",
  "currency": "SAR"
}
```

> **Note**: This response has been simplified for brevity. The full response includes additional fields like `items`, `custom_metadata`, `success_redirect_url`, and more. See the [API Reference](/api/v2-payment-links-create) for the complete response schema.

Redirect your customer to the `url` field to complete the payment securely.

### Checkout Language

The checkout page language can be overridden using the `language`
query parameter on the payment link URL. By default, the checkout page is displayed to the customer in the language the organization is configured in.

Example:

```
https://streampay.sa/s/...?...&language=en
```

Or:

```
https://streampay.sa/s/...?language=en
```

Supported values:

| Value | Language |
| ------- | ---------- |
| `ar` | Arabic (default) |
| `en` | English |

> Note: This parameter only affects the hosted checkout page UI language. Data is not affected.

---

## Handling Payment Redirects

After checkout, Stream can redirect the customer to your `success_redirect_url` or `failure_redirect_url` (if provided) with payment information as query parameters. If you omit these URLs, Stream will show its hosted success/failure pages instead.

### Redirect URL Examples

**Success redirect:**

```
https://example.com/success?id=...&invoice_id=...&status=paid&message=APPROVED
```

**Failure redirect:**

```
https://example.com/failure?payment_link_id=...&id=...&status=failed&message=...
```

### Query Parameters

All redirects include these parameters:

| Parameter         | Description                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | Payment gateway payment ID - for internal use only. Useful for debugging when contacting support, but cannot be used in Stream APIs. Use `payment_id` or `invoice_id` instead. |
| `payment_link_id` | UUID of the payment link that was used                                                                                                                                         |
| `status`          | Payment status: `paid`, `pending`, `failed`, or `failed_internal_error`                                                                                                        |
| `message`         | Status message from the gateway (e.g., `APPROVED`, `DECLINED`, `The customer’s bank has declined.`)                                                                            |
| `login_method`    | Consumer's preferred login method: `PHONE` or `EMAIL`                                                                                                                          |

:::info

- **`status=failed`**: A definite rejection (e.g. insufficient funds, card declined). The payer should **retry** after addressing the issue.
- **`status=failed_internal_error`**: Transient or unclear failures (e.g. timeouts). The payer should **contact support**; money may or may not have been taken.

:::

**Additional parameters on success only:**

| Parameter                  | Description                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `invoice_id`               | UUID of the invoice created from the payment link                                                      |
| `consent_id`               | UUID of the payment consent/authorization                                                              |
| `payment_id`               | UUID of the payment record in Stream's system                                                          |
| `organization_consumer_id` | UUID of the customer who made the payment (newly created if not set when the payment link was created) |

> **Note**: On failure, the additional parameters above are not included since the payment did not complete successfully.

### Processing the Redirect

Parse the query parameters from the redirect URL on your server.

:::danger

**Important:** Always validate the payment server-side before accepting the order or completing any business action. Fetch the invoice using the `invoice_id` from the redirect with the [Invoice API](/api/v2-invoices-get), and verify its `status`, `amount`, and `currency` match your expectations. This server-side verification ensures the payment is legitimate before updating your system state. Never trust redirect parameters alone, always verify through our API.

:::

---

## Retrieve Payment or Subscription Status

Use the **Get Payment** and **Get Subscription** endpoints to fetch the latest status programmatically.

**Endpoints**

- **Payment status:** `GET /api/v2/payments/{payment_id}` → [Payments API](/api/v2-payments-get)
- **Subscription status:** `GET /api/v2/subscriptions/{subscription_id}` → [Subscriptions API](/api/v2-subscriptions-get)

**Authentication**

Use the same `x-api-key` header described in [Authorization](#authorization):

```
x-api-key: <base64(api-key:api-secret)>
```

### Example: Fetch Payment Status (cURL)

```bash
curl -X GET https://stream-app-service.streampay.sa/api/v2/payments/your-payment-id \
  -H "x-api-key: <your-base64-token>"
```

### Example: Fetch Subscription Status (cURL)

```bash
curl -X GET https://stream-app-service.streampay.sa/api/v2/subscriptions/your-subscription-id \
  -H "x-api-key: <your-base64-token>"
```

### Example: Fetch Status in JavaScript (Node.js)

```js
const API_BASE = "https://stream-app-service.streampay.sa/api/v2";
const API_KEY = process.env.STREAM_API_KEY_BASE64; // base64(api-key:api-secret)

async function getPaymentStatus(paymentId) {
  const res = await fetch(`${API_BASE}/payments/${paymentId}`, {
    headers: { "x-api-key": API_KEY }
  });
  if (!res.ok) throw new Error(`Payment fetch failed: ${res.status}`);
  const payment = await res.json();
  return payment.status;
}

async function getSubscriptionStatus(subscriptionId) {
  const res = await fetch(`${API_BASE}/subscriptions/${subscriptionId}`, {
    headers: { "x-api-key": API_KEY }
  });
  if (!res.ok) throw new Error(`Subscription fetch failed: ${res.status}`);
  const subscription = await res.json();
  return subscription.status;
}
```

> **Tip**: The `status` field in each response is the source of truth for the current state. See the full response schema in the linked API reference pages.

---

## Pagination & Filtering

# Pagination

Pagination helps you efficiently navigate, sort, and filter large collections of data without fetching everything at once.
This is especially useful for endpoints like:

- [List Payments](/api/v2-payments-list)
- [List Products](/api/v2-products-list)
- [List Invoices](/api/v2-invoices-list)
- [List Subscriptions](/api/v2-subscriptions-list)

# Filtering

Filtering is another way to efficiently navigate and filter large collections of data without fetching everything at once.

Whenever pagination is applied, then so is filtering.

Filtering allows you to filter your fetched objects through specific features or conditions like queries.

Whenever an endpoint may return many items, Stream uses a consistent pagination and filtering structure across all list responses.

---

# Request Parameters

## Pagination Parameters

You can control pagination using the following query parameters:

| Parameter        | Type   | Description                                                                 |
|------------------|--------|-----------------------------------------------------------------------------|
| `page`           | int    | Page number starting from **1**.                                            |
| `limit`          | int    | Number of items per page. Maximum: **100**.                                |
| `sort_field`     | string | Field used to sort the results.                                             |
| `sort_direction` | string | Either `"asc"` or `"desc"` depending on sorting direction.                  |

By default, `sort_field` is `created_at` and `sort_direction` is `desc`.

```
GET api/v2/products?page=1&limit=20&sort_field=created_at&sort_direction=desc
```

---

#Filtering allows you to query objects based on specific attributes. When you apply filters, the `pagination` metadata in the response will reflect the total count of items *matching* your filter, not the total database count.

| Parameter     | Type             | Description                                                                                       |
|---------------|------------------|---------------------------------------------------------------------------------------------------|
| `search_term` | `string`         | A generic query string. The API searches relevant fields (e.g., names, IDs, descriptions) for matches. |
| **Field Specific**| `string` / `array` | Specific attributes depending on the resource (e.g., `invoice_id`, `statuses`, `currency`).       |

**Note on Array Filters:**
Some parameters, like `statuses`, accept multiple values. In the query string, this appears as repeating keys:
`statuses=PENDING&statuses=PROCESSING`

For example, the [List Payments](/api/v2-payments-list) endpoint takes filtering queries like `invoice_id` and `statuses` to filter down the returned payments.

Example query:

```
GET api/v2/payments?page=1&limit=20&invoice_id=73b89d47-1bb1-443c-9a4c-f0ee23e22191&statuses=PENDING&statuses=PROCESSING
```

---

# Pagination Response Structure

Paginated responses include a `pagination` object that provides metadata about the current, previous, and next pages.

| Field              | Description                                                                 |
|--------------------|-----------------------------------------------------------------------------|
| `total_count`      | Number of objects returned in the current page.                             |
| `max_page`         | Maximum page number available.                                              |
| `current_page`     | Page you are currently on.                                                  |
| `limit`            | Page size (echoes your request, capped at 100).                             |
| `has_next_page`    | Whether another page exists after this one.                                 |
| `has_previous_page`| Whether a page exists before this one.                                      |

Example response snippet:

```
{
  "data": [...],
  "pagination": {
    "total_count": 20,
    "max_page": 12,
    "current_page": 1,
    "limit": 20,
    "has_next_page": true,
    "has_previous_page": false
  }
}
```

---

# Examples (Python)

Below are practical examples using Python's `requests` library.

## 1. Basic Pagination

Fetching the first page of results with a custom limit.

```python

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stream-app-service.streampay.sa/api/v2/products"

response = requests.get(
    BASE_URL,
    headers={"x-api-key": API_KEY},
    params={
        "page": 1,
        "limit": 20
    }
)

data = response.json()
print(f"Showing page {data['pagination']['current_page']} of {data['pagination']['max_page']}")
```

## 2. Global Search Filtering

Using the `search_term` to find items matching a specific string (e.g., a customer name or partial ID).

```python

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stream-app-service.streampay.sa/api/v2/customers"

response = requests.get(
    BASE_URL,
    headers={"x-api-key": API_KEY},
    params={
        "search_term": "JOHN DOE", # Searches for customer with that name
        "limit": 10
    }
)

results = response.json()["data"]
print(f"Found {len(results)} matches for 'Al-Faisaliah'")
```

## 3. Advanced Filtering (Lists & Specific Fields)

Filtering by a specific `invoice_id` and multiple `statuses`. Note how the list of statuses is passed to the `params` dictionary.

```python

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stream-app-service.streampay.sa/api/v2/payments"

# To filter by multiple statuses, pass them as a list
payload_filters = {
    "page": 1,
    "limit": 50,
    "invoice_id": "73b89d47-1bb1-443c-9a4c-f0ee23e22191",
    "statuses": ["PENDING", "PROCESSING"] # Requests handles this as statuses=PENDING&statuses=PROCESSING
}

response = requests.get(
    BASE_URL,
    headers={"x-api-key": API_KEY},
    params=payload_filters
)

payments = response.json()["data"]
for p in payments:
    print(f"Payment ID: {p['id']} | Status: {p['status']}")
```

## 4. Iterating Through All Pages

A robust pattern to fetch every item available.

```python

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stream-app-service.streampay.sa/api/v2/products"

page = 1
all_products = []

while True:
    response = requests.get(
        BASE_URL,
                headers={"x-api-key": API_KEY},
        params={"page": page, "limit": 100} # Maximize limit to reduce requests
    )

    body = response.json()
    all_products.extend(body["data"])

    # Stop if there are no more pages
    if not body["pagination"]["has_next_page"]:
        break

    page += 1

print(f"Successfully fetched {len(all_products)} products.")
```

---

---

## Webhooks


Webhooks allow your platform to receive real-time notifications from Stream when key events occur—such as payment successes, failures, or cancellations. This enables you to react to events programmatically, such as updating your database, sending notifications, or triggering internal workflows.

Stream's webhook infrastructure is designed for reliability and includes features like:

- Event-specific subscriptions
- Secure payload signing
- Delivery tracking for observability
- Automatic retries using exponential backoff

## Creating a Webhook

To create or manage your webhooks, go to <FrontendUrl path="/settings/webhooks">Webhook Settings</FrontendUrl>.

There you can:
- Register a new webhook endpoint
- Select which event types you want to subscribe to
- Enable, disable, or delete webhooks

## Webhook Flow Logic

Understanding which webhooks are sent in different scenarios:

### Single Payment Succeeds

When a single payment succeeds:

1. `PAYMENT_SUCCEEDED` webhook is sent (one per payment)
2. If the payment completes the invoice (all payments are now paid), `INVOICE_COMPLETED` webhook is also sent

Example: Invoice with 1 payment of 1000 SAR
- Payment succeeds → `PAYMENT_SUCCEEDED` webhook
- Invoice completes → `INVOICE_COMPLETED` webhook

### Multiple Payments Succeed (Installments)

When multiple payments succeed together (e.g., installments):

1. `PAYMENT_SUCCEEDED` webhook is sent for each payment that succeeded (one per payment)
2. If all payments complete the invoice, `INVOICE_COMPLETED` webhook is also sent

Example: Invoice with 3 payments of 1000 SAR each
- Payments 1, 2, 3 all succeed together:
  - `PAYMENT_SUCCEEDED` webhook for payment_1
  - `PAYMENT_SUCCEEDED` webhook for payment_2
  - `PAYMENT_SUCCEEDED` webhook for payment_3
  - `INVOICE_COMPLETED` webhook

Example: Invoice with 5 payments, payments 1-3 succeed together:
- `PAYMENT_SUCCEEDED` webhook for payment_1
- `PAYMENT_SUCCEEDED` webhook for payment_2
- `PAYMENT_SUCCEEDED` webhook for payment_3
- No `INVOICE_COMPLETED` webhook (invoice not yet fully paid)

### Payment Fails

When a payment fails:

1. `PAYMENT_FAILED` webhook is sent
2. No invoice completion webhook is sent

### Payment Refunded

When a payment is refunded:

1. `PAYMENT_REFUNDED` webhook is sent
2. Invoice status does not change (invoice remains completed)

### Payment Marked as Paid

When a payment is manually marked as paid:

1. `PAYMENT_MARKED_AS_PAID` webhook is sent
2. If this completes the invoice, `INVOICE_COMPLETED` webhook is also sent

### Subscription Renewal

When a subscription cycle renews:

1. New invoice created → `INVOICE_CREATED` webhook
2. Payment succeeds → `PAYMENT_SUCCEEDED` webhook
3. Invoice completes → `INVOICE_COMPLETED` webhook

**Note:** For subscription renewals, the `INVOICE_COMPLETED` webhook indicates that the subscription cycle has been renewed successfully. The invoice will have a `subscription_id` in its payload, and you can check if it's a renewal invoice by comparing it with previous invoices for that subscription.

## Event Types

### Payment Events

- `PAYMENT_SUCCEEDED` - Payment completed successfully
- `PAYMENT_FAILED` - Payment attempt failed
- `PAYMENT_CANCELED` - Payment was canceled
- `PAYMENT_REFUNDED` - Payment was refunded
- `PAYMENT_MARKED_AS_PAID` - Payment was manually marked as paid

### Invoice Events

- `INVOICE_CREATED` - New invoice created
- `INVOICE_SENT` - Invoice sent to consumer
- `INVOICE_ACCEPTED` - Invoice accepted by consumer
- `INVOICE_REJECTED` - Invoice rejected by consumer
- `INVOICE_COMPLETED` - Invoice completed (all payments done)
- `INVOICE_CANCELED` - Invoice canceled
- `INVOICE_UPDATED` - Invoice details updated

### Subscription Events

- `SUBSCRIPTION_CREATED` - New subscription created
- `SUBSCRIPTION_ACTIVATED` - Subscription activated
- `SUBSCRIPTION_INACTIVATED` - Subscription deactivated
- `SUBSCRIPTION_CANCELED` - Subscription canceled
- `SUBSCRIPTION_FROZEN` - Subscription frozen
- `SUBSCRIPTION_CYCLE_RENEWAL_FAILED` - Subscription cycle renewal failed (use `INVOICE_COMPLETED` with `subscription_id` for successful renewals)
- `SUBSCRIPTION_CANCEL_AT_PERIOD_END` - Subscription scheduled to cancel at period end
- `SUBSCRIPTION_FREEZE_NOW` - Subscription frozen immediately
- `SUBSCRIPTION_UNFREEZE_NOW` - Subscription unfrozen immediately
- `SUBSCRIPTION_UNFREEZE_FUTURE` - Subscription scheduled to unfreeze in future
- `SUBSCRIPTION_FREEZE_CANCEL` - Subscription freeze canceled
- `SUBSCRIPTION_PLAN_CHANGE_SCHEDULED` - A plan change was scheduled to take effect at `current_period_end`.
- `SUBSCRIPTION_PLAN_CHANGE_CANCELED` - A previously scheduled plan change was canceled before it took effect.
- `SUBSCRIPTION_PLAN_CHANGED` - The scheduled plan change was actually applied — items, coupons, interval, and amount are now live on the subscription.
- `SUBSCRIPTION_PLAN_CHANGE_INVOICE_REISSUED` - While scheduling a plan change, an existing prepared next-cycle invoice was canceled and regenerated from the new target plan. This is triggered alongside `SUBSCRIPTION_PLAN_CHANGE_SCHEDULED` if it affects the plan's invoice.
- `SUBSCRIPTION_PLAN_UPDATED` - Subscription plan change was applied immediately. This applies for changing seats, adding add-ons, and changing number of subscription cycles.

### Payment Link Events

- `PAYMENT_LINK_PAY_ATTEMPT_FAILED` - Payment attempt failed for a payment link

  **Note:** This webhook is sent when a payment link payment fails. Unlike regular payment failures, no invoice, payment, or subscription entities are created on failure, so `PAYMENT_FAILED` webhook cannot be sent. This event exists specifically to notify about payment link failures when no entities exist.

## Webhook Payload

The webhook POST request will have a JSON body like:

```json
{
  "event_type": "PAYMENT_SUCCEEDED",
  "entity_type": "PAYMENT",
  "entity_id": "uuid",
  "entity_url": "<https://stream-app-service.streampay.sa/api/v2/payments/{id}>",
  "status": "SUCCEEDED",
  "data": { /* payment or event-specific data */ },
  "timestamp": "2025-07-15T14:41:21.705Z"
}

```

## Webhook Payload Example

```json
{
  "data": {
    "invoice": {
      "id": "2df0f7e0-2634-46ab-829a-bfcb0a797d87",
      "url": "https://stream-app-service.streampay.sa/api/v2/invoices/2df0f7e0-2634-46ab-829a-bfcb0a797d87"
    },
    "payment": {
      "id": "e2182d3d-b4cf-4972-bcc0-ec6d963c066d",
      "url": "https://stream-app-service.streampay.sa/api/v2/payments/e2182d3d-b4cf-4972-bcc0-ec6d963c066d"
    },
    "payment_link": {
      "id": "6361941e-3a81-4aa5-aaa6-60d6e052883a",
      "url": "https://stream-app-service.streampay.sa/api/v2/payment_links/6361941e-3a81-4aa5-aaa6-60d6e052883a"
    },
    "metadata": {
      "customer_id": "cust_12345",
      "nested_data": {
        "sub_field": "sub_value",
        "sub_number": 678
      },
      "affiliate_id": "aff_987",
      "custom_field_1": "value_1",
      "custom_field_2": 12345,
      "campaign_source": "email_marketing"
    }
  },
  "status": "SUCCEEDED",
  "entity_id": "e2182d3d-b4cf-4972-bcc0-ec6d963c066d",
  "timestamp": "2025-07-22T14:40:31.485576",
  "entity_url": "https://stream-app-service.streampay.sa/api/v2/payments/e2182d3d-b4cf-4972-bcc0-ec6d963c066d",
  "event_type": "PAYMENT_SUCCEEDED",
  "entity_type": "PAYMENT"
}
```

## Webhook Request Headers

- `Content-Type: application/json`
- `User-Agent: StreamApp-Webhook/1.0`
- `X-Webhook-Event`: Event type (e.g., `PAYMENT_SUCCEEDED`)
- `X-Webhook-Entity-Type`: Entity type (e.g., `PAYMENT`)
- `X-Webhook-Entity-ID`: Entity UUID
- `X-Webhook-Signature`:
Format: `t={timestamp},v1={signature}`
    - `timestamp` is the UNIX timestamp when the signature was generated.
    - `signature` is an HMAC-SHA256 of `{timestamp}.{payload}` using your webhook’s `secret_key`.
- `X-Webhook-Timestamp`: The timestamp used in the signature.

## Verifying Webhook Authenticity

:::warning

Always verify the `X-Webhook-Signature` before treating a webhook as authentic or updating your system (fulfillment, access, financial state). Reject requests with a missing or invalid signature. Unsigned or unverified payloads could be forged; never trust the JSON body alone.

:::

To verify a webhook:

1. Extract the `X-Webhook-Signature` header and split into timestamp and signature.
2. Compute the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using your webhook’s `secret_key`.
3. Compare your computed signature to the value in the header.

Example (Python):

```python

def verify_webhook_signature(secret: str, raw_body: bytes, signature_header: str):
    # signature_header: "t=TIMESTAMP,v1=SIGNATURE"
    parts = dict(x.split('=') for x in signature_header.split(','))
    timestamp = parts['t']
    signature = parts['v1']
    message = f"{timestamp}.{raw_body.decode()}"
    computed = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, signature)

```

## Webhook Delivery & Retry Logic

- Delivery Attempts:

    Every webhook event triggers a delivery record. Each delivery attempt and its status (pending, delivered, failed, retrying) is tracked for auditing.

- Retry Schedule:

    If your endpoint does not respond with a 2xx status, Stream will retry delivery up to 5 times.

    The default retry delays (in minutes) are:

    1. 1st retry: 5 minutes after the first failure
    2. 2nd retry: 30 minutes after the second failure
    3. 3rd retry: 2 hours (120 minutes) after the third failure
    4. 4th retry: 6 hours (360 minutes) after the fourth failure
    5. 5th retry: 12 hours (720 minutes) after the fifth failure

    After the fifth attempt, if delivery is still unsuccessful, the webhook delivery is marked as failed and no further attempts will be made.

- Auditing:

    All delivery attempts, responses, and errors are logged and can be audited.

---

## Testing Cards

## Testing Environment

In order to test your application without having to go live with cards and accounts, you can use [Moyasar's testing cards](https://docs.moyasar.com/guides/card-payments/test-cards/)) to simulate different transaction outcomes.

The test cards should be used in a sandbox environment. This is also applicable if you are using the Stream's UI in sandbox mode and want to test the flow without having to use actual cards.

## Required Card Fields

Below are the values that need to be entered for the non-card number fields when testing:

| Field | Value |
| :--- | :--- |
| **Name** | Any name made of two words separated by a space (e.g., John Doe) |
| **Year** | Any **future** year |
| **Month** | Any month (or a future month if using the current year) |
| **CVC** | Any 3 digits (4 digits for American Express (AMEX)) |

---

## List of Test Cards and Expected Outcomes

Below is the list of test card numbers you can use in your test environment to simulate specific transaction statuses (Success/Failure) according to the card network.

### Mada

| Card Number | Status | Message | Response Code | 3DS Note |
| :--- | :--- | :--- | :--- | :--- |
| `4201320111111010` | **paid** | APPROVED | 00 | ---- |
| `4201320000013020` | **failed** | UNSPECIFIED FAILURE | 99 | ---- |
| `4201320000311101` | **failed** | INSUFFICIENT FUNDS | 51 | ---- |
| `4201320131000508` | **failed** | DECLINED: LOST CARD | 41 | ---- |
| `4201321234411220` | **failed** | DECLINED | 05 | ---- |
| `4201322267774310` | **failed** | DECLINED: EXPIRED CARD | 54 | ---- |
| `4201326324640570` | **failed** | DECLINED: EXCEEDS WITHDRAWAL LIMIT | 61 | ---- |
| `4201321144311528` | **failed** | DECLINED: STOLEN CARD | 43 | ---- |

### Visa

| Card Number | Status | Message | Response Code | 3DS Note |
| :--- | :--- | :--- | :--- | :--- |
| `4111114005765430` | **paid** | APPROVED | 00 | Frictionless Authentication |
| `4111111111111111` | **paid** | APPROVED | 00 | ---- |
| `4123120000000000` | **failed** | UNSPECIFIED FAILURE | 99 | ---- |
| `4123120001090000` | **failed** | INSUFFICIENT FUNDS | 51 | ---- |
| `4123450131000508` | **failed** | DECLINED: LOST CARD | 41 | ---- |
| `4123120001090109` | **failed** | DECLINED | 05 | ---- |
| `4123128518640738` | **failed** | DECLINED: EXPIRED CARD | 54 | ---- |
| `4123123033308648` | **failed** | DECLINED: EXCEEDS WITHDRAWAL LIMIT | 61 | ---- |
| `4123125276780003` | **failed** | DECLINED: STOLEN CARD | 43 | ---- |
| `4111118250252531` | **failed** | 3DS: attempted but not available, please ensure that you have enabled Online Purchase from your bank portal. | ---- | ECI 06 |
| `4111113343111067` | **failed** | 3DS service error occurred. | ---- | 3DS fails during enrollement check |
| `4111116611600661` | **failed** | The card is not enrolled in 3DS service. | ---- | ---- |
| `4111112205628150` | **failed** | 3DS service error occurred. | ---- | 3DS fails during authentication attempt |
| `4111115784228433` | **failed** | The authentication attempt was rejected by the issuer bank. | ---- | ---- |
| `4111115620358287` | **failed** | The authentication is unavailable, please try again later or contact issuer bank if problem persisted. | ---- | ---- |

### Mastercard

| Card Number | Status | Message | Response Code | 3DS Note |
| :--- | :--- | :--- | :--- | :--- |
| `5421080101000000` | **paid** | APPROVED | 00 | ---- |
| `5105105105105100` | **failed** | UNSPECIFIED FAILURE | 99 | ---- |
| `5457210001000092` | **failed** | INSUFFICIENT FUNDS | 51 | ---- |
| `5204010101000000` | **failed** | DECLINED: LOST CARD | 41 | ---- |
| `5204730000002514` | **failed** | DECLINED | 05 | ---- |
| `5105107550274126` | **failed** | DECLINED: EXPIRED CARD | 54 | ---- |
| `5105106475101067` | **failed** | DECLINED: EXCEEDS WITHDRAWAL LIMIT | 61 | ---- |
| `5105107304607225` | **failed** | DECLINED: STOLEN CARD | 43 | ---- |

### American Express (AMEX)

| Card Number | Status | Message | Response Code | 3DS Note |
| :--- | :--- | :--- | :--- | :--- |
| `340000000900000` | **paid** | APPROVED | 00 | ---- |
| `371111111111114` | **failed** | UNSPECIFIED FAILURE | 99 | ---- |
| `340033000000000` | **failed** | INSUFFICIENT FUNDS | 51 | ---- |
| `340012340501000` | **failed** | DECLINED: LOST CARD | 41 | ---- |
| `340033000000133` | **failed** | DECLINED | 05 | ---- |
| `340000018441278` | **failed** | DECLINED: EXPIRED CARD | 54 | ---- |
| `340000753060788` | **failed** | DECLINED: EXCEEDS WITHDRAWAL LIMIT | 61 | ---- |
| `340000418501838` | **failed** | DECLINED: STOLEN CARD | 43 | ---- |

---

## Testing Apple Pay

Unlike card payments where specific test card numbers are used, testing **Apple Pay** payments in the Stream's sandbox environment is based on the **amount** sent to the API (according to [Moyassar](https://docs.moyasar.com/guides/apple-pay/testing/)).

A **real card** must be added to an Apple Pay Wallet to test the process, but you must be using the sandbox environment to ensure no actual payment is made.

The following amounts will simulate different payment outcomes:

| Amount (Minor Unit) | Amount (SAR) | Status | Message | Response Code |
| :--- | :--- | :--- | :--- | :--- |
| `20000` to `30000` | `200.00` to `300.00` | **paid** | APPROVED | 00 |
| `100000` to `110000` | `1000.00` to `1100.00` | **failed** | UNSPECIFIED FAILURE | 99 |
| `110100` to `120000` | `1101.00` to `1200.00` | **failed** | INSUFFICIENT FUNDS | 51 |
| `120100` to `130000` | `1201.00` to `1300.00` | **failed** | DECLINED: LOST CARD | 41 |
| `130100` to `140000` | `1301.00` to `1400.00` | **failed** | DECLINED | 05 |
| `140100` to `150000` | `1401.00` to `1500.00` | **failed** | DECLINED: EXPIRED CARD | 54 |
| `150100` to `160000` | `1501.00` to `1600.00` | **failed** | DECLINED: EXCEEDS WITHDRAWAL LIMIT | 61 |
| `160100` to `170000` | `1601.00` to `1700.00` | **failed** | DECLINED: STOLEN CARD | 43 |

> **Note:** Moyasar accepts the payment amount in the **minor currency unit** (e.g., cents), and the test environment uses this amount to return different results.
---
> **Tip:** Using any other amount range than the stated above will result in the payment failing.

---

## Installments


Installments allow customers to split a payment into multiple smaller payments over time. Customers can choose from available installment options (2, 3, or 4 installments) when paying an invoice or payment link.

> Note: Installments are only available for one-time products. They are automatically disabled for recurring products (subscriptions).

---

## How Installments Work

When a customer selects an installment option, Stream automatically calculates the amount for each installment and schedules them based on the split period. Each installment becomes a separate payment with its own due date.

![Customer selecting installment split option](/img/installment-split-selection.png)

**Example:** 1,000 SAR split into 3 monthly installments:
- Installment 1: 333.33 SAR (due on payment date)
- Installment 2: 333.33 SAR (due 1 month later)
- Installment 3: 333.34 SAR (due 2 months later)

---

## How Installment Amounts Are Calculated

Installment amounts are calculated by dividing the total payment by the number of installments. If the amount doesn't divide evenly, any rounding difference is added to the last installment to ensure the total always equals the original payment amount.

For example, 999.98 SAR split into 3 installments results in: 333.33 SAR, 333.33 SAR, and 333.32 SAR (the last installment is reduced by 0.01 SAR to account for the rounding difference).

> Note: The total of all installments always equals the original payment amount.

---

## Configuration

Configure installment settings in your <FrontendUrl path="/settings/payment-settings">Payment Settings</FrontendUrl>. Invoice and payment link settings are configured separately.

### Enable/Disable Installments

#### API (Payment Links)

When creating a payment link via the [Payment Links API](/api/v2-payment-links-create), you can enable or disable installments by including the `payment_methods` parameter in your request. Set `installment: true` to enable installments or `installment: false` to disable them for that specific payment link.

This setting overrides the organization's default payment link installment settings. If you don't include the `payment_methods` parameter, the organization's default settings will be used.

#### Settings Page

You can configure the default installment settings in your <FrontendUrl path="/settings/payment-settings">Payment Settings</FrontendUrl>:
- **For invoices**: Enable or disable installments in the invoice payment options (invoices can only be created from the UI)
- **For payment links**: Enable or disable installments in the payment link payment options (these defaults apply when creating payment links via the UI or when the API request doesn't specify `payment_methods`)

### Split Options

Configure which numbers of installments (2, 3, or 4) are available for customers to choose from.

Default split options:
- 2 installments, monthly
- 3 installments, monthly
- 4 installments, monthly

The split period (the interval between installments, e.g., monthly, quarterly, yearly) cannot be changed through the API or dashboard. Contact Stream support to modify the split period.

### Minimum Amount

The minimum installment amount is 100 SAR per installment. If the payment amount divided by the number of installments is less than 100 SAR, that installment option will not be available.

For example, with a payment of 250 SAR:
- 2 installments: 125 SAR each ✅ (available)
- 3 installments: 83.33 SAR each ❌ (not available, below minimum)

The minimum amount cannot be changed through the API or dashboard. Contact Stream support to modify this value.

---

## Authentication


Learn how to authenticate your API requests to the Stream platform.

## Overview

All API calls to Stream require authentication using your API Key Pair. Stream uses a simple but secure authentication method where you encode your credentials and include them in every request.

## Getting Your API Keys

1. Log in to your Stream dashboard
2. Navigate to <FrontendUrl path="/settings/api-keys">API Settings</FrontendUrl>
3. Click **Create Key Pair**
4. Store your `api-key` and `api-secret` securely
5. Copy `x-api-key` to use in the APIs or you can gernerate later

:::warning Important
Your API secret should be kept secure and never exposed in client-side code or public repositories. Treat it like a password.
:::

## Authentication Methods

Stream uses HTTP Basic Authentication with Base64 encoding of your API credentials.

Encode your API key and secret as a Base64-encoded token:

```bash
echo -n 'api-key:api-secret' | base64
```

**Example:**

```bash
echo -n '038cb769-9ce3-49da-9d52-17fd49bf07e8:6ea68e79-8756-4be8-9bd2-307314e8d12c' | base64
# Output: MDM4Y2I3NjktOWNlMy00OWRhLTlkNTItMTdmZDQ5YmYwN2U4OjZlYTY4ZTc5LTg3NTYtNGJlOC05YmQyLTMwNzMxNGU4ZDEyYw==
```

#### Using the Token

Include the Base64-encoded token in the `x-api-key` header for all API requests:

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/payment_links \
  -H "x-api-key: MDM4Y2I3NjktOWNlMy00OWRhLTlkNTItMTdmZDQ5YmYwN2U4OjZlYTY4ZTc5LTg3NTYtNGJlOC05YmQyLTMwNzMxNGU4ZDEyYw==" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Payment",
    "amount": 100.00
  }'
```

### Using SDKs

When using Stream SDKs, authentication is handled automatically. Simply provide your `x-api-key` during initialization:

#### TypeScript SDK

```typescript

const client = StreamSDK.init(process.env.STREAM_API_KEY!);
```

#### Express SDK

```typescript

app.get(
  "/checkout",
  Checkout({
    apiKey: process.env.STREAM_API_KEY!,
    // ... other config
  })
);
```

---

## Branches in the API


API requests are always scoped to a single branch. When creating an API key, you specify which branches it can access. For each request, you can select the target branch, which determines where resources are created and accessed.

## Creating API Keys with Branch Access

When creating an API key, you can specify:

- Branches: List of specific branches the API key can access
- Default Branch: Default branch used when `x-branch-id` header is not provided
- Is All Branches: If `true`, the API key has access to all branches, present and future

## Selecting a Branch in API Requests

Include the `x-branch-id` header to specify which branch to use for that request:

```bash
curl -X GET https://stream-app-service.streampay.sa/api/v2/user \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-branch-id: branch-uuid-here"
```

If `x-branch-id` is omitted, the API key's `default_branch_id` is used.

## Branch Access Validation

The API key must have access to the branch specified in `x-branch-id`:
- If `is_all_branches=true`: Access to all organization branches
- Otherwise: Only branches listed in `branch_ids`

Requests to unauthorized branches return a 4xx error.

---

## Embedded Checkout


Render a payment link checkout in-page with the Stream Embed SDK. Create a payment link via the API first, then pass the response **`url`** into `paymentLink`. Details on creating links (products, consumers, redirects): [Creating a Payment Link](/#creating-a-payment-link).

## Prerequisites

- Same setup as payment-link creation: API key pair, and at least one product ID. See [Creating a Payment Link](/#creating-a-payment-link).

- For using Apple Pay through our embedded checkouts, the following steps need to be done:
  - Get the text file from `https://streampay.sa/.well-known/apple-developer-merchantid-domain-association`
  -  Host the same exact text file under your domain through this path: `.well-known/apple-developer-merchantid-domain-association`
  - Reach out to support team on available communication methods to register you in the PGW system.

## Example

### 1. Create a payment link

`POST /api/v2/payment_links` returns an object whose **`url`** field is what you embed (same value you would redirect to).

```bash
curl -s -X POST https://stream-app-service.streampay.sa/api/v2/payment_links \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout",
    "items": [{ "product_id": "your-product-uuid-here", "quantity": 1 }],
    "contact_information_type": "PHONE",
    "currency": "SAR",
    "max_number_of_payments": 100
  }'
```

Example response (trimmed):

```json
{
  "url": "https://streampay.sa/ds/..."
}
```

Use that `url` as `paymentLink` in the next step. Build the request body you need (customer-specific links, metadata, redirect URLs, subscriptions, etc.) using the guide and [Create payment link](https://docs.streampay.sa/api/v2-payment-links-create).

### 2. Embed checkout

Load the default SDK, mount a container, call `Stream.Checkout` with the **`url`** from step 1. Inject the URL from your server—do not create payment links or expose API keys in frontend-only code.

```html
<script src="https://stream-embed.streampay.sa/sdk/embed.min.js"></script>

<script>
  Stream.Checkout({
    paymentLink: "https://streampay.sa/ds/XXXXXX", # the URL should be the created payment link URL
    container: "#stream-checkout",
  });
</script>
```

## Options

| Option | Type | Required | Description |
| ------ | ---- | -------- | ----------- |
| `paymentLink` | `string` | **Yes** | Full payment-link URL from the API (`url` field) or short ID Stream accepts |
| `container` | `string` \| `Element` | **Yes** | CSS selector or DOM element for the iframe |
| `minHeightPx` | `number` | No | Min iframe height (default **280**) |
| `maxHeightPx` | `number` | No | Max iframe height (default **920**) |
| `vhCapPx` | `number` | No | Viewport-relative height cap (default **800**) |
| `vhFraction` | `number` | No | Viewport fraction for fluid height (default **0.7**) |

## See also

- [Webhooks](/webhooks) — confirm payment server-side  
- [Public API reference](https://docs.streampay.sa/)

---

## Stream API Errors


This page documents the error response format and the standardized error codes returned by Stream API endpoints. The goal is to provide a stable, predictable contract for client applications and integrators.

## Error response envelope

All handled errors return a response body using the `StreamBaseResponse` envelope:

```json
{
  "error": {
    "code": "STREAM_ERROR",
    "message": "Something wrong happened, please contact support.",
    "additional_info": "Optional human-readable details"
  }
}
```

- `code`: A stable error code from `StreamErrorCodes`.
- `message`: A user‑facing message associated with the code.
- `additional_info`: Optional, best‑effort details to aid debugging.

## Common error classes and HTTP status codes

The following exception classes map to consistent HTTP status codes:

| Exception class | HTTP status |
| --- | --- |
| `BadRequestError` | 400 |
| `UnauthorizedError` | 401 |
| `ForbiddenError` | 403 |
| `PermissionForbiddenError` | 403 |
| `NotFoundError` | 404 |
| `GoneError` | 410 |
| `UnprocessableEntityError` | 422 |
| `DuplicateValueError` | 422 |

## Stream error codes

The following codes are used across all Stream API endpoints:

| Code | Message |
| --- | --- |
| `STREAM_ERROR` | Something wrong happened, please contact support. |
| `STREAM_UNKNOWN_ERROR` | Unknown exception happened; this exception will be handled as soon as possible. |
| `PHONE_ALREADY_REGISTERED` | Phone is already registered. |
| `INVALID_PARAMETERS` | Request input is not valid. |
| `INVOICE_FINALISED` | Invoice is finalised and cannot undergo this action. |
| `PAYMENT_REFUNDED_ALREADY` | Duplicate action; payment has already been refunded. |
| `PAYMENT_REFUNDED_FAILED` | Could not refund payment; processor failed. |
| `DUPLICATE_CONSUMER` | Consumer already exists. |
| `DUPLICATE_PAYMENT` | A payment with the given information already exists. |
| `PERMISSION_FORBIDDEN` | Permission forbidden. |
| `PRODUCT_USED_IN_FINALIZED_INVOICE` | Product cannot be updated; it is used by a finalized invoice. |
| `COUPON_USED_IN_FINALIZED_INVOICE` | Coupon cannot be updated; it is used by a finalized invoice. |

---

## Handling Your Own Notifications


This guide explains how to handle your own organization consumer notifications by disabling default notifications and using webhooks for event-based notifications or list APIs for scheduled notifications.

## Overview

By default, Stream sends notifications to your organization consumers (customers) for various events like payment confirmations, invoice updates, and subscription changes. If you want to handle these notifications yourself, you can:

1. Disable default org_consumer notifications - Contact support to enable the blocking setting
2. Subscribe to webhook events - For immediate, event-based notifications
3. Use list APIs - For scheduled notifications (reminders, overdue notices, etc.)

---

## Step 1: Disable Default Org Consumer Notifications

**Important:** Before disabling default notifications, you must contact our support team to disable default notifications for your organization. This prevents all default notifications from being sent to your organization consumers.

Once enabled, you can manage notifications through webhooks and list APIs as described below.

---

## Step 2: Subscribe to Webhook Events

For event-based notifications (immediate actions like payment succeeded, invoice accepted, etc.), subscribe to webhook events.

To create or manage your webhooks, go to <FrontendUrl path="/settings/webhooks">Webhook Settings</FrontendUrl> and subscribe to the relevant event types.

For a complete list of available webhook events, payload structure, verification, and delivery details, see the [Webhooks Guide](/webhooks).

---

## Step 3: Use List APIs for Scheduled Notifications

For scheduled notifications (time-based reminders like payment due, overdue, etc.), use list APIs with appropriate filters to query for items that need notifications. For example, use the [List Payments API](/api/v2-payments-list), [List Invoices API](/api/v2-invoices-list), or [List Subscriptions API](/api/v2-subscriptions-list).

---

## Stream MCP Server


MCP (Model Context Protocol) is a standard way for AI clients to call tools and read resources from external systems.

The Stream MCP Server exposes Stream operations (payments, invoices, customers, products, etc.) as MCP tools so clients like Claude Desktop, Cursor, and VS Code can use them directly.

**Resources vs tools:** MCP **resources** (such as the OpenAPI documentation) do not require a Stream API key. **Tools** that call the Stream API—payments, customers, invoices, products, coupons, and the rest, **do** require a valid key in your client configuration.

## Main Feature: API Documentation Integration

The primary feature of this MCP server is direct integration with Stream API documentation.

- It exposes the full OpenAPI spec as an MCP resource.
- AI clients can read the latest API schema and stay aligned with current endpoints.
- This improves tool accuracy for request fields, validation, and endpoint usage.

## Hosted endpoint

Stream hosts the MCP server at:

`https://mcp.streampay.sa/mcp`

Configure your client to use this URL. Include `Authorization` when you use tools that hit the Stream API; you can omit it if you only read documentation resources.

---

## Client configuration (Claude Desktop / Cursor / VS Code)

Add this to your MCP config file (`claude_desktop_config.json` or `mcp.json`). Use the `headers` block whenever you rely on tools that require the Stream API (omit it for resources-only use, such as the OpenAPI spec).

```jsonc
{
  "mcpServers": {
    "stream": {
      "url": "https://mcp.streampay.sa/mcp",
      "headers": {
        // Required for operational tools (payments, customers, etc.); omit if you only read docs resources (e.g. OpenAPI).
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}
```

---

## Available Tools

### Payment Links

| Tool | Description |
|---|---|
| `create_payment_link` | Create a new checkout / payment link |
| `list_payment_links` | Paginated list with optional status filter |
| `get_payment_link` | Get a single payment link by ID |
| `deactivate_payment_link` | Deactivate / archive a payment link |

### Customers

| Tool | Description |
|---|---|
| `create_customer` | Create a customer with name, email, phone, metadata |
| `list_customers` | Paginated list of customers |
| `get_customer` | Get a single customer by ID |
| `update_customer` | Update customer fields |
| `delete_customer` | Soft-delete a customer |

### Products

| Tool | Description |
|---|---|
| `create_product` | Create a one-time or recurring product |
| `list_products` | List products with optional type filter |
| `get_product` | Get a single product by ID |
| `update_product` | Update product name, description, or price |
| `archive_product` | Archive a product |

### Coupons

| Tool | Description |
|---|---|
| `create_coupon` | Create a fixed or percentage discount coupon |
| `list_coupons` | List coupons with optional status filter |
| `get_coupon` | Get a single coupon by ID |
| `deactivate_coupon` | Deactivate a coupon |

### Invoices

| Tool | Description |
|---|---|
| `create_invoice` | Create a ZATCA-compliant invoice |
| `list_invoices` | List invoices with filters |
| `get_invoice` | Get a single invoice by ID |
| `send_invoice` | (Re)send an invoice via email / SMS |
| `void_invoice` | Void / cancel an unpaid invoice |

### Payments

| Tool | Description |
|---|---|
| `list_payments` | List payments with filters |
| `get_payment` | Get payment details |
| `refund_payment` | Issue a full or partial refund |

### Resources

Reading these resources does not require your Stream API key in the client (unlike the operational tools above).

| Resource URI | Description |
|---|---|
| `stream://docs/openapi` | Full Stream OpenAPI spec (cached, auto-refreshed) — main documentation integration feature |

---

## Auto Charge On Demand

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Auto Charge On Demand"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/payments/auto-charge-on-demand/{payment_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Charge a payment using the consumer's latest tokenized card.

This endpoint allows organizations to charge a payment using the consumer's latest
active tokenized card. The following conditions must be met:

- The consumer must have at least one active tokenized card.
- The payment must be in an unpaid status (PENDING, PROCESSING, FAILED, etc.).

**This is a restricted API and is only available to some organizations.**

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment to charge","title":"Payment Id"},"description":"Unique identifier (UUID) of the payment to charge"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"payment_id":{"type":"string","format":"uuid","title":"Payment Id","description":"ID of the payment that was charged"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id","description":"ID of the invoice associated with the payment"}},"type":"object","title":"AutoChargeOnDemandResponse"}}}},"400":{"description":"If no active card exists, payment is already paid, or payment processing fails."},"401":{"description":"If the organization does not have access to this API."},"404":{"description":"If payment, consumer, card, or consent is not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Cancel Scheduled Subscription Plan Change

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cancel Scheduled Subscription Plan Change"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/api/v2/subscriptions/{subscription_id}/pending-change"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Cancel a previously-scheduled deferred plan change.

No-op (still 200) when no SCHEDULED pending change exists. If the original
schedule call had already re-issued the next-cycle invoice (Arm B), the new
invoice remains unchanged — it represents the upcoming cycle the consumer was
notified about.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Cancel Subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cancel Subscription"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/subscriptions/{subscription_id}/cancel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Schedule or complete cancellation and optionally cancel related invoices.

Behavior depends on subscription **status**:

- **ACTIVE**: Cancellation is **scheduled for the end of the current billing period** (the subscription
  stays active until then; it is not moved to ``CANCELED`` immediately).
- **INACTIVE**, **TRIALING**, **TRIAL_PENDING**: The subscription is **canceled immediately**
  (status becomes ``CANCELED``).

Use ``cancel_related_invoices`` to also cancel ongoing invoices tied to this subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription to cancel","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription to cancel"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"cancel_related_invoices":{"type":"boolean","title":"Cancel Related Invoices","description":"Whether or not to cancel all the related invoices to this subscription. If False, only the subscription will be canceled but the related invoices will remain untouched.","default":false}},"type":"object","title":"SubscriptionCancel"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Branch

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Branch"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/branch"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new branch for the organization.

If a branch with the same name already exists, returns the existing branch.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Branch name. Must be unique within the organization."}},"type":"object","required":["name"],"title":"CreateBranchRequest"}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"user_count":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","title":"BranchItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Consumer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Consumer"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/consumers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new consumer with contact information and payment details.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":512,"title":"Name","description":"Consumer name"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address"},"external_id":{"type":"string","maxLength":512,"nullable":true,"description":"External ID"},"iban":{"type":"string","maxLength":34,"title":"IBAN","nullable":true,"description":"IBAN"},"alias":{"type":"string","maxLength":512,"nullable":true,"description":"Alias"},"comment":{"type":"string","maxLength":512,"nullable":true,"description":"Comment"},"preferred_language":{"nullable":true,"description":"Preferred language","type":"string","enum":["AR","EN"],"title":"Language"},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","nullable":true,"description":"Communication methods"},"consumer_type":{"description":"Consumer type: individual or business","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Address (required for business type)","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1 (building number, street name)"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2 (district)"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","required":["address_line_1","city","country"],"title":"AddressCreate"},"vat_number":{"type":"string","maxLength":64,"nullable":true,"description":"VAT number (optional for business type)"},"commercial_registration":{"type":"string","maxLength":512,"nullable":true,"description":"Commercial registration number (optional for business type)"}},"type":"object","required":["name"],"title":"ConsumerCreate","description":"Consumer creation model."}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the consumer"},"external_id":{"type":"string","nullable":true,"description":"External identifier for the consumer"},"consumer":{"nullable":true,"description":"Consumer information","properties":{"id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"nullable":true,"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"iban":{"type":"string","nullable":true,"description":"IBAN (International Bank Account Number) of the consumer"},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"Whether the consumer has been deleted"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time when the consumer was created"},"branch":{"description":"Branch information for this consumer","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"Branch"},"comment":{"type":"string","nullable":true,"description":"Additional comments or notes about the consumer"},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","title":"Communication Methods","description":"Preferred communication methods for the consumer"},"preferred_language":{"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"description":"Consumer type: individual or business","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"National address (required for business type)","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number (optional for business type)"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration number (optional for business type)"},"last_invoice_activity":{"nullable":true,"description":"Information about the most recent invoice activity for this consumer","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"subcription_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the subscription if applicable"}},"type":"object","title":"LastInvoiceActivity"}},"type":"object","title":"ConsumerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Coupon

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Coupon"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/coupons"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new coupon with discount details and active/inactive status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"anyOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount.","default":false},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is active upon creation.","default":true}},"type":"object","required":["name","discount_value"],"title":"CouponCreate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Invite For A User To Join The Organization By Email

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Invite For A User To Join The Organization By Email"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/organization/invite"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Send an email invitation for a user to join the organization.

An invitation email will be sent to the specified address with a link to accept the invitation.
Organization admins can invite users to any branch, while branch admins can only invite to their own branches.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"language","in":"header","required":false,"schema":{"default":"AR","type":"string","enum":["AR","EN"],"title":"Language"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Email address of the user to invite. Must not already be registered."},"role":{"description":"Role to assign to the invited user.","type":"string","enum":["organization_admin","branch_admin","branch_user"],"title":"UserRolesEnum"},"branches":{"items":{"type":"string","format":"uuid"},"type":"array","minItems":1,"title":"Branches","description":"List of branch IDs where the user will have access."}},"type":"object","required":["email","role","branches"],"title":"OrganizationInviteCreate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","format":"email","title":"Email"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"expire_at":{"type":"string","format":"date-time","title":"Expire At"},"created_by":{"type":"string","format":"uuid","title":"Created By"},"role":{"type":"string","enum":["organization_admin","branch_admin","branch_user"],"title":"UserRolesEnum"},"branches":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Branches"}},"type":"object","title":"OrganizationInviteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Invoice

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Invoice"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/invoices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"notify_consumer":{"type":"boolean","title":"Notify Consumer","description":"Whether to send a notification to the consumer about the invoice","default":true},"description":{"type":"string","maxLength":512,"minLength":1,"nullable":true,"description":"Invoice description or notes"},"items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"UUID of the product to include"},"quantity":{"type":"integer","exclusiveMinimum":0,"title":"Quantity","description":"Quantity of the product"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","nullable":true,"description":"List of coupon UUIDs to apply for discounts on this specific item"}},"type":"object","required":["product_id","quantity"],"title":"InvoiceItemCreateDto"},"type":"array","minItems":1,"title":"Items","description":"List of products or services to include in the invoice"},"payment_methods":{"description":"Payment methods allowed for this invoice","properties":{"mada":{"type":"boolean","title":"Mada","description":"Enable Mada payment method"},"visa":{"type":"boolean","title":"Visa","description":"Enable Visa payment method"},"mastercard":{"type":"boolean","title":"Mastercard","description":"Enable Mastercard payment method"},"amex":{"type":"boolean","title":"Amex","description":"Enable American Express payment method"},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"Enable bank transfer payment method"},"installment":{"type":"boolean","title":"Installment","description":"Enable installment payment option"},"qurrah":{"type":"boolean","title":"Qurrah","description":"Enable Qurrah payment method","default":false}},"type":"object","required":["mada","visa","mastercard","amex","bank_transfer","installment"],"title":"InvoicePaymentMethodDto"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","nullable":true,"description":"List of coupon UUIDs to apply for discounts"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"UUID of the consumer who will pay this invoice"},"scheduled_on":{"type":"string","format":"date-time","title":"Scheduled On","description":"Payment due date. After this date, the invoice will be marked as overdue"},"exclude_coupons_if_installments":{"type":"boolean","title":"Exclude Coupons If Installments","description":"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.","default":false},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"}},"type":"object","required":["items","payment_methods","organization_consumer_id","scheduled_on"],"title":"InvoiceCreate","description":"DTO for creating a new invoice.\n\nMulti-Currency Support:\n- The `currency` field is optional and defaults to 'SAR' for backward compatibility.\n- When a currency is specified, products must have a price in that currency.\n- If no ProductPrice exists for the currency, falls back to product.price (legacy)."}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"invoice_number":{"type":"integer","title":"Invoice Number","description":"Global unique invoice number"},"remaining_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Remaining Amount","description":"Remaining amount to be paid"},"paid_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Paid Amount","description":"Total amount already paid"},"exclude_coupons_if_installments":{"type":"boolean","title":"Exclude Coupons If Installments","description":"Whether coupons are excluded when paying by installments"},"organization_consumer":{"description":"Consumer information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"alias":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone_number":{"type":"string","format":"phone","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse","description":"Address response model."},"vat_number":{"type":"string","nullable":true},"commercial_registration":{"type":"string","nullable":true},"consumer":{"nullable":true,"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"phone_number":{"type":"string","format":"phone","nullable":true},"email":{"type":"string","format":"email","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"is_deleted":{"type":"boolean","nullable":true},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","nullable":true}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"product":{"description":"Product details for this invoice item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this invoice item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"unit_price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Snapshotted unit price at invoice creation (for historical accuracy)"},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item (for traceability)"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceItemDto","description":"Invoice item response DTO.\n\nMulti-Currency Support:\n- `currency`: The currency code for this item (e.g., SAR, USD)\n- `unit_price`: Snapshotted price at invoice creation (for historical accuracy)\n- `product_price_id`: Reference to the ProductPrice used (for traceability)"},"type":"array","title":"Items","description":"List of items included in the invoice"},"branch":{"nullable":true,"description":"Branch information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"BranchDto"},"payments":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"scheduled_on":{"type":"string","format":"date-time","title":"Scheduled On","description":"Scheduled date and time for the payment"},"invoice_payment_number":{"type":"integer","title":"Invoice Payment Number","description":"Payment number within the invoice"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"description":"Current status of the payment","type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"settled_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was settled"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"pdf_link":{"type":"string","nullable":true,"description":"URL to the payment PDF document"},"paid_to_account_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the account the payment was made to"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentDto"},"type":"array","title":"Payments","description":"List of payments associated with this invoice"},"subscription_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the subscription if this invoice is part of a subscription"},"subscription":{"nullable":true,"description":"Subscription details if this invoice is part of a subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"},"payment_methods":{"nullable":true,"description":"Payment methods available for this invoice","properties":{"mada":{"type":"boolean","title":"Mada","description":"Enable Mada payment method"},"visa":{"type":"boolean","title":"Visa","description":"Enable Visa payment method"},"mastercard":{"type":"boolean","title":"Mastercard","description":"Enable Mastercard payment method"},"amex":{"type":"boolean","title":"Amex","description":"Enable American Express payment method"},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"Enable bank transfer payment method"},"installment":{"type":"boolean","title":"Installment","description":"Enable installment payment option"},"qurrah":{"type":"boolean","title":"Qurrah","description":"Enable Qurrah payment method","default":false}},"type":"object","required":["mada","visa","mastercard","amex","bank_transfer","installment"],"title":"InvoicePaymentMethodDto"},"recurrence_pattern":{"nullable":true,"description":"Recurrence pattern for recurring invoices","type":"string","enum":["Hour","Day","Week","Fortnight","Month","Quarter","Half-Year","Year"],"title":"RecurrencePattern"},"parent_id":{"type":"string","format":"uuid4","nullable":true,"description":"Parent invoice ID for recurring invoices"},"custom_field_answers":{"additionalProperties":true,"type":"object","nullable":true,"description":"Answers to custom fields collected for this invoice"},"url":{"type":"string","title":"Url","description":"URL to access the invoice"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true},"remaining_amount_in_smallest_unit":{"type":"integer","title":"Remaining Amount In Smallest Unit","description":"Remaining amount in smallest currency unit.","readOnly":true},"paid_amount_in_smallest_unit":{"type":"integer","title":"Paid Amount In Smallest Unit","description":"Paid amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Payment Link

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Payment Link"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/payment_links"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new checkout/payment link for collecting payments.

- **One-time products**: Creates an invoice (with its associated payment) when paid.
- **Recurring products**: Creates a subscription (with its associated invoice and payment) when paid.

**Notes:**
- Cannot mix one-time and recurring products in the same payment link.
- Installments are automatically disabled for recurring products (subscriptions).
- Invoices, subscriptions and payments are created only after a successful payment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":512,"title":"Name","description":"Name of the payment link"},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Optional description of the payment link"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product to include in the payment link"},"quantity":{"type":"integer","minimum":1,"title":"Quantity","description":"Quantity of the product. Must be at least 1.","default":1},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Coupons","description":"List of coupon UUIDs to apply to this specific item for discounts"},"allow_custom_quantity":{"type":"boolean","title":"Allow Custom Quantity","description":"Whether customers can select custom quantity for this item","default":false},"min_quantity":{"type":"integer","minimum":0,"nullable":true,"description":"Minimum quantity allowed if allow_custom_quantity is True; value is inclusive"},"max_quantity":{"type":"integer","minimum":0,"nullable":true,"description":"Maximum quantity allowed if allow_custom_quantity is True; value is inclusive"}},"type":"object","required":["product_id"],"title":"CreatePaymentLinkItemDto"},"type":"array","minItems":1,"title":"Items","description":"List of products to include in the payment link"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Coupons","description":"List of coupon UUIDs to apply at the payment link level for discounts"},"max_number_of_payments":{"type":"integer","nullable":true,"description":"Maximum number of times this payment link can be used. If null, the payment link can be used unlimited times. If organization_consumer_id is set, this number becomes how many times that specific customer can pay. Typically this should be set to 1 in that scenario."},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"Datetime after which the payment link is no longer valid. If no timezone is specified, UTC is assumed."},"confirmation_message":{"type":"string","maxLength":512,"nullable":true,"description":"Optional message to display to the payer after successful payment"},"payment_methods":{"nullable":true,"description":"Configure which payment methods are available. If null, organization defaults are used. Note: Installments are always disabled for recurring products (subscriptions).","properties":{"visa":{"type":"boolean","title":"Visa","description":"visa is enabled","default":false},"mastercard":{"type":"boolean","title":"Mastercard","description":"mastercard is enabled","default":false},"amex":{"type":"boolean","title":"Amex","description":"amex is enabled","default":false},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"bank_transfer is enabled","default":false},"installment":{"type":"boolean","title":"Installment","description":"installment is enabled","default":false}},"type":"object","title":"PaymentMethodDto"},"trial_period_days":{"type":"integer","maximum":365,"minimum":1,"nullable":true,"description":"Free trial duration (in days) for subscriptions created from this link. Only valid when the link contains recurring (subscription) products. Must be between 1 and 365. Omit (or null) for no trial."},"custom_fields":{"type":"object","title":"properties","description":"JSON Schema (https://json-schema.org/specification) to define and validate fields collected from payers during payment. Only string type properties allowed.","example":{"properties":{"child_name":{"title":"Child Name","type":"string"},"parent_email":{"title":"Parent Email","type":"string"}},"required":["child_name"],"type":"object"},"nullable":true},"success_redirect_url":{"type":"string","maxLength":2000,"minLength":1,"format":"uri","nullable":true,"description":"URL to redirect the payer to after a successful payment"},"failure_redirect_url":{"type":"string","maxLength":2000,"minLength":1,"format":"uri","nullable":true,"description":"URL to redirect the payer to after a failed payment"},"organization_consumer_id":{"type":"string","format":"uuid","nullable":true,"description":"ID of an existing consumer who will pay using this payment link. If set, customer information is not collected and this payment will be for that customer only. This is typically used when a specific customer is paying once. If not set, the link will collect customer information first. Use this when you expect multiple payments from different people, such as for a group trip or event."},"custom_metadata":{"additionalProperties":{"title":"JsonValue"},"type":"object","nullable":true,"description":"Optional key-value metadata dictionary for attaching custom information. This metadata will be included as-is in payment link responses and webhook payloads."},"contact_information_type":{"nullable":true,"description":"Type of contact information required for payment collection. Defaults to PHONE if not specified.","type":"string","enum":["PHONE","EMAIL"],"title":"ContactInformationType"}},"type":"object","required":["name","items"],"title":"CreatePaymentLinkDto"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link"},"name":{"type":"string","title":"Name","description":"Name of the payment link"},"description":{"type":"string","nullable":true,"description":"Description of the payment link"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total payment link amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original payment link amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the payment link","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation; for SAR links or when converted from other currencies."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate from link currency to home currency (SAR) at creation time"},"max_number_of_payments":{"type":"integer","nullable":true,"description":"Maximum number of times this payment link can be used"},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"UTC datetime after which the payment link is no longer valid"},"confirmation_message":{"type":"string","nullable":true,"description":"Message to display to the payer after successful payment"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this payment link creates a subscription","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring payments"},"trial_period_days":{"type":"integer","nullable":true,"description":"Free trial duration (in days) for subscriptions created from this link. Only meaningful for recurring (subscription) products. When set, each consumer who subscribes via this link gets a free trial of this length, after which the first real billing period begins. Must be between 1 and 365."},"status":{"description":"Current status of the payment link","type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the payment link"},"organization_consumer_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the organization consumer if linked to a specific consumer"},"deactivate_message":{"type":"string","nullable":true,"description":"Message to display when the payment link is deactivated"},"custom_fields":{"type":"object","title":"properties","description":"Custom fields schema for collecting additional information","example":{"properties":{"child_name":{"title":"Child Name","type":"string"},"parent_email":{"title":"Parent Email","type":"string"}},"required":["child_name"],"type":"object"},"nullable":true},"success_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a successful payment"},"failure_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a failed payment"},"custom_metadata":{"additionalProperties":{"title":"JsonValue"},"type":"object","nullable":true,"description":"The key-value metadata dictionary passed during creation."},"contact_information_type":{"nullable":true,"description":"Type of contact information required for payment collection","type":"string","enum":["PHONE","EMAIL"],"title":"ContactInformationType"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this payment link item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."},"allow_custom_quantity":{"type":"boolean","title":"Allow Custom Quantity","description":"Whether customers can select custom quantity for this item","default":false},"min_quantity":{"type":"integer","nullable":true,"description":"Minimum quantity allowed if allow_custom_quantity is True"},"max_quantity":{"type":"integer","nullable":true,"description":"Maximum quantity allowed if allow_custom_quantity is True"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item, if any"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkItemDto"},"type":"array","title":"Items","description":"List of products included in the payment link"},"coupons":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"},"type":"array","title":"Coupons","description":"List of coupons applied to the payment link"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this payment link","properties":{"visa":{"type":"boolean","title":"Visa","description":"visa is enabled","default":false},"mastercard":{"type":"boolean","title":"Mastercard","description":"mastercard is enabled","default":false},"amex":{"type":"boolean","title":"Amex","description":"amex is enabled","default":false},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"bank_transfer is enabled","default":false},"installment":{"type":"boolean","title":"Installment","description":"installment is enabled","default":false}},"type":"object","title":"PaymentMethodDto"},"url":{"type":"string","title":"Url","description":"Public URL of the payment link for sharing with payers"},"amount_collected":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Collected","description":"Total amount collected from payments"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment link amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original payment link amount (before discounts) in smallest currency unit.","readOnly":true},"amount_collected_in_smallest_unit":{"type":"integer","title":"Amount Collected In Smallest Unit","description":"Total amount collected in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Product

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Product"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new product with pricing and description.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"minLength":1,"nullable":true,"description":"Description of the product."},"price":{"anyOf":[{"type":"number","minimum":1},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Price","description":"[DEPRECATED] Price of the product. Use 'prices' array for multi-currency support."},"prices":{"items":{"properties":{"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"anyOf":[{"type":"number","minimum":1},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Amount","description":"Price amount (must be >= 1)"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"If True, amount includes VAT","default":true},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"If True, no VAT applies to this price","default":false}},"type":"object","required":["currency","amount"],"title":"ProductPriceInlineCreate","description":"Inline price creation for product create/update endpoints."},"type":"array","nullable":true,"description":"Prices for the product in different currencies. At least one price is required."},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Will this product be used only one time in one invoice?","default":false},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring. Required for cyclic products. For ONE_OFF, value is ignored.","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","minimum":1,"title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring","default":1},"is_price_exempt_from_vat":{"type":"boolean","nullable":true,"description":"[DEPRECATED] Is the price exempt from VAT? Use VAT settings in prices[] instead."},"is_price_inclusive_of_vat":{"type":"boolean","nullable":true,"description":"[DEPRECATED] Is the price inclusive of VAT? Use VAT settings in prices[] instead."}},"type":"object","required":["name","type"],"title":"ProductCreate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Create Subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Subscription"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/subscriptions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new subscription with items, coupons, and payment methods.

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 a subscription and manually marking it as paid for reference
- Automated subscription creation

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"notify_consumer":{"type":"boolean","title":"Notify Consumer","description":"Whether to send a notification to the consumer about the subscription's first invoice","default":true},"description":{"type":"string","maxLength":512,"minLength":1,"nullable":true,"description":"Subscription description or notes"},"items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"UUID of the product to include"},"quantity":{"type":"integer","exclusiveMinimum":0,"title":"Quantity","description":"Quantity of the product"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","nullable":true,"description":"List of coupon UUIDs to apply for discounts on this specific item"}},"type":"object","required":["product_id","quantity"],"title":"SubscriptionItemCreateDto"},"type":"array","minItems":1,"title":"Items","description":"List of products or services to include in the subscription"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","nullable":true,"description":"List of coupon UUIDs to apply for discounts on subscription invoices"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"UUID of the consumer who will subscribe"},"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Start date of the first billing cycle. For trial subscriptions, this must be a future date — the trial runs from now until this date."},"until_cycle_number":{"type":"integer","minimum":1,"nullable":true,"description":"Number of billing cycles before the subscription automatically cancels. If not specified, the subscription continues indefinitely until manually canceled."},"override_payment_methods":{"nullable":true,"description":"Override payment methods for invoices generated by this subscription. Set any field to null to use the organization's global settings for that payment method.","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"exclude_coupons_if_installments":{"type":"boolean","title":"Exclude Coupons If Installments","description":"If enabled, all coupons (subscription-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.","default":false},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","maxLength":3,"minLength":3,"default":"SAR"},"trial":{"type":"boolean","title":"Trial","description":"Whether this is a free trial subscription. If true, the trial starts now and billing begins at period_start.","default":false}},"type":"object","required":["items","organization_consumer_id","period_start"],"title":"SubscriptionCreate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Delete Branch

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Branch"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/api/v2/branch/{branch_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a branch from the organization.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"branch_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the branch to delete","title":"Branch Id"},"description":"Unique identifier (UUID) of the branch to delete"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Delete Consumer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Consumer"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/api/v2/consumers/{consumer_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a consumer from the organization.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"consumer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the consumer to delete","title":"Consumer Id"},"description":"Unique identifier (UUID) of the consumer to delete"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Delete Coupon

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Coupon"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/api/v2/coupons/{coupon_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a coupon from the organization.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"coupon_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the coupon to delete","title":"Coupon Id"},"description":"Unique identifier (UUID) of the coupon to delete"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Delete Product

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Product"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/api/v2/products/{product_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a product from the organization.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the product to delete","title":"Product Id"},"description":"Unique identifier (UUID) of the product to delete"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Delete Subscription Freeze

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Subscription Freeze"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/api/v2/subscriptions/{subscription_id}/freeze/{freeze_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Remove a freeze period from a subscription.

Deletes the specified freeze period, allowing the subscription to resume normal invoice
generation immediately (if the freeze period was active).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription"},{"name":"freeze_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the freeze period to delete","title":"Freeze Id"},"description":"Unique identifier (UUID) of the freeze period to delete"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Freeze Subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Freeze Subscription"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/subscriptions/{subscription_id}/freeze"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Freeze a subscription to pause invoice generation for a specific period.

During the freeze period, no invoices will be generated for the subscription. The subscription
will automatically resume after the freeze period ends.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription to freeze","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription to freeze"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime","description":"Start date and time when the subscription freeze period begins"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true,"description":"End date and time when the subscription freeze period ends. If not provided, the freeze will continue indefinitely until manually removed."},"notes":{"type":"string","nullable":true,"description":"Optional notes explaining the reason for the freeze"}},"type":"object","required":["freeze_start_datetime"],"title":"FreezeSubscriptionCreateRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get All Branches

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get All Branches"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/branch"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all branches for the organization.

Returns branches based on user role:
- Organization admins see all branches in the organization
- Branch admins and branch users see only branches they're assigned to

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"user_count":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","title":"BranchItem"},"type":"array","title":"Data"}},"type":"object","title":"BranchListResponse"}}}}}}
>
  
</StatusCodes>

---

## Get All Consumers

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get All Consumers"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/consumers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"search_term","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Search term to filter consumers. Default is None."},"description":"Search term to filter consumers. Default is None."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the consumer"},"external_id":{"type":"string","nullable":true,"description":"External identifier for the consumer"},"consumer":{"nullable":true,"description":"Consumer information","properties":{"id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"nullable":true,"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"iban":{"type":"string","nullable":true,"description":"IBAN (International Bank Account Number) of the consumer"},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"Whether the consumer has been deleted"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time when the consumer was created"},"branch":{"description":"Branch information for this consumer","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"Branch"},"comment":{"type":"string","nullable":true,"description":"Additional comments or notes about the consumer"},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","title":"Communication Methods","description":"Preferred communication methods for the consumer"},"preferred_language":{"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"description":"Consumer type: individual or business","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"National address (required for business type)","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number (optional for business type)"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration number (optional for business type)"},"last_invoice_activity":{"nullable":true,"description":"Information about the most recent invoice activity for this consumer","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"subcription_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the subscription if applicable"}},"type":"object","title":"LastInvoiceActivity"}},"type":"object","title":"ConsumerResponse"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[ConsumerResponse]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Branch By Id

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Branch By Id"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/branch/{branch_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific branch by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"branch_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the branch to retrieve","title":"Branch Id"},"description":"Unique identifier (UUID) of the branch to retrieve"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"user_count":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","title":"BranchItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Consumer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Consumer"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/consumers/{consumer_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific consumer by their ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"consumer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the consumer","title":"Consumer Id"},"description":"Unique identifier (UUID) of the consumer"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the consumer"},"external_id":{"type":"string","nullable":true,"description":"External identifier for the consumer"},"consumer":{"nullable":true,"description":"Consumer information","properties":{"id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"nullable":true,"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"iban":{"type":"string","nullable":true,"description":"IBAN (International Bank Account Number) of the consumer"},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"Whether the consumer has been deleted"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time when the consumer was created"},"branch":{"description":"Branch information for this consumer","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"Branch"},"comment":{"type":"string","nullable":true,"description":"Additional comments or notes about the consumer"},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","title":"Communication Methods","description":"Preferred communication methods for the consumer"},"preferred_language":{"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"description":"Consumer type: individual or business","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"National address (required for business type)","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number (optional for business type)"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration number (optional for business type)"}},"type":"object","title":"BaseConsumerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Coupon

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Coupon"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/coupons/{coupon_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific coupon including redemption history.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"coupon_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the coupon","title":"Coupon Id"},"description":"Unique identifier (UUID) of the coupon"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."},"redemptions":{"type":"integer","title":"Redemptions","description":"Indicates how many times this coupon has been used."}},"type":"object","title":"CouponDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Invoice

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Invoice"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/invoices/{invoice_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific invoice by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the invoice","title":"Invoice Id"},"description":"Unique identifier (UUID) of the invoice"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"invoice_number":{"type":"integer","title":"Invoice Number","description":"Global unique invoice number"},"remaining_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Remaining Amount","description":"Remaining amount to be paid"},"paid_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Paid Amount","description":"Total amount already paid"},"exclude_coupons_if_installments":{"type":"boolean","title":"Exclude Coupons If Installments","description":"Whether coupons are excluded when paying by installments"},"organization_consumer":{"description":"Consumer information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"alias":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone_number":{"type":"string","format":"phone","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse","description":"Address response model."},"vat_number":{"type":"string","nullable":true},"commercial_registration":{"type":"string","nullable":true},"consumer":{"nullable":true,"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"phone_number":{"type":"string","format":"phone","nullable":true},"email":{"type":"string","format":"email","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"is_deleted":{"type":"boolean","nullable":true},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","nullable":true}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"product":{"description":"Product details for this invoice item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this invoice item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"unit_price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Snapshotted unit price at invoice creation (for historical accuracy)"},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item (for traceability)"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceItemDto","description":"Invoice item response DTO.\n\nMulti-Currency Support:\n- `currency`: The currency code for this item (e.g., SAR, USD)\n- `unit_price`: Snapshotted price at invoice creation (for historical accuracy)\n- `product_price_id`: Reference to the ProductPrice used (for traceability)"},"type":"array","title":"Items","description":"List of items included in the invoice"},"branch":{"nullable":true,"description":"Branch information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"BranchDto"},"payments":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"scheduled_on":{"type":"string","format":"date-time","title":"Scheduled On","description":"Scheduled date and time for the payment"},"invoice_payment_number":{"type":"integer","title":"Invoice Payment Number","description":"Payment number within the invoice"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"description":"Current status of the payment","type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"settled_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was settled"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"pdf_link":{"type":"string","nullable":true,"description":"URL to the payment PDF document"},"paid_to_account_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the account the payment was made to"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentDto"},"type":"array","title":"Payments","description":"List of payments associated with this invoice"},"subscription_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the subscription if this invoice is part of a subscription"},"subscription":{"nullable":true,"description":"Subscription details if this invoice is part of a subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"},"payment_methods":{"nullable":true,"description":"Payment methods available for this invoice","properties":{"mada":{"type":"boolean","title":"Mada","description":"Enable Mada payment method"},"visa":{"type":"boolean","title":"Visa","description":"Enable Visa payment method"},"mastercard":{"type":"boolean","title":"Mastercard","description":"Enable Mastercard payment method"},"amex":{"type":"boolean","title":"Amex","description":"Enable American Express payment method"},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"Enable bank transfer payment method"},"installment":{"type":"boolean","title":"Installment","description":"Enable installment payment option"},"qurrah":{"type":"boolean","title":"Qurrah","description":"Enable Qurrah payment method","default":false}},"type":"object","required":["mada","visa","mastercard","amex","bank_transfer","installment"],"title":"InvoicePaymentMethodDto"},"recurrence_pattern":{"nullable":true,"description":"Recurrence pattern for recurring invoices","type":"string","enum":["Hour","Day","Week","Fortnight","Month","Quarter","Half-Year","Year"],"title":"RecurrencePattern"},"parent_id":{"type":"string","format":"uuid4","nullable":true,"description":"Parent invoice ID for recurring invoices"},"custom_field_answers":{"additionalProperties":true,"type":"object","nullable":true,"description":"Answers to custom fields collected for this invoice"},"url":{"type":"string","title":"Url","description":"URL to access the invoice"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true},"remaining_amount_in_smallest_unit":{"type":"integer","title":"Remaining Amount In Smallest Unit","description":"Remaining amount in smallest currency unit.","readOnly":true},"paid_amount_in_smallest_unit":{"type":"integer","title":"Paid Amount In Smallest Unit","description":"Paid amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Payment"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/payments/{payment_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific payment by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment","title":"Payment Id"},"description":"Unique identifier (UUID) of the payment"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"scheduled_on":{"type":"string","title":"Scheduled On","description":"Scheduled date and time for the payment"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum","description":"Current status of the payment"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"refund_reason":{"nullable":true,"description":"Reason for the refund if applicable","type":"string","enum":["REQUESTED_BY_CUSTOMER","DUPLICATE","FRAUDULENT","OTHER"],"title":"PaymentRefundReason"},"refund_note":{"type":"string","nullable":true,"description":"Note explaining the refund reason if applicable"},"latest_pgw_message":{"type":"string","nullable":true,"description":"Latest payment gateway message for this payment"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Payment Link

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Payment Link"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/payment_links/{payment_link_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific payment link by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment link","title":"Payment Link Id"},"description":"Unique identifier (UUID) of the payment link"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link"},"name":{"type":"string","title":"Name","description":"Name of the payment link"},"description":{"type":"string","nullable":true,"description":"Description of the payment link"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total payment link amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original payment link amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the payment link","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation; for SAR links or when converted from other currencies."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate from link currency to home currency (SAR) at creation time"},"max_number_of_payments":{"type":"integer","nullable":true,"description":"Maximum number of times this payment link can be used"},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"UTC datetime after which the payment link is no longer valid"},"confirmation_message":{"type":"string","nullable":true,"description":"Message to display to the payer after successful payment"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this payment link creates a subscription","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring payments"},"trial_period_days":{"type":"integer","nullable":true,"description":"Free trial duration (in days) for subscriptions created from this link. Only meaningful for recurring (subscription) products. When set, each consumer who subscribes via this link gets a free trial of this length, after which the first real billing period begins. Must be between 1 and 365."},"status":{"description":"Current status of the payment link","type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the payment link"},"organization_consumer_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the organization consumer if linked to a specific consumer"},"deactivate_message":{"type":"string","nullable":true,"description":"Message to display when the payment link is deactivated"},"custom_fields":{"type":"object","title":"properties","description":"Custom fields schema for collecting additional information","example":{"properties":{"child_name":{"title":"Child Name","type":"string"},"parent_email":{"title":"Parent Email","type":"string"}},"required":["child_name"],"type":"object"},"nullable":true},"success_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a successful payment"},"failure_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a failed payment"},"custom_metadata":{"additionalProperties":{"title":"JsonValue"},"type":"object","nullable":true,"description":"The key-value metadata dictionary passed during creation."},"contact_information_type":{"nullable":true,"description":"Type of contact information required for payment collection","type":"string","enum":["PHONE","EMAIL"],"title":"ContactInformationType"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this payment link item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."},"allow_custom_quantity":{"type":"boolean","title":"Allow Custom Quantity","description":"Whether customers can select custom quantity for this item","default":false},"min_quantity":{"type":"integer","nullable":true,"description":"Minimum quantity allowed if allow_custom_quantity is True"},"max_quantity":{"type":"integer","nullable":true,"description":"Maximum quantity allowed if allow_custom_quantity is True"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item, if any"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkItemDto"},"type":"array","title":"Items","description":"List of products included in the payment link"},"coupons":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"},"type":"array","title":"Coupons","description":"List of coupons applied to the payment link"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this payment link","properties":{"visa":{"type":"boolean","title":"Visa","description":"visa is enabled","default":false},"mastercard":{"type":"boolean","title":"Mastercard","description":"mastercard is enabled","default":false},"amex":{"type":"boolean","title":"Amex","description":"amex is enabled","default":false},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"bank_transfer is enabled","default":false},"installment":{"type":"boolean","title":"Installment","description":"installment is enabled","default":false}},"type":"object","title":"PaymentMethodDto"},"url":{"type":"string","title":"Url","description":"Public URL of the payment link for sharing with payers"},"amount_collected":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Collected","description":"Total amount collected from payments"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment link amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original payment link amount (before discounts) in smallest currency unit.","readOnly":true},"amount_collected_in_smallest_unit":{"type":"integer","title":"Amount Collected In Smallest Unit","description":"Total amount collected in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Product

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/products/{product_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific product by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the product","title":"Product Id"},"description":"Unique identifier (UUID) of the product"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get Subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Subscription"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/subscriptions/{subscription_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve detailed information about a specific subscription by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Get User And Organization Info

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User And Organization Info"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/me"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve information about the authenticated user and their organization.

It requires a valid authentication token and can be used to verify API
connectivity and retrieve user context. This endpoint returns details about the currently
authenticated user and their associated organization.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"user":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","title":"Email"},"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"en_first_name":{"type":"string","nullable":true},"en_last_name":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","title":"MeUserInfo","description":"User information for /me endpoint."},"organization":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"name_en":{"type":"string","nullable":true},"sandbox":{"type":"boolean","title":"Sandbox"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"currency_config":{"properties":{"home_currency":{"description":"Settlement/reporting currency. Always SAR for Moyasar settlements.","default":"SAR","type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode"},"default_currency":{"description":"Default currency for new invoices and products.","default":"SAR","type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode"},"enabled_currencies":{"items":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"type":"array","minItems":1,"title":"Enabled Currencies","description":"List of currencies enabled for billing. Must include at least one.","default":["SAR"]}},"type":"object","title":"OrganizationCurrencyConfigDTO","description":"DTO for organization currency configuration."}},"type":"object","title":"MeOrganizationInfo","description":"Organization information for /me endpoint."}},"type":"object","title":"MeResponse","description":"Response for /me endpoint."}}}}}}
>
  
</StatusCodes>

---

## List Coupons

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Coupons"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/coupons"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"search_term","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Search by coupon name."},"description":"Search by coupon name."},{"name":"active","in":"query","required":false,"schema":{"type":"boolean","nullable":true,"description":"Filter by active or inactive coupons."},"description":"Filter by active or inactive coupons."},{"name":"is_percentage","in":"query","required":false,"schema":{"type":"boolean","nullable":true,"description":"Filter by percentage-based or fixed-amount coupons."},"description":"Filter by percentage-based or fixed-amount coupons."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."},"redemptions":{"type":"integer","title":"Redemptions","description":"Indicates how many times this coupon has been used."}},"type":"object","title":"CouponDetailed"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[CouponDetailed]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## List Invoices

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Invoices"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/invoices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"include_payments","in":"query","required":false,"schema":{"type":"boolean","nullable":true}},{"name":"payment_link_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","nullable":true}},{"name":"statuses","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum","description":"Invoice status enum representing the lifecycle/state of an invoice.\n\nStatus describes the current stage of an invoice in its lifecycle (DRAFT → CREATED → SENT → ACCEPTED → COMPLETED).\nThis changes over time as the invoice progresses. Different from InvoiceType which describes the payment structure."},"nullable":true}},{"name":"payment_statuses","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum"},"nullable":true,"description":"Invoice includes payments with the following statuses"},"description":"Invoice includes payments with the following statuses"},{"name":"search_term","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"from_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true}},{"name":"to_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true}},{"name":"due_date_from","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Invoice's payment due date from this date onwards"},"description":"Invoice's payment due date from this date onwards"},{"name":"due_date_to","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Invoice's payment due date to this date or older"},"description":"Invoice's payment due date to this date or older"},{"name":"from_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}]}},{"name":"to_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}]}},{"name":"organization_consumer_id","in":"query","required":false,"schema":{"type":"string","format":"uuid4","nullable":true}},{"name":"subscription_id","in":"query","required":false,"schema":{"type":"string","format":"uuid4","nullable":true}},{"name":"currencies","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Filter by invoice currency codes (OR). E.g. currencies=SAR,USD"},"description":"Filter by invoice currency codes (OR). E.g. currencies=SAR,USD"},{"name":"payments_not_settled","in":"query","required":false,"schema":{"type":"boolean","nullable":true,"description":"When true, only include invoices with a SUCCEEDED card/wallet payment (e.g. MADA, Visa)."},"description":"When true, only include invoices with a SUCCEEDED card/wallet payment (e.g. MADA, Visa)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum","description":"Invoice status enum representing the lifecycle/state of an invoice.\n\nStatus describes the current stage of an invoice in its lifecycle (DRAFT → CREATED → SENT → ACCEPTED → COMPLETED).\nThis changes over time as the invoice progresses. Different from InvoiceType which describes the payment structure."},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"remaining_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Remaining amount to be paid"},"paid_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Paid Amount","description":"Total amount already paid"},"organization_consumer":{"description":"Consumer information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"alias":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone_number":{"type":"string","format":"phone","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse","description":"Address response model."},"vat_number":{"type":"string","nullable":true},"commercial_registration":{"type":"string","nullable":true},"consumer":{"nullable":true,"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"phone_number":{"type":"string","format":"phone","nullable":true},"email":{"type":"string","format":"email","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"is_deleted":{"type":"boolean","nullable":true},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","nullable":true}},"type":"object","title":"OrganizationConsumer"},"subscription":{"nullable":true,"description":"Subscription information if this invoice is part of a subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the current billing period"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"}},"type":"object","title":"InvoiceListSubscrptionDto"},"payments":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"scheduled_on":{"type":"string","format":"date-time","title":"Scheduled On","description":"Scheduled date and time for the payment"},"invoice_payment_number":{"type":"integer","title":"Invoice Payment Number","description":"Payment number within the invoice"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"description":"Current status of the payment","type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"settled_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was settled"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"pdf_link":{"type":"string","nullable":true,"description":"URL to the payment PDF document"},"paid_to_account_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the account the payment was made to"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentDto"},"type":"array","nullable":true,"description":"List of payments associated with this invoice"},"total_number_of_payments":{"type":"integer","title":"Total Number Of Payments","description":"Total number of payments for this invoice"},"last_payment_paid_at":{"type":"string","format":"date-time","nullable":true,"description":"The date when the last payment was paid"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true},"remaining_amount_in_smallest_unit":{"type":"integer","nullable":true,"description":"Remaining amount in smallest currency unit."},"paid_amount_in_smallest_unit":{"type":"integer","title":"Paid Amount In Smallest Unit","description":"Paid amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceListItem"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[InvoiceListItem]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## List Payment Links

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Payment Links"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/payment_links"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all payment links with pagination, filtering, and sorting options.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"statuses","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus"},"nullable":true,"description":"Filter by subscription status"},"description":"Filter by subscription status"},{"name":"from_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"datetime is created_at"},"description":"datetime is created_at"},{"name":"to_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"datetime is created_at"},"description":"datetime is created_at"},{"name":"from_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"limit list by min payment link total amount inclusive"},"description":"limit list by min payment link total amount inclusive"},{"name":"to_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"limit list by max payment link total amount inclusive"},"description":"limit list by max payment link total amount inclusive"},{"name":"product_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"Product ids that need to be in the list of payment links"},"description":"Product ids that need to be in the list of payment links"},{"name":"currencies","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Filter by currency codes (OR). E.g. currencies=SAR,USD"},"description":"Filter by currency codes (OR). E.g. currencies=SAR,USD"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link"},"name":{"type":"string","title":"Name","description":"Name of the payment link"},"description":{"type":"string","nullable":true,"description":"Description of the payment link"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total payment link amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original payment link amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the payment link","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation; for SAR links or when converted from other currencies."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate from link currency to home currency (SAR) at creation time"},"max_number_of_payments":{"type":"integer","nullable":true,"description":"Maximum number of times this payment link can be used"},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"UTC datetime after which the payment link is no longer valid"},"confirmation_message":{"type":"string","nullable":true,"description":"Message to display to the payer after successful payment"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this payment link creates a subscription","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring payments"},"trial_period_days":{"type":"integer","nullable":true,"description":"Free trial duration (in days) for subscriptions created from this link. Only meaningful for recurring (subscription) products. When set, each consumer who subscribes via this link gets a free trial of this length, after which the first real billing period begins. Must be between 1 and 365."},"status":{"description":"Current status of the payment link","type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the payment link"},"organization_consumer_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the organization consumer if linked to a specific consumer"},"deactivate_message":{"type":"string","nullable":true,"description":"Message to display when the payment link is deactivated"},"custom_fields":{"type":"object","title":"properties","description":"Custom fields schema for collecting additional information","example":{"properties":{"child_name":{"title":"Child Name","type":"string"},"parent_email":{"title":"Parent Email","type":"string"}},"required":["child_name"],"type":"object"},"nullable":true},"success_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a successful payment"},"failure_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a failed payment"},"custom_metadata":{"additionalProperties":{"title":"JsonValue"},"type":"object","nullable":true,"description":"The key-value metadata dictionary passed during creation."},"contact_information_type":{"nullable":true,"description":"Type of contact information required for payment collection","type":"string","enum":["PHONE","EMAIL"],"title":"ContactInformationType"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this payment link item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."},"allow_custom_quantity":{"type":"boolean","title":"Allow Custom Quantity","description":"Whether customers can select custom quantity for this item","default":false},"min_quantity":{"type":"integer","nullable":true,"description":"Minimum quantity allowed if allow_custom_quantity is True"},"max_quantity":{"type":"integer","nullable":true,"description":"Maximum quantity allowed if allow_custom_quantity is True"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item, if any"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkItemDto"},"type":"array","title":"Items","description":"List of products included in the payment link"},"coupons":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"},"type":"array","title":"Coupons","description":"List of coupons applied to the payment link"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this payment link","properties":{"visa":{"type":"boolean","title":"Visa","description":"visa is enabled","default":false},"mastercard":{"type":"boolean","title":"Mastercard","description":"mastercard is enabled","default":false},"amex":{"type":"boolean","title":"Amex","description":"amex is enabled","default":false},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"bank_transfer is enabled","default":false},"installment":{"type":"boolean","title":"Installment","description":"installment is enabled","default":false}},"type":"object","title":"PaymentMethodDto"},"url":{"type":"string","title":"Url","description":"Public URL of the payment link for sharing with payers"},"amount_collected":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Collected","description":"Total amount collected from payments"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment link amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original payment link amount (before discounts) in smallest currency unit.","readOnly":true},"amount_collected_in_smallest_unit":{"type":"integer","title":"Amount Collected In Smallest Unit","description":"Total amount collected in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkDetailed"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[PaymentLinkDetailed]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## List Payments

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Payments"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/payments"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

Payments can be filtered by invoice IDs, statuses, date ranges, or search terms.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_id","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"Filter by invoice IDs. Default is None."},"description":"Filter by invoice IDs. Default is None."},{"name":"statuses","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum"},"nullable":true,"description":"Filter by payment statuses. Default is None."},"description":"Filter by payment statuses. Default is None."},{"name":"search_term","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Search term to filter payments. Default is None."},"description":"Search term to filter payments. Default is None."},{"name":"from_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Filter payments from this date. Default is None."},"description":"Filter payments from this date. Default is None."},{"name":"to_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Filter payments up to this date. Default is None."},"description":"Filter payments up to this date. Default is None."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"scheduled_on":{"type":"string","title":"Scheduled On","description":"Scheduled date and time for the payment"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum","description":"Current status of the payment"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"refund_reason":{"nullable":true,"description":"Reason for the refund if applicable","type":"string","enum":["REQUESTED_BY_CUSTOMER","DUPLICATE","FRAUDULENT","OTHER"],"title":"PaymentRefundReason"},"refund_note":{"type":"string","nullable":true,"description":"Note explaining the refund reason if applicable"},"latest_pgw_message":{"type":"string","nullable":true,"description":"Latest payment gateway message for this payment"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentResponse"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[PaymentResponse]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## List Products

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"search_term","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Serach by product name or description."},"description":"Serach by product name or description."},{"name":"active","in":"query","required":false,"schema":{"type":"boolean","nullable":true,"description":"Filter by active or inactive product. Removing this flag will return all products."},"description":"Filter by active or inactive product. Removing this flag will return all products."},{"name":"type","in":"query","required":false,"schema":{"nullable":true,"description":"Filter by product type.","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"description":"Filter by product type."},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"nullable":true,"description":"Filter by currency availability. Only returns products with an active price in this currency."},"description":"Filter by currency availability. Only returns products with an active price in this currency."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[ProductDto]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## List Subscription Freezes

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Subscription Freezes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/subscriptions/{subscription_id}/freeze"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all freeze periods for a specific subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[FreezeSubscriptionBase]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## List Subscriptions

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Subscriptions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/subscriptions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

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

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"statuses","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"nullable":true,"description":"Filter by subscription status"},"description":"Filter by subscription status"},{"name":"latest_invoice_is_paid","in":"query","required":false,"schema":{"type":"boolean","nullable":true,"description":"Filter subscriptions based on if their latest invoice is paid or partially paid"},"description":"Filter subscriptions based on if their latest invoice is paid or partially paid"},{"name":"from_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"datetime is created_at"},"description":"datetime is created_at"},{"name":"to_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"datetime is created_at"},"description":"datetime is created_at"},{"name":"current_period_start_from_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Filter subscriptions with current_period_start from this date onwards"},"description":"Filter subscriptions with current_period_start from this date onwards"},{"name":"current_period_start_to_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Filter subscriptions with current_period_start up to this date"},"description":"Filter subscriptions with current_period_start up to this date"},{"name":"current_period_end_from_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Filter subscriptions with current_period_end from this date onwards"},"description":"Filter subscriptions with current_period_end from this date onwards"},{"name":"current_period_end_to_date","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"description":"Filter subscriptions with current_period_end up to this date"},"description":"Filter subscriptions with current_period_end up to this date"},{"name":"from_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"limit list by min subscription amount inclusive"},"description":"limit list by min subscription amount inclusive"},{"name":"to_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"limit list by max subscription amount inclusive"},"description":"limit list by max subscription amount inclusive"},{"name":"organization_consumer_id","in":"query","required":false,"schema":{"type":"string","format":"uuid4","nullable":true,"description":"filter subscriptions that belongs to organization consumer"},"description":"filter subscriptions that belongs to organization consumer"},{"name":"search_term","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Serach by product name or description."},"description":"Serach by product name or description."},{"name":"product_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"Product ids that need to be in the list of subscriptions"},"description":"Product ids that need to be in the list of subscriptions"},{"name":"currencies","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Filter subscriptions by currency codes (OR). E.g. currencies=SAR,USD"},"description":"Filter subscriptions by currency codes (OR). E.g. currencies=SAR,USD"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Page number, defaults to 1.","default":1},"description":"Page number, defaults to 1."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"description":"Size of a page, defaults to 10. Maximum is 100.","default":10},"description":"Size of a page, defaults to 10. Maximum is 100."},{"name":"sort_field","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},"description":"Field to sort by, e.g., 'amount', 'scheduled_on'"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sorting direction ('asc' or 'desc')"},"description":"Sorting direction ('asc' or 'desc')"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"},"type":"array","title":"Data"},"pagination":{"properties":{"total_count":{"type":"integer","title":"Total Count"},"max_page":{"type":"integer","title":"Max Page"},"current_page":{"type":"integer","title":"Current Page"},"limit":{"type":"integer","title":"Limit"},"has_next_page":{"type":"boolean","title":"Has Next Page"},"has_previous_page":{"type":"boolean","title":"Has Previous Page"}},"type":"object","title":"Pagination"}},"type":"object","title":"ListResource[SubscriptionDetailed]"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Mark Payment As Paid

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Mark Payment As Paid"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/payments/{payment_id}/mark-paid"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Manually mark a payment as paid.

Record a payment received through manual methods (CASH, BANK_TRANSFER, CARD, or QURRAH).

**Requirements:**
- Payment must be in unpaid status (PENDING, UNDER_REVIEW, or FAILED)
- Payment method must be manual (CASH, BANK_TRANSFER, CARD, or QURRAH)
- For installment invoices, invoice must be in ACCEPTED status

Automatically completes the invoice if all payments are paid.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment to mark as paid","title":"Payment Id"},"description":"Unique identifier (UUID) of the payment to mark as paid"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_method":{"description":"Manual payment method used. Automated payment methods (e.g., MADA, VISA, MASTERCARD) are not allowed.","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"note":{"type":"string","maxLength":512,"nullable":true,"description":"Optional note or reference number for the payment (e.g., transaction ID, receipt number)"}},"type":"object","required":["payment_method"],"title":"PaymentMarkPaidRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{},"type":"object","title":"PaymentMarkPaidResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Refund Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Refund Payment"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/payments/{payment_id}/refund"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Process a refund for a payment.

Supports full refunds. The refund reason and optional note can be specified in the request.

**Note:** If the customer paid multiple payments in a single transaction, you may receive an error
(400 Bad Request) indicating multiple payments in the transaction. The error response will include
details about all related payments. In this case, set `allow_refund_multiple_related_payments` to
`true` to refund all payments that were part of the same transaction.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment to refund","title":"Payment Id"},"description":"Unique identifier (UUID) of the payment to refund"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"refund_reason":{"description":"Reason for the refund","type":"string","enum":["REQUESTED_BY_CUSTOMER","DUPLICATE","FRAUDULENT","OTHER"],"title":"PaymentRefundReason"},"refund_note":{"type":"string","maxLength":512,"nullable":true,"description":"Optional note explaining the refund reason"},"allow_refund_multiple_related_payments":{"type":"boolean","title":"Allow Refund Multiple Related Payments","description":"If true and the customer paid multiple payments at the same time (single transaction), refund all related payments instead of returning an error. Use this when attempting to refund a single payment that was part of a multi-payment transaction.","default":false}},"type":"object","required":["refund_reason"],"title":"PaymentRefundRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"scheduled_on":{"type":"string","title":"Scheduled On","description":"Scheduled date and time for the payment"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum","description":"Current status of the payment"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"refund_reason":{"nullable":true,"description":"Reason for the refund if applicable","type":"string","enum":["REQUESTED_BY_CUSTOMER","DUPLICATE","FRAUDULENT","OTHER"],"title":"PaymentRefundReason"},"refund_note":{"type":"string","nullable":true,"description":"Note explaining the refund reason if applicable"},"latest_pgw_message":{"type":"string","nullable":true,"description":"Latest payment gateway message for this payment"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentResponse"}}}},"400":{"description":"Multiple payments were paid in a single transaction. Set 'allow_refund_multiple_related_payments' to true to refund all related payments.","content":{"application/json":{"schema":{"properties":{"error":{"nullable":true,"properties":{"code":{"type":"string","enum":["STREAM_ERROR","STREAM_UNKNOWN_ERROR","PHONE_ALREADY_REGISTERED","MFA_VERIFICATION_SESSION_IN_PROGRESS","MFA_ATTEMPTS_EXHAUSTED","MFA_INVALID","MFA_SESSION_EXPIRED","MFA_CHANNEL_COOLDOWN","RECAPTCHA_INVALID","SAUDI_ID_ALREADY_REGISTERED","USER_INFO_NOT_VERIFIED","COMPANY_NOT_FOUND","ORGANIZATION_ALREADY_CREATED","USER_NOT_REGISTERED","INVALID_PARAMETERS","INVITATION_EXPIRED","USER_ALREADY_REGISTERED","PAYMENT_FLOW_NOT_ALLOWED","INVOICE_PAYMENT_COUNT_NOT_MATCHED","INVOICE_FINALISED","INVOICE_INVALID_STATUS","INVOICE_TOTAL_MISMATCH_PAYMENT_AMOUNT_SUM","INVOICE_CONSENT_CONSUMED","INVOICE_CONSENT_EXPIRED","PAYMENT_IN_PROGRESS","PAYMENT_FINALIZED","PAYMEND_UNPAID","PAYMENT_REFUNDED_ALREADY","PAYMENT_REFUNDED_FAILED","INVALID_STATUS","ACCOUNT_ONE_DEFAULT_REQUIRED","DUPLICATE_CONSUMER","DUPLICATE_PAYMENT","DUPLICATE_CARD_TOKEN","CONSUMER_HAS_ONGOING_INVOICES","CONSUMER_HAS_ONGOING_SUBSCRIPTIONS","CONSUMER_HAS_ACTIVE_PAYMENT_LINKS","MOYASAR_BAD_REQUEST","NOTIFICATION_TEMPLATE_DOES_NOT_EXIST","FEATURE_DISABLED","INSUFFICIENT_FUNDS","PAYMENT_GATEWAY_DECLINED","MANUAL_INVOICE_CARD_ID","ONE_OFF_INVALID_PAYMENT_FLOW","ONE_OFF_CARD_ID","AUTO_INVOICE_MISSING_CARD_ID","MOYASAR_INVALID_CARD_TOKEN","MOYASAR_UNAUTHORIZED","MOYASAR_FORBIDDEN","MOYASAR_NOT_FOUND","MOYASAR_METHOD_NOT_ALLOWED","MOYASAR_TOO_MANY_REQUESTS","MOYASAR_INTERNAL_SERVER_ERROR","MOYASAR_SERVICE_UNAVAILABLE","MOYASAR_PAYMENT_INFO_MISMATCH","MOYASAR_TIMEOUT","PDF_LINK_EXISTS","BRANCH_NOT_FOUND","BRANCH_ACCESS_DENIED","PERMISSION_FORBIDDEN","PRODUCT_USED_IN_FINALIZED_INVOICE","RESOURCE_ALREADY_EXISTS","COUPON_USED_IN_FINALIZED_INVOICE","CONSUMER_CONTACT_INFO_CHANGE_NOT_ALLOWED"],"title":"StreamErrorCodes"},"message":{"type":"string","title":"Message"},"additional_info":{"type":"string","nullable":true}},"type":"object","title":"StreamError"},"payment_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Payment Ids","description":"List of payment IDs that were paid in the same transaction"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount of all payments in the transaction"}},"type":"object","title":"MultiplePaymentsInTransactionErrorResponse","description":"Error response for payment refund operations when multiple payments are in a single transaction."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Uncancel Subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Uncancel Subscription"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/subscriptions/{subscription_id}/uncancel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Withdraw a pending cancellation so the subscription continues after the current billing period.

Only **ACTIVE** subscriptions are accepted.
If the subscription is not scheduled to be cancelled, the request succeeds as a no-op.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Branch

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Branch"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/branch/{branch_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update branch information.

If a branch with the same name already exists, returns an error.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"branch_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the branch to update","title":"Branch Id"},"description":"Unique identifier (UUID) of the branch to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"New name for the branch. Must be unique within the organization."}},"type":"object","required":["name"],"title":"UpdateBranchRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"user_count":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","title":"BranchItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Consumer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Consumer"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/consumers/{consumer_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update consumer information such as contact details or payment methods.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"consumer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the consumer to update","title":"Consumer Id"},"description":"Unique identifier (UUID) of the consumer to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":512,"nullable":true,"description":"Consumer name"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address"},"external_id":{"type":"string","maxLength":512,"nullable":true,"description":"External ID"},"iban":{"type":"string","maxLength":34,"title":"IBAN","nullable":true,"description":"IBAN"},"alias":{"type":"string","maxLength":512,"nullable":true,"description":"Alias"},"comment":{"type":"string","maxLength":512,"nullable":true,"description":"Comment"},"preferred_language":{"nullable":true,"description":"Preferred language","type":"string","enum":["AR","EN"],"title":"Language"},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","nullable":true,"description":"Communication methods"},"consumer_type":{"nullable":true,"description":"Consumer type: individual or business","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Address (required for business type)","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1 (building number, street name)"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2 (district)"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","required":["address_line_1","city","country"],"title":"AddressCreate"},"vat_number":{"type":"string","maxLength":64,"nullable":true,"description":"VAT number (optional for business type)"},"commercial_registration":{"type":"string","maxLength":512,"nullable":true,"description":"Commercial registration number (optional for business type)"}},"type":"object","title":"ConsumerUpdate","description":"Consumer update model with all fields optional."}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the consumer"},"external_id":{"type":"string","nullable":true,"description":"External identifier for the consumer"},"consumer":{"nullable":true,"description":"Consumer information","properties":{"id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the consumer"},"phone_number":{"type":"string","format":"phone","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"nullable":true,"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"iban":{"type":"string","nullable":true,"description":"IBAN (International Bank Account Number) of the consumer"},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"Whether the consumer has been deleted"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time when the consumer was created"},"branch":{"description":"Branch information for this consumer","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"Branch"},"comment":{"type":"string","nullable":true,"description":"Additional comments or notes about the consumer"},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","title":"Communication Methods","description":"Preferred communication methods for the consumer"},"preferred_language":{"description":"Preferred language of the consumer","type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"description":"Consumer type: individual or business","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"National address (required for business type)","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number (optional for business type)"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration number (optional for business type)"}},"type":"object","title":"BaseConsumerResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Coupon

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Coupon"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/coupons/{coupon_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update coupon details such as discount amount or active status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"coupon_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the coupon to update","title":"Coupon Id"},"description":"Unique identifier (UUID) of the coupon to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":80,"minLength":1,"nullable":true,"description":"Updated name of the coupon."},"discount_value":{"anyOf":[{"type":"number","minimum":0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Discount Value","description":"Updated discount value (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","nullable":true,"description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","nullable":true,"description":"Whether the coupon should be active or inactive."}},"type":"object","title":"CouponUpdate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Invoice In Place

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Invoice In Place"}
>
</Heading>

<MethodEndpoint
  method={"patch"}
  path={"/api/v2/invoices/{invoice_id}/inplace"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Partially update specific invoice fields in-place.

This endpoint allows updating only the fields specified in the request.
Use for quick changes such as updating the description or scheduled date.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Invoice Id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"scheduled_on":{"type":"string","format":"date-time","nullable":true,"description":"The scheduled payment date for the invoice. After this date, the invoice will be considered overdue. Must be a future date."},"description":{"type":"string","maxLength":512,"minLength":1,"nullable":true,"description":"Description of the invoice. Provides additional context or details about the invoice. Must be between 1 and 512 characters if provided."}},"type":"object","title":"InvoiceInPlaceUpdate","description":"DTO for partial in-place updates to invoice fields.\n\nThis DTO allows updating specific fields of an invoice without requiring all fields.\nOnly the fields provided will be updated. All fields are optional.\n\nNote: This endpoint performs in-place updates, unlike the full update endpoint\nwhich cancels and recreates the invoice. Use this for simple field updates."}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"invoice_number":{"type":"integer","title":"Invoice Number","description":"Global unique invoice number"},"remaining_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Remaining Amount","description":"Remaining amount to be paid"},"paid_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Paid Amount","description":"Total amount already paid"},"exclude_coupons_if_installments":{"type":"boolean","title":"Exclude Coupons If Installments","description":"Whether coupons are excluded when paying by installments"},"organization_consumer":{"description":"Consumer information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"alias":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone_number":{"type":"string","format":"phone","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"},"consumer_type":{"default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse","description":"Address response model."},"vat_number":{"type":"string","nullable":true},"commercial_registration":{"type":"string","nullable":true},"consumer":{"nullable":true,"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"phone_number":{"type":"string","format":"phone","nullable":true},"email":{"type":"string","format":"email","nullable":true},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language"}},"type":"object","title":"Consumer"},"is_deleted":{"type":"boolean","nullable":true},"communication_methods":{"items":{"type":"string","enum":["WHATSAPP","EMAIL","SMS"],"title":"ConsumerCommunicationMethod"},"type":"array","nullable":true}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"product":{"description":"Product details for this invoice item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this invoice item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"unit_price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Snapshotted unit price at invoice creation (for historical accuracy)"},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item (for traceability)"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceItemDto","description":"Invoice item response DTO.\n\nMulti-Currency Support:\n- `currency`: The currency code for this item (e.g., SAR, USD)\n- `unit_price`: Snapshotted price at invoice creation (for historical accuracy)\n- `product_price_id`: Reference to the ProductPrice used (for traceability)"},"type":"array","title":"Items","description":"List of items included in the invoice"},"branch":{"nullable":true,"description":"Branch information for this invoice","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the branch"},"name":{"type":"string","title":"Name","description":"Name of the branch"}},"type":"object","title":"BranchDto"},"payments":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Payment amount"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"scheduled_on":{"type":"string","format":"date-time","title":"Scheduled On","description":"Scheduled date and time for the payment"},"invoice_payment_number":{"type":"integer","title":"Invoice Payment Number","description":"Payment number within the invoice"},"type":{"description":"Type of payment","type":"string","enum":["INITIAL","INSTALLMENT","SPLIT_PREPAID"],"title":"PaymentTypeEnum"},"payment_method":{"nullable":true,"description":"Payment method used","type":"string","enum":["MADA","MASTERCARD","VISA","APPLE_PAY","SAMSUNG_PAY","AMEX","CASH","PGW_CARD_UNSPECIFIED","BANK_TRANSFER","CARD","QURRAH"],"title":"PaymentMethod"},"current_status":{"description":"Current status of the payment","type":"string","enum":["PENDING","PROCESSING","FAILED_INITIATION","SUCCEEDED","FAILED","CANCELED","UNDER_REVIEW","EXPIRED","SETTLED","REFUNDED"],"title":"PaymentStatusEnum"},"payed_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was completed"},"settled_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was settled"},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the payment was refunded"},"pdf_link":{"type":"string","nullable":true,"description":"URL to the payment PDF document"},"paid_to_account_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the account the payment was made to"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment amount in smallest currency unit (e.g. halala for SAR).","readOnly":true}},"type":"object","title":"PaymentDto"},"type":"array","title":"Payments","description":"List of payments associated with this invoice"},"subscription_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the subscription if this invoice is part of a subscription"},"subscription":{"nullable":true,"description":"Subscription details if this invoice is part of a subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"},"payment_methods":{"nullable":true,"description":"Payment methods available for this invoice","properties":{"mada":{"type":"boolean","title":"Mada","description":"Enable Mada payment method"},"visa":{"type":"boolean","title":"Visa","description":"Enable Visa payment method"},"mastercard":{"type":"boolean","title":"Mastercard","description":"Enable Mastercard payment method"},"amex":{"type":"boolean","title":"Amex","description":"Enable American Express payment method"},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"Enable bank transfer payment method"},"installment":{"type":"boolean","title":"Installment","description":"Enable installment payment option"},"qurrah":{"type":"boolean","title":"Qurrah","description":"Enable Qurrah payment method","default":false}},"type":"object","required":["mada","visa","mastercard","amex","bank_transfer","installment"],"title":"InvoicePaymentMethodDto"},"recurrence_pattern":{"nullable":true,"description":"Recurrence pattern for recurring invoices","type":"string","enum":["Hour","Day","Week","Fortnight","Month","Quarter","Half-Year","Year"],"title":"RecurrencePattern"},"parent_id":{"type":"string","format":"uuid4","nullable":true,"description":"Parent invoice ID for recurring invoices"},"custom_field_answers":{"additionalProperties":true,"type":"object","nullable":true,"description":"Answers to custom fields collected for this invoice"},"url":{"type":"string","title":"Url","description":"URL to access the invoice"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true},"remaining_amount_in_smallest_unit":{"type":"integer","title":"Remaining Amount In Smallest Unit","description":"Remaining amount in smallest currency unit.","readOnly":true},"paid_amount_in_smallest_unit":{"type":"integer","title":"Paid Amount In Smallest Unit","description":"Paid amount in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Payment Link Coupons

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Payment Link Coupons"}
>
</Heading>

<MethodEndpoint
  method={"patch"}
  path={"/api/v2/payment_links/{payment_link_id}/coupons"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update link-level and item-level coupons on a payment link.

Recomputes totals. New checkouts use the updated coupons;
payments already in progress are unchanged.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment link to update","title":"Payment Link Id"},"description":"Unique identifier (UUID) of the payment link to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Coupons","description":"Link-level coupons (replaces existing). Omit or [] clears link-level coupons."},"items":{"items":{"properties":{"payment_link_item_id":{"type":"string","format":"uuid4","title":"Payment Link Item Id","description":"Id of an existing payment link item"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Coupons","description":"Item-level coupons for this item (replaces existing). Omit or [] clears item-level coupons on this item."}},"type":"object","required":["payment_link_item_id"],"title":"UpdatePaymentLinkCouponItemDto"},"type":"array","title":"Items","description":"Item-level coupons per item listed; omitted items assume no coupons."}},"type":"object","title":"UpdatePaymentLinkCouponsDto"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link"},"name":{"type":"string","title":"Name","description":"Name of the payment link"},"description":{"type":"string","nullable":true,"description":"Description of the payment link"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total payment link amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original payment link amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the payment link","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation; for SAR links or when converted from other currencies."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate from link currency to home currency (SAR) at creation time"},"max_number_of_payments":{"type":"integer","nullable":true,"description":"Maximum number of times this payment link can be used"},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"UTC datetime after which the payment link is no longer valid"},"confirmation_message":{"type":"string","nullable":true,"description":"Message to display to the payer after successful payment"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this payment link creates a subscription","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring payments"},"trial_period_days":{"type":"integer","nullable":true,"description":"Free trial duration (in days) for subscriptions created from this link. Only meaningful for recurring (subscription) products. When set, each consumer who subscribes via this link gets a free trial of this length, after which the first real billing period begins. Must be between 1 and 365."},"status":{"description":"Current status of the payment link","type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the payment link"},"organization_consumer_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the organization consumer if linked to a specific consumer"},"deactivate_message":{"type":"string","nullable":true,"description":"Message to display when the payment link is deactivated"},"custom_fields":{"type":"object","title":"properties","description":"Custom fields schema for collecting additional information","example":{"properties":{"child_name":{"title":"Child Name","type":"string"},"parent_email":{"title":"Parent Email","type":"string"}},"required":["child_name"],"type":"object"},"nullable":true},"success_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a successful payment"},"failure_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a failed payment"},"custom_metadata":{"additionalProperties":{"title":"JsonValue"},"type":"object","nullable":true,"description":"The key-value metadata dictionary passed during creation."},"contact_information_type":{"nullable":true,"description":"Type of contact information required for payment collection","type":"string","enum":["PHONE","EMAIL"],"title":"ContactInformationType"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this payment link item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."},"allow_custom_quantity":{"type":"boolean","title":"Allow Custom Quantity","description":"Whether customers can select custom quantity for this item","default":false},"min_quantity":{"type":"integer","nullable":true,"description":"Minimum quantity allowed if allow_custom_quantity is True"},"max_quantity":{"type":"integer","nullable":true,"description":"Maximum quantity allowed if allow_custom_quantity is True"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item, if any"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkItemDto"},"type":"array","title":"Items","description":"List of products included in the payment link"},"coupons":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"},"type":"array","title":"Coupons","description":"List of coupons applied to the payment link"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this payment link","properties":{"visa":{"type":"boolean","title":"Visa","description":"visa is enabled","default":false},"mastercard":{"type":"boolean","title":"Mastercard","description":"mastercard is enabled","default":false},"amex":{"type":"boolean","title":"Amex","description":"amex is enabled","default":false},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"bank_transfer is enabled","default":false},"installment":{"type":"boolean","title":"Installment","description":"installment is enabled","default":false}},"type":"object","title":"PaymentMethodDto"},"url":{"type":"string","title":"Url","description":"Public URL of the payment link for sharing with payers"},"amount_collected":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Collected","description":"Total amount collected from payments"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment link amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original payment link amount (before discounts) in smallest currency unit.","readOnly":true},"amount_collected_in_smallest_unit":{"type":"integer","title":"Amount Collected In Smallest Unit","description":"Total amount collected in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Payment Link Status

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Payment Link Status"}
>
</Heading>

<MethodEndpoint
  method={"patch"}
  path={"/api/v2/payment_links/{payment_link_id}/status"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update the status of a payment link.

Allows activating or deactivating a payment link. When deactivated, the link will no longer
accept new payments. Existing payments in progress are not affected.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"payment_link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the payment link to update","title":"Payment Link Id"},"description":"Unique identifier (UUID) of the payment link to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus","description":"New status for the payment link"},"deactivate_message":{"type":"string","maxLength":512,"nullable":true,"description":"Optional message to display when the payment link is deactivated"}},"type":"object","required":["status"],"title":"UpdatePaymentLinkStatusDto"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link"},"name":{"type":"string","title":"Name","description":"Name of the payment link"},"description":{"type":"string","nullable":true,"description":"Description of the payment link"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total payment link amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original payment link amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the payment link","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation; for SAR links or when converted from other currencies."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate from link currency to home currency (SAR) at creation time"},"max_number_of_payments":{"type":"integer","nullable":true,"description":"Maximum number of times this payment link can be used"},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"UTC datetime after which the payment link is no longer valid"},"confirmation_message":{"type":"string","nullable":true,"description":"Message to display to the payer after successful payment"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this payment link creates a subscription","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring payments"},"trial_period_days":{"type":"integer","nullable":true,"description":"Free trial duration (in days) for subscriptions created from this link. Only meaningful for recurring (subscription) products. When set, each consumer who subscribes via this link gets a free trial of this length, after which the first real billing period begins. Must be between 1 and 365."},"status":{"description":"Current status of the payment link","type":"string","enum":["INACTIVE","ACTIVE","COMPLETED"],"title":"PaymentLinkStatus"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the payment link"},"organization_consumer_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the organization consumer if linked to a specific consumer"},"deactivate_message":{"type":"string","nullable":true,"description":"Message to display when the payment link is deactivated"},"custom_fields":{"type":"object","title":"properties","description":"Custom fields schema for collecting additional information","example":{"properties":{"child_name":{"title":"Child Name","type":"string"},"parent_email":{"title":"Parent Email","type":"string"}},"required":["child_name"],"type":"object"},"nullable":true},"success_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a successful payment"},"failure_redirect_url":{"type":"string","nullable":true,"description":"URL to redirect the payer to after a failed payment"},"custom_metadata":{"additionalProperties":{"title":"JsonValue"},"type":"object","nullable":true,"description":"The key-value metadata dictionary passed during creation."},"contact_information_type":{"nullable":true,"description":"Type of contact information required for payment collection","type":"string","enum":["PHONE","EMAIL"],"title":"ContactInformationType"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the payment link item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this payment link item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."},"allow_custom_quantity":{"type":"boolean","title":"Allow Custom Quantity","description":"Whether customers can select custom quantity for this item","default":false},"min_quantity":{"type":"integer","nullable":true,"description":"Minimum quantity allowed if allow_custom_quantity is True"},"max_quantity":{"type":"integer","nullable":true,"description":"Maximum quantity allowed if allow_custom_quantity is True"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"product_price_id":{"type":"string","format":"uuid4","nullable":true,"description":"Reference to the ProductPrice used for this item, if any"},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original item amount in smallest currency unit.","readOnly":true},"discounted_amount_in_smallest_unit":{"type":"integer","title":"Discounted Amount In Smallest Unit","description":"Discounted item amount in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkItemDto"},"type":"array","title":"Items","description":"List of products included in the payment link"},"coupons":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the coupon"},"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"Name of the coupon."},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value of the coupon (either percentage or fixed)."},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","nullable":true},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"True if the discount is a percentage, False if it is a fixed amount."},"is_active":{"type":"boolean","title":"Is Active","description":"Indicates if the coupon is currently active."}},"type":"object","title":"CouponDto"},"type":"array","title":"Coupons","description":"List of coupons applied to the payment link"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this payment link","properties":{"visa":{"type":"boolean","title":"Visa","description":"visa is enabled","default":false},"mastercard":{"type":"boolean","title":"Mastercard","description":"mastercard is enabled","default":false},"amex":{"type":"boolean","title":"Amex","description":"amex is enabled","default":false},"bank_transfer":{"type":"boolean","title":"Bank Transfer","description":"bank_transfer is enabled","default":false},"installment":{"type":"boolean","title":"Installment","description":"installment is enabled","default":false}},"type":"object","title":"PaymentMethodDto"},"url":{"type":"string","title":"Url","description":"Public URL of the payment link for sharing with payers"},"amount_collected":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Collected","description":"Total amount collected from payments"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Payment link amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original payment link amount (before discounts) in smallest currency unit.","readOnly":true},"amount_collected_in_smallest_unit":{"type":"integer","title":"Amount Collected In Smallest Unit","description":"Total amount collected in smallest currency unit.","readOnly":true}},"type":"object","title":"PaymentLinkDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Product

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Product"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/products/{product_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update product details such as name, price, or description.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the product to update","title":"Product Id"},"description":"Unique identifier (UUID) of the product to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","maxLength":160,"minLength":1,"nullable":true,"description":"Name of the product."},"description":{"type":"string","maxLength":512,"minLength":1,"nullable":true,"description":"Description of the product."},"price":{"anyOf":[{"type":"number","minimum":1},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Price","description":"[DEPRECATED] Price of the product. Use 'prices' array for multi-currency support."},"prices":{"items":{"properties":{"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"anyOf":[{"type":"number","minimum":1},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Amount","description":"Price amount (must be >= 1)"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"If True, amount includes VAT","default":true},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"If True, no VAT applies to this price","default":false}},"type":"object","required":["currency","amount"],"title":"ProductPriceInlineCreate","description":"Inline price creation for product create/update endpoints."},"type":"array","nullable":true,"description":"Prices for the product in different currencies."},"is_active":{"type":"boolean","nullable":true,"description":"Whether the product is active. If `true`, the product won't be available for purchase anymore. Existing customers will still have access to the product details in the invoice, and subscriptions will continue normally."},"type":{"nullable":true,"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring. Required for cyclic products","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","minimum":1,"nullable":true,"description":"The billing cycle multiple if the product is recurring"},"is_price_exempt_from_vat":{"type":"boolean","nullable":true,"description":"[DEPRECATED] Is the price exempt from VAT? Use VAT settings in prices[] instead."},"is_price_inclusive_of_vat":{"type":"boolean","nullable":true,"description":"[DEPRECATED] Is the price inclusive of VAT? Use VAT settings in prices[] instead."}},"type":"object","title":"ProductUpdate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto","description":"Product response DTO.\n\nThis DTO includes both legacy single-price fields and new multi-currency `prices` array\nfor backward compatibility with existing API consumers.\n\nLegacy fields (`price`, `currency`, `vat_amount`, etc.) represent the default price\nand are kept for backward compatibility. New integrations should use the `prices` array."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Subscription

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Subscription"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/subscriptions/{subscription_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update subscription items, coupons, billing interval, description, auto-cancel cycles, or payment methods.

Updatable fields:

- **Items** (products and quantities) — deferred to the next cycle.
- **Subscription-level coupons** — same deferral as items.
- **Recurring interval / interval count** (e.g. monthly ↔ yearly) — deferred to the next cycle.
- **Description** — applied immediately.
- **Until cycle number** (auto-cancel) — applied immediately.
- **Payment method overrides** — applied immediately.

Any change to items, coupons, or interval is recorded as a *pending
change* that takes effect at ``current_period_end``. The response carries a
``pending_change`` block describing the deferred change, including a
``next_invoice_preview`` and the per-line diff. If the next-cycle invoice
has already been generated and is unpaid, it is automatically cancelled
and re-issued with the new amount.

To change anything else (e.g. the consumer / payer), cancel the
subscription and create a new one. Use ``DELETE /pending-change`` to
revert a previously scheduled change before it takes effect.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription to update","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the subscription."},"items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"UUID of the product to include"},"quantity":{"type":"integer","exclusiveMinimum":0,"title":"Quantity","description":"Quantity of the product"},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","nullable":true,"description":"List of coupon UUIDs to apply for discounts on this specific item"}},"type":"object","required":["product_id","quantity"],"title":"SubscriptionItemCreateDto"},"type":"array","minItems":1,"title":"Items","description":"products to purchaseIf you want to keep existing items, include them in the list."},"coupons":{"items":{"type":"string","format":"uuid4"},"type":"array","minItems":0,"title":"Coupons","description":"coupons to apply to the subscription for discounts.If you want to keep existing coupons, include them in the list."},"until_cycle_number":{"type":"integer","minimum":1,"nullable":true,"description":"Number of billing cycles the subscription should run before it auto-cancels. If set to the current cycle, cancellation is scheduled at period end. If set to null, subscription will continue indefinitely until manually canceled."},"override_payment_methods":{"nullable":true,"description":"overriden payment methods for generated invoices for the payer - sending 'null' for any value means we should follow organization global settings for that method","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"recurring_interval":{"nullable":true,"description":"Optional new billing interval. If omitted, the current interval is preserved. Use this to flip monthly <-> yearly without re-checkout. Interval changes always take effect at the next cycle (deferred).","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","minimum":1,"nullable":true,"description":"Optional new interval multiplier. Defaults to the current value if omitted. Same deferral behavior as ``recurring_interval``."},"exclude_coupons_if_installments":{"type":"boolean","nullable":true,"description":"Optional override for the same field on the subscription."}},"type":"object","required":["items","coupons"],"title":"SubscriptionUpdate"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription"},"description":{"type":"string","nullable":true,"description":"Description of the subscription"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount","description":"Total subscription amount after discounts"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original subscription amount before discounts"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the subscription","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"remaining_days":{"type":"integer","title":"Remaining Days","description":"Number of days remaining in the current billing period"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Amount in home currency (SAR) at creation"},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at subscription creation"},"recurring_interval":{"description":"Billing cycle interval","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"Number of intervals per billing cycle (e.g., 2 for bi-monthly)"},"status":{"description":"Current status of the subscription","type":"string","enum":["INACTIVE","ACTIVE","EXPIRED","CANCELED","FROZEN","TRIALING","TRIAL_PENDING"],"title":"SubscriptionStatus"},"current_period_start":{"type":"string","format":"date-time","title":"Current Period Start","description":"Start date and time of the current billing period"},"current_period_end":{"type":"string","format":"date-time","title":"Current Period End","description":"End date and time of the current billing period"},"current_cycle_number":{"type":"integer","title":"Current Cycle Number","description":"Current cycle number of the subscription"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","description":"Whether the subscription will be canceled at the end of the current period"},"cancel_at_cycle_number":{"type":"integer","nullable":true,"description":"Cycle number at which the subscription will be automatically canceled"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription started"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the subscription ended"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the subscription"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"latest_invoice_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the most recent invoice for this subscription"},"trial_period_days":{"type":"integer","nullable":true,"description":"Number of days for the free trial period"},"trial_end":{"type":"string","format":"date-time","nullable":true,"description":"Date and time when the trial period ends"},"organization_consumer":{"nullable":true,"description":"Consumer information for this subscription","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the organization consumer"},"name":{"type":"string","title":"Name","description":"Name of the consumer"},"alias":{"type":"string","nullable":true,"description":"Alias of the consumer"},"email":{"type":"string","nullable":true,"description":"Email address of the consumer"},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the consumer"},"preferred_language":{"type":"string","enum":["AR","EN"],"title":"Language","nullable":true,"description":"Preferred language of the consumer"},"consumer_type":{"description":"Consumer type (individual or business)","default":"INDIVIDUAL","type":"string","enum":["INDIVIDUAL","BUSINESS"],"title":"OrganizationConsumerType"},"address":{"nullable":true,"description":"Business address for business consumers","properties":{"address_line_1":{"type":"string","title":"Address Line 1","description":"Address line 1"},"address_line_2":{"type":"string","nullable":true,"description":"Address line 2"},"city":{"type":"string","title":"City","description":"City"},"postal_code":{"type":"string","nullable":true,"description":"Postal code"},"country":{"type":"string","title":"Country","description":"Country"}},"type":"object","title":"AddressResponse"},"vat_number":{"type":"string","nullable":true,"description":"VAT number for business consumers"},"commercial_registration":{"type":"string","nullable":true,"description":"Commercial registration for business consumers"}},"type":"object","title":"OrganizationConsumer"},"items":{"items":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the subscription item"},"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Unique identifier (UUID) of the product"},"subscription_id":{"type":"string","format":"uuid4","title":"Subscription Id","description":"Unique identifier (UUID) of the subscription"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity of the product in this subscription item"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original amount before discounts"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Amount after discounts are applied"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to this item","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"product":{"description":"Product details for this subscription item","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the product"},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Name of the product."},"description":{"type":"string","maxLength":512,"nullable":true,"description":"Description of the product."},"type":{"description":"the type of product: one off or recurring","type":"string","enum":["RECURRING","ONE_OFF"],"title":"ProductType"},"recurring_interval":{"nullable":true,"description":"Represents the billing cycle interval if product is recurring","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","title":"Recurring Interval Count","description":"The billing cycle multiple if the product is recurring"},"price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price","description":"Total price including VAT (default currency)."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","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","SLL","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","XAF","XCD","XOF","XPF","XSU","XUA","YER","ZAR","ZMW","ZWL"],"maxLength":3,"minLength":3,"title":"Currency","description":"Default price currency of the product.","default":"SAR"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat","description":"Is the default price exempt from VAT?"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat","description":"Is the default price inclusive of VAT?"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat","description":"Default price excluding VAT."},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount","description":"VAT amount for default price."},"prices":{"items":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"is_active":{"type":"boolean","title":"Is Active"},"is_price_inclusive_of_vat":{"type":"boolean","title":"Is Price Inclusive Of Vat"},"is_price_exempt_from_vat":{"type":"boolean","title":"Is Price Exempt From Vat"},"price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price Excluding Vat"},"vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Vat Amount"}},"type":"object","title":"ProductPriceInlineDto","description":"Inline price DTO for product responses."},"type":"array","title":"Prices","description":"All active prices for this product across different currencies."},"is_active":{"type":"boolean","title":"Is Active","description":"Can this product be used in invoices or subscriptions?"},"is_one_time":{"type":"boolean","title":"Is One Time","description":"Shows if the product was created to be used once, and not to be added to product cataloge"},"is_used_in_finalized_invoice":{"type":"boolean","title":"Is Used In Finalized Invoice","description":"Is the product used in a finalized invoice?","default":false}},"type":"object","title":"ProductDto"}},"type":"object","title":"SubscriptionItemDto"},"type":"array","nullable":true,"description":"List of items included in the subscription"},"latest_invoice":{"nullable":true,"description":"Most recent invoice generated for this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid4","title":"Id","description":"Unique identifier (UUID) of the invoice"},"payment_link_id":{"type":"string","format":"uuid4","nullable":true,"description":"Unique identifier (UUID) of the payment link if invoice was created from one"},"user_id":{"type":"string","format":"uuid4","title":"User Id","description":"Unique identifier (UUID) of the user who created the invoice"},"organization_id":{"type":"string","format":"uuid4","title":"Organization Id","description":"Unique identifier (UUID) of the organization"},"organization_consumer_id":{"type":"string","format":"uuid4","title":"Organization Consumer Id","description":"Unique identifier (UUID) of the organization consumer"},"account_id":{"type":"string","format":"uuid4","title":"Account Id","description":"Unique identifier (UUID) of the account"},"branch_id":{"type":"string","format":"uuid4","title":"Branch Id","description":"Unique identifier (UUID) of the branch"},"org_invoice_number":{"type":"integer","title":"Org Invoice Number","description":"Organization-specific invoice number"},"description":{"type":"string","nullable":true,"description":"Description of the invoice"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total invoice amount after discounts (in invoice currency)"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Original invoice amount before discounts (in invoice currency)"},"item_level_discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Item Level Discounted Amount","description":"Total amount discounted at the item level"},"total_vat_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total VAT amount calculated from products"},"total_price_excluding_vat":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total price excluding VAT"},"coupon_calculation_metadata":{"nullable":true,"description":"Metadata about how coupons were applied to the invoice","properties":{"coupons":{"items":{"properties":{"coupon_id":{"type":"string","title":"Coupon Id","description":"Unique identifier of the coupon"},"name":{"type":"string","title":"Name","description":"Name of the coupon"},"is_percentage":{"type":"boolean","title":"Is Percentage","description":"Whether the discount is a percentage or fixed amount"},"discount_value":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Value","description":"Discount value (percentage or fixed amount)"},"currency":{"type":"string","nullable":true,"description":"Currency code for fixed-amount coupons (e.g., SAR, USD). Null for percentage coupons."},"order":{"type":"integer","title":"Order","description":"Order in which the coupon was applied"},"amount_before_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Before Discount","description":"Amount before applying this coupon"},"discount_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Amount","description":"Discount amount applied by this coupon"},"amount_after_discount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount After Discount","description":"Amount after applying this coupon"}},"type":"object","title":"CouponMetadataDto"},"type":"array","title":"Coupons","description":"List of coupons applied and their calculation details"}},"type":"object","title":"CouponCalculationMetadataDto"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway.","default":"SAR"},"home_currency_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Total in home currency (SAR) for reporting. Equals total_amount for SAR invoices."},"home_currency_amount_actual":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Actual settled amount in home currency (SAR) after payment processing."},"exchange_rate_at_creation":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"Exchange rate used at invoice creation time (for audit). 1 for SAR invoices."},"consumer_message":{"type":"string","nullable":true,"description":"Message to display to the consumer"},"status":{"description":"Current status of the invoice","type":"string","enum":["DRAFT","CREATED","SENT","ACCEPTED","REJECTED","COMPLETED","CANCELED","EXPIRED"],"title":"InvoiceStatusEnum"},"payment_method":{"description":"Payment method for the invoice","type":"string","enum":["OPENBANKING","PAYMENTGATEWAY"],"title":"PaymentMethodEnum"},"allowed_payment_flow":{"description":"Allowed payment flow for the invoice","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"current_payment_flow":{"nullable":true,"description":"Current payment flow being used","type":"string","enum":["ALL","AUTO","MANUAL"],"title":"PaymentFlow"},"period_start":{"type":"string","format":"date-time","nullable":true,"description":"Start date and time of the billing period"},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"End date and time of the billing period"},"recurring_interval":{"nullable":true,"description":"Billing cycle interval if this is a recurring invoice","type":"string","enum":["WEEK","MONTH","SEMESTER","YEAR"],"title":"RecurringInterval"},"recurring_interval_count":{"type":"integer","nullable":true,"description":"Number of intervals per billing cycle for recurring invoices"},"type":{"nullable":true,"description":"Type of invoice","type":"string","enum":["ONE_OFF","ONE_OFF_FUTURE","RECURRING","INSTALLMENTS","PRORATION"],"title":"InvoiceType"},"total_amount_in_smallest_unit":{"type":"integer","title":"Total Amount In Smallest Unit","description":"Total invoice amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original invoice amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"InvoiceBase"},"latest_freeze":{"nullable":true,"description":"Most recent freeze period applied to this subscription","properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"},"override_payment_methods":{"nullable":true,"description":"Payment methods override for this subscription","properties":{"visa":{"type":"boolean","nullable":true,"description":"override visa from global settings"},"mastercard":{"type":"boolean","nullable":true,"description":"override mastercard from global settings"},"amex":{"type":"boolean","nullable":true,"description":"override amex from global settings"},"bank_transfer":{"type":"boolean","nullable":true,"description":"override bank_transfer from global settings"},"installment":{"type":"boolean","nullable":true,"description":"override installment from global settings"},"qurrah":{"type":"boolean","nullable":true,"description":"override qurrah from global settings"},"subscription_auto_renewal":{"type":"boolean","nullable":true,"description":"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."}},"type":"object","title":"SubscriptionPaymentMethodDto"},"pending_change":{"nullable":true,"description":"A scheduled deferred change that will be applied at current_period_end, if any","properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"Pending change identifier"},"effective_at":{"type":"string","format":"date-time","title":"Effective At","description":"When this change will take effect (subscription period end)"},"invoice_was_reissued":{"type":"boolean","title":"Invoice Was Reissued","description":"True if the next-cycle invoice had to be cancelled and recreated to reflect this change"},"target_items":{"items":{"properties":{"product_id":{"type":"string","format":"uuid4","title":"Product Id","description":"Product UUID"},"product_name":{"type":"string","title":"Product Name","description":"Product display name"},"quantity":{"type":"integer","title":"Quantity","description":"Quantity that will be billed under the new plan"},"original_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Amount","description":"Per-item original amount in subscription currency"},"discounted_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discounted Amount","description":"Per-item amount after item-level discounts"}},"type":"object","title":"PendingPlanChangeItemPreview"},"type":"array","title":"Target Items","description":"Items the subscription will have after the change is applied"},"target_subscription_coupon_ids":{"items":{"type":"string","format":"uuid4"},"type":"array","title":"Target Subscription Coupon Ids","description":"Subscription-level coupons that will be active after the change"},"target_recurring_interval":{"description":"Billing interval after the change","type":"string","enum":["WEEK","MONTH","QUARTER","YEAR"],"title":"SubscriptionRecurringInterval"},"target_recurring_interval_count":{"type":"integer","title":"Target Recurring Interval Count","description":"Billing interval multiplier after the change"},"target_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Target Amount","description":"Total amount per cycle under the new plan"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."},"current_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Current Amount","description":"Subscription's current per-cycle amount"},"delta_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Delta Amount","description":"target_amount - current_amount"},"delta_amount_per_month":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","nullable":true,"description":"target_amount - current_amount, normalised to a monthly rate. Useful for displaying interval flips in like-for-like terms."},"changes":{"items":{"properties":{"kind":{"description":"Classification of this diff entry","type":"string","enum":["PRODUCT_ADDED","PRODUCT_REMOVED","PRODUCT_REPLACED","QUANTITY_DECREASED","QUANTITY_INCREASED","COUPON_ADDED","COUPON_REMOVED","INTERVAL_CHANGED"],"title":"PendingPlanChangeDiffKind"},"label":{"type":"string","title":"Label","description":"Pre-formatted, locale-neutral label suitable for display"},"product_id":{"type":"string","format":"uuid4","nullable":true,"description":"Affected product, if applicable"},"from_value":{"type":"string","nullable":true,"description":"Pre-change value, if applicable"},"to_value":{"type":"string","nullable":true,"description":"Post-change value, if applicable"}},"type":"object","title":"PendingPlanChangeDiffEntry","description":"A single human-renderable diff row, computed server-side."},"type":"array","title":"Changes","description":"Human-renderable, server-computed list of changes"},"next_invoice_preview":{"description":"Fully precomputed next invoice that will be billed under the new plan","properties":{"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Period start of the next invoice"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Period end of the next invoice"},"issue_at":{"type":"string","format":"date-time","title":"Issue At","description":"When the next invoice will be issued (notification time)"},"due_at":{"type":"string","format":"date-time","title":"Due At","description":"When the next invoice will be due"},"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal","description":"Subtotal before discounts"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total","description":"Sum of all discounts"},"total_amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount","description":"Total amount payable"},"currency":{"type":"string","enum":["SAR","USD","EUR","GBP","AED","BHD","KWD","OMR","QAR"],"title":"CurrencyCode","description":"ISO 4217 currency codes supported by Moyasar.\n\nIncludes all currencies supported by Moyasar payment gateway."}},"type":"object","title":"NextInvoicePreview"}},"type":"object","title":"PendingPlanChange"},"amount_in_smallest_unit":{"type":"integer","title":"Amount In Smallest Unit","description":"Subscription amount in smallest currency unit (e.g. halala for SAR).","readOnly":true},"original_amount_in_smallest_unit":{"type":"integer","title":"Original Amount In Smallest Unit","description":"Original subscription amount (before discounts) in smallest currency unit.","readOnly":true}},"type":"object","title":"SubscriptionDetailed"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Update Subscription Freeze

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Subscription Freeze"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/subscriptions/{subscription_id}/freeze/{freeze_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update an existing subscription freeze period.

Allows modifying the start and end dates of a freeze period. The subscription will remain
frozen during the updated period.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the subscription","title":"Subscription Id"},"description":"Unique identifier (UUID) of the subscription"},{"name":"freeze_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Unique identifier (UUID) of the freeze period to update","title":"Freeze Id"},"description":"Unique identifier (UUID) of the freeze period to update"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime","description":"freeze_start_datetime is always provided even if it dont change"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true,"description":"freeze_end_datetime is optional, if provided, it must be greater than freeze_start_datetime "},"notes":{"type":"string","nullable":true,"description":"Optional notes explaining the reason for the freeze"}},"type":"object","required":["freeze_start_datetime","freeze_end_datetime"],"title":"FreezeSubscriptionUpdateRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp of the object."},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp of the object."},"id":{"type":"string","format":"uuid","title":"Id"},"freeze_start_datetime":{"type":"string","format":"date-time","title":"Freeze Start Datetime"},"freeze_end_datetime":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"invoice_id":{"type":"string","format":"uuid","title":"Invoice Id"},"duration":{"type":"integer","nullable":true}},"type":"object","title":"FreezeSubscriptionBase"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>

---

## Express SDK


For the complete Express SDK documentation, please visit our GitHub repository:

**[📦 @streamsdk/express on GitHub →](https://github.com/streampayments/streamsdk-express)**

## Quick Links

- **[Installation & Quick Start](https://github.com/streampayments/streamsdk-express#installation)**
- **[API Documentation](https://github.com/streampayments/streamsdk-express#api-documentation)**
- **[Code Examples](https://github.com/streampayments/streamsdk-express/tree/main/examples)**
- **[Demo Application](https://github.com/streampayments/stream-express-sdk-demo)**
- **[npm Package](https://www.npmjs.com/package/@streamsdk/express)**

## Overview

The Stream Express SDK provides a clean, declarative way to integrate Stream payments into your Express.js applications. Built on top of [@streamsdk/typescript](https://www.npmjs.com/package/@streamsdk/typescript), it offers drop-in handlers for checkout flows and webhook processing.

**Key Benefits:**

- 🚀 **Simple Integration** - Add payment processing in minutes
- 🔒 **Type-Safe** - Full TypeScript support with type definitions
- 🎯 **Event-Driven** - Clean event handlers for webhook processing
- 🔄 **Flexible** - Supports guest and authenticated checkout flows
- 📦 **Lightweight** - Minimal dependencies (~7KB)
- 🔗 **Auto-Updates** - Inherits stream-sdk updates automatically

## Installation

```bash
npm install @streamsdk/express
```

## Quick Example

```typescript

const app = express();
app.use(express.json());

// Payment link handler
app.get("/checkout", Checkout({
  apiKey: process.env.STREAM_API_KEY!,
  successUrl: "https://myapp.com/success",
  returnUrl: "https://myapp.com/cancel",
}));

// Webhook handler with events
app.post("/webhooks/stream", Webhooks({
  apiKey: process.env.STREAM_API_KEY!,
  onPaymentSucceeded: async (data) => {
    console.log("Payment succeeded:", data);
    // Update your database, send confirmation emails, etc.
  },
  onPaymentFailed: async (data) => {
    console.log("Payment failed:", data);
  },
  onInvoiceCreated: async (data) => {
    console.log("Invoice created:", data);
  },
}));

app.listen(3000);
```

For complete documentation, examples, and API reference, visit the [GitHub repository](https://github.com/streampayments/streamsdk-express).

## Demo Application

Want to see it in action? Clone and run the **[Express SDK demo repository](https://github.com/streampayments/stream-express-sdk-demo)** locally for a quick working example.

## Related SDKs

- **[TypeScript SDK](/sdks/typescript)** - Core SDK for Node.js/TypeScript
- **[API Reference](/api)** - REST API documentation
- **[Webhooks Guide](/webhooks)** - Webhook event reference

---

## TypeScript SDK


For the complete TypeScript SDK documentation, please visit our GitHub repository:

**[📦 @streamsdk/typescript on GitHub →](https://github.com/streampayments/streamsdk-typescript)**

## Quick Links

- **[Installation & Quick Start](https://github.com/streampayments/streamsdk-typescript#installation)**
- **[API Documentation](https://github.com/streampayments/streamsdk-typescript#api-documentation)**
- **[Code Examples](https://github.com/streampayments/streamsdk-typescript/tree/main/examples)**
- **[npm Package](https://www.npmjs.com/package/@streamsdk/typescript)**

## Overview

The Stream TypeScript SDK provides a complete Node.js/TypeScript interface for:

- 🔐 Secure API Key authentication
- 👥 Customer (Consumer) management
- 📦 Product catalog management
- 💳 Payment link creation
- 🔄 Subscription handling
- 🧾 Invoice generation
- 🎟️ Coupon & discount management

## Installation

```bash
npm install @streamsdk/typescript
```

## Quick Example

```typescript

const client = StreamSDK.init(process.env.STREAM_API_KEY!);

const result = await client.createSimplePaymentLink({
  name: "Monthly Subscription",
  amount: 99.99,
  consumer: {
    email: "customer@example.com",
    name: "Ahmad Ali",
    phone: "+966501234567",
  },
  product: {
    name: "Premium Plan",
    price: 99.99,
  },
  successRedirectUrl: "https://yourapp.com/success",
  failureRedirectUrl: "https://yourapp.com/failure",
});

console.log("Payment URL:", result.paymentUrl);
```

For complete documentation, examples, and API reference, visit the [GitHub repository](https://github.com/streampayments/streamsdk-typescript).

## Related SDKs

- **[Express.js SDK](/sdks/express)** - Framework adapter for Express.js applications
- **[API Reference](/api)** - REST API documentation