### Express SDK Quick Example: Checkout and Webhooks

Source: https://docs.streampay.sa/sdks/express

Demonstrates a basic Express.js application setup using the Stream Express SDK. It includes a route for handling checkout redirects and another for processing incoming webhooks from Stream, with specific handlers for payment success, failure, and invoice creation.

```typescript
import express from "express";
import { Checkout, Webhooks } from "@streamsdk/express";

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);
```

--------------------------------

### Express SDK Checkout and Webhook Example

Source: https://context7_llms

Demonstrates a basic Express.js application setup using the Stream Express SDK. It includes handlers for creating payment links via the '/checkout' route and processing webhook events from Stream via the '/webhooks/stream' route. Requires setting the STREAM_API_KEY environment variable.

```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);
```

--------------------------------

### Python Examples

Source: https://context7_llms

Practical examples demonstrating how to interact with the StreamPay API using Python's `requests` library for pagination, global search, and advanced filtering.

```APIDOC
## Python Examples

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

### 1. Basic Pagination

Fetching the first page of results with a custom limit.

```python
import requests

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

response = requests.get(
    BASE_URL,
    headers={"Authorization": f"Bearer {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
import requests

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

response = requests.get(
    BASE_URL,
    headers={"Authorization": f"Bearer {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
import requests

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

response = requests.get(
    BASE_URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "invoice_id": "73b89d47-1bb1-443c-9a4c-f0ee23e22191",
        "statuses": ["PENDING", "PROCESSING"]
    }
)

payments = response.json()["data"]
print(f"Retrieved {len(payments)} payments matching the criteria.")
```
```

--------------------------------

### API Request with Pagination and Sorting

Source: https://context7_llms

Example of an HTTP GET request to the API to fetch products, demonstrating the use of pagination parameters (page, limit) and sorting parameters (sort_field, sort_direction).

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

--------------------------------

### Install Express SDK

Source: https://docs.streampay.sa/sdks/express

Installs the Express SDK package using npm. This is the first step to integrating Stream payments into your Express application.

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

--------------------------------

### Install TypeScript SDK

Source: https://docs.streampay.sa/sdks/typescript

Installs the Stream App TypeScript SDK using npm. This is the first step to integrating the SDK into your Node.js or TypeScript project.

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

--------------------------------

### Webhook Payload Example with Payment Link Data

Source: https://docs.streampay.sa/webhooks

An example of a webhook payload for a successful payment, including details about the associated invoice, payment, and payment link. It also showcases metadata which can contain custom fields and campaign information.

```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"
}
```

--------------------------------

### API Request with Filtering by Invoice ID and Statuses

Source: https://context7_llms

Example of an HTTP GET request to filter payments by a specific invoice ID and multiple statuses. It shows how to pass an array of values for a filter parameter.

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

--------------------------------

### POST /api/v2/products

Source: https://docs.streampay.sa/api/v2-products-create

This endpoint allows you to create a new product with its associated pricing and description.

```APIDOC
## POST /api/v2/products

### Description
Create a new product with pricing and description.

### Method
POST

### Endpoint
/api/v2/products

### Parameters
#### Request Body
- **name** (string) - Required - The name of the product.
- **description** (string) - Optional - A detailed description of the product.
- **price** (number) - Required - The price of the product.
- **currency** (string) - Required - The currency of the price (e.g., USD, EUR).

### Request Example
```json
{
  "name": "Example Product",
  "description": "This is a sample product for demonstration purposes.",
  "price": 19.99,
  "currency": "USD"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created product.
- **name** (string) - The name of the product.
- **description** (string) - The description of the product.
- **price** (number) - The price of the product.
- **currency** (string) - The currency of the price.
- **created_at** (string) - The timestamp when the product was created.

#### Response Example
```json
{
  "id": "prod_12345abcde",
  "name": "Example Product",
  "description": "This is a sample product for demonstration purposes.",
  "price": 19.99,
  "currency": "USD",
  "created_at": "2024-01-01T12:00:00Z"
}
```

#### Error Response (422)
- **message** (string) - A message describing the validation error.
- **errors** (object) - An object containing specific field validation errors.
```

--------------------------------

### Payment Settings Configuration

Source: https://context7_llms

Configure default installment settings for invoices and payment links. This includes enabling/disabling installments and setting available split options.

```APIDOC
## Payment Settings Configuration

### Description
Configure default installment settings for invoices and payment links. This includes enabling/disabling installments and setting available split options. The minimum installment amount is 100 SAR per installment.

### Method
PUT

### Endpoint
/settings/payment-settings

### Parameters
#### Request Body
- **installments_enabled_invoices** (boolean) - Optional - Enable or disable installments for invoices.
- **installments_enabled_payment_links** (boolean) - Optional - Enable or disable installments for payment links.
- **available_split_options** (array) - Optional - An array of integers representing the number of installments (e.g., [2, 3, 4]).

### Request Example
```json
{
  "installments_enabled_invoices": true,
  "installments_enabled_payment_links": true,
  "available_split_options": [2, 3, 4]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of settings update.

#### Response Example
```json
{
  "message": "Payment settings updated successfully."
}
```
```

--------------------------------

### Initialize Checkout Middleware (Express)

Source: https://context7_llms

Demonstrates initializing the Checkout middleware in an Express.js application, providing the API key as a configuration option. Other configuration options can also be passed.

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

--------------------------------

### Create Payment Link with TypeScript SDK

Source: https://docs.streampay.sa/sdks/typescript

Demonstrates how to initialize the Stream SDK with an API key and create a simple payment link. This example shows how to define payment details, consumer information, product details, and redirect URLs. It requires the STREAM_API_KEY environment variable to be set.

```typescript
import StreamSDK from "@streamsdk/typescript";

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

const result = await client.createSimplePaymentLink({
  name: "Monthly Subscription",
  amount: 99.99,
  consumer: {
    email: "[email protected]",
    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);
```

--------------------------------

### Payment Links API - Installment Configuration

Source: https://context7_llms

This section details how to enable or disable installments for specific payment links using the Payment Links API.

```APIDOC
## API (Payment Links) - Installment Configuration

### Description
When creating a payment link via the Payment Links API, you can enable or disable installments by including the `payment_methods` parameter in your request. This setting overrides the organization's default payment link installment settings.

### Method
POST

### Endpoint
`/api/v2-payment-links-create`

### Parameters
#### Request Body
- **payment_methods** (object) - Optional - Specifies the payment methods available for the payment link.
  - **installment** (boolean) - Optional - Set to `true` to enable installments or `false` to disable them for this payment link. If omitted, the organization's default settings are used.

### Request Example (Enable Installments)
```json
{
  "amount": 100000,
  "currency": "SAR",
  "description": "Payment for services",
  "payment_methods": {
    "card": true,
    "bank_transfer": false,
    "apple_pay": false,
    "installments": true 
  }
}
```

### Request Example (Disable Installments)
```json
{
  "amount": 100000,
  "currency": "SAR",
  "description": "Payment for services",
  "payment_methods": {
    "card": true,
    "bank_transfer": false,
    "apple_pay": false,
    "installments": false 
  }
}
```

### Response
#### Success Response (200)
- **payment_link_id** (string) - The ID of the created payment link.
- **url** (string) - The URL for the payment link.

#### Response Example
```json
{
  "payment_link_id": "pl_abc123xyz789",
  "url": "https://pay.stream.co/pay/pl_abc123xyz789"
}
```
```

--------------------------------

### Initialize Stream SDK (TypeScript)

Source: https://context7_llms

Shows how to initialize the Stream SDK in TypeScript, passing the API key during client initialization. Assumes the API key is stored in an environment variable.

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

--------------------------------

### POST /api/v2/products

Source: https://context7_llms

Creates a new product with specified pricing, description, and recurrence settings. Supports both one-time and recurring products.

```APIDOC
## POST /api/v2/products

### Description
Create a new product with pricing and description. This endpoint allows for the creation of both one-time and recurring products, with detailed options for pricing, VAT, and recurrence intervals.

### Method
POST

### Endpoint
/api/v2/products

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - Name of the product. Max length 160, min length 1.
- **description** (string) - Optional - Description of the product. Max length 500.
- **price** (number or string) - Required - Price of the product. Can be a number or a string representing a number. Must be a minimum of 1 if a number.
- **is_one_time** (boolean) - Optional - Will this product be used only one time in one invoice? Defaults to false.
- **type** (string) - Required - The type of product: 'RECURRING' or 'ONE_OFF'.
- **recurring_interval** (string) - Optional - Represents the billing cycle interval if the product is recurring. Required for cyclic products. Enum: ['WEEK', 'MONTH', 'SEMESTER', 'YEAR'].
- **recurring_interval_count** (integer) - Optional - The billing cycle multiple if the product is recurring. Minimum 1. Defaults to 1.
- **is_price_exempt_from_vat** (boolean) - Optional - Is the price exempt from VAT?
- **is_price_inclusive_of_vat** (boolean) - Optional - Is the price inclusive of VAT?

### Request Example
```json
{
  "name": "Premium Subscription",
  "description": "Monthly access to premium features.",
  "price": "19.99",
  "type": "RECURRING",
  "recurring_interval": "MONTH",
  "recurring_interval_count": 1,
  "is_price_inclusive_of_vat": true
}
```

### Response
#### Success Response (200)
- **created_at** (string) - Creation timestamp of the object.
- **updated_at** (string) - Last modification timestamp of the object.
- **id** (string) - Unique identifier (UUID) of the product.
- **name** (string) - Name of the product.
- **description** (string) - Description of the product.
- **type** (string) - The type of product: 'RECURRING' or 'ONE_OFF'.
- **recurring_interval** (string) - Represents the billing cycle interval if the product is recurring.
- **recurring_interval_count** (integer) - The billing cycle multiple if the product is recurring.
- **price** (string) - Total price including VAT.
- **currency** (string) - Price currency of the product. Defaults to 'SAR'.
- **is_active** (boolean) - Can this product be used in invoices or subscriptions?
- **is_one_time** (boolean) - Shows if the product was created to be used once, and not to be added to product catalog.
- **is_price_exempt_from_vat** (boolean) - Is the price exempt from VAT?
- **is_price_inclusive_of_vat** (boolean) - Is the price inclusive of VAT?

#### Response Example
```json
{
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": null,
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "Premium Subscription",
  "description": "Monthly access to premium features.",
  "type": "RECURRING",
  "recurring_interval": "MONTH",
  "recurring_interval_count": 1,
  "price": "19.99",
  "currency": "SAR",
  "is_active": true,
  "is_one_time": false,
  "is_price_exempt_from_vat": false,
  "is_price_inclusive_of_vat": true
}
```
```

--------------------------------

### GET /api/v2/invoices/:invoice_id

Source: https://docs.streampay.sa/api/v2-invoices-get

Retrieves detailed information about a specific invoice by its ID.

```APIDOC
## GET /api/v2/invoices/:invoice_id

### Description
Retrieve detailed information about a specific invoice by its ID.

### Method
GET

### Endpoint
/api/v2/invoices/:invoice_id

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The unique identifier of the invoice to retrieve.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **invoice_id** (string) - The unique identifier of the invoice.
- **amount** (number) - The total amount of the invoice.
- **currency** (string) - The currency of the invoice (e.g., 'SAR').
- **status** (string) - The current status of the invoice (e.g., 'paid', 'unpaid', 'expired').
- **due_date** (string) - The due date of the invoice in ISO 8601 format.
- **created_at** (string) - The timestamp when the invoice was created in ISO 8601 format.
- **updated_at** (string) - The timestamp when the invoice was last updated in ISO 8601 format.

#### Response Example
```json
{
  "invoice_id": "inv_12345abcde",
  "amount": 150.75,
  "currency": "SAR",
  "status": "unpaid",
  "due_date": "2024-12-31T23:59:59Z",
  "created_at": "2024-11-15T10:00:00Z",
  "updated_at": "2024-11-15T10:00:00Z"
}
```

#### Error Response (422)
- **message** (string) - A message describing the validation error.
- **errors** (object) - An object containing specific field validation errors.

#### Error Response Example
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "invoice_id": [
      "Invalid invoice ID format."
    ]
  }
}
```
```

--------------------------------

### Verifying Webhook Authenticity

Source: https://docs.streampay.sa/webhooks

Provides instructions and an example for verifying the authenticity of incoming webhooks using HMAC-SHA256.

```APIDOC
## Verifying Webhook Authenticity

### Description
To ensure the integrity and origin of webhook events, verify the signature provided in the `X-Webhook-Signature` header against the raw request body.

### Verification Steps

1.  Extract the `X-Webhook-Signature` header and parse it to get the `timestamp` and `signature`.
2.  Construct the message by concatenating the `timestamp` and the raw request body: `{timestamp}.{raw_request_body}`.
3.  Compute the HMAC-SHA256 hash of the constructed message using your webhook’s `secret_key`.
4.  Compare the computed signature with the `signature` value from the header. If they match, the webhook is authentic.

### Example (Python)

```python
import hmac, hashlib

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

--------------------------------

### Iterate Through All Products with Pagination (Python)

Source: https://context7_llms

Provides a robust pattern to fetch all products available through the API, handling pagination. It uses a `while` loop to continuously request pages until no more pages are available, maximizing the `limit` parameter to reduce the number of requests. The `requests` library is used for API calls.

```python
import requests

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={"Authorization": f"Bearer {API_KEY}"},
        params={"page": page, "limit": 100} 
    )
    
    body = response.json()
    all_products.extend(body["data"])
    
    if not body["pagination"]["has_next_page"]:
        break

    page += 1

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

--------------------------------

### GET /invoices/{invoice_id}

Source: https://context7_llms

Retrieves detailed information about a specific invoice.

```APIDOC
## GET /invoices/{invoice_id}

### Description
Retrieves detailed information about a specific invoice, including its payment method, recurrence pattern, parent ID for recurring invoices, custom field answers, and a URL to access the invoice.

### Method
GET

### Endpoint
/invoices/{invoice_id}

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The unique identifier of the invoice.

### Response
#### Success Response (200)
- **invoice_id** (string) - The unique identifier of the invoice.
- **amount** (number) - The total amount of the invoice.
- **currency** (string) - The currency of the invoice (e.g., 'USD', 'EUR').
- **due_date** (string) - The due date for the invoice.
- **status** (string) - The current status of the invoice (e.g., 'Draft', 'Sent', 'Paid', 'Overdue').
- **payment_method** (object) - Details about the payment method used for the invoice.
  - **type** (string) - The type of payment method (e.g., 'CreditCard', 'BankTransfer').
  - **details** (object) - Specific details related to the payment method.
- **recurrence_pattern** (string) - Optional. The recurrence pattern for recurring invoices (e.g., 'Month', 'Year').
- **parent_id** (string) - Optional. The parent invoice ID for recurring invoices.
- **custom_field_answers** (object) - Optional. Answers to custom fields collected for this invoice.
- **url** (string) - The URL to access the invoice.

#### Response Example
```json
{
  "invoice_id": "inv_123e4567-e89b-12d3-a456-426614174000",
  "amount": 150.75,
  "currency": "USD",
  "due_date": "2024-12-31",
  "status": "Sent",
  "payment_method": {
    "type": "CreditCard",
    "details": {
      "card_type": "Visa",
      "last_four": "1234"
    }
  },
  "recurrence_pattern": "Month",
  "parent_id": "inv_a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "custom_field_answers": {
    "project_code": "PROJ-XYZ",
    "internal_ref": "REF987"
  },
  "url": "https://example.com/invoices/inv_123e4567-e89b-12d3-a456-426614174000"
}
```

#### Error Response (422)
- **detail** (array) - A list of validation errors.
  - **loc** (array) - The location of the error in the request.
  - **msg** (string) - The error message.
  - **type** (string) - The type of error.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "path",
        "invoice_id"
      ],
      "msg": "Invalid invoice ID format",
      "type": "value_error"
    }
  ]
}
```
```

--------------------------------

### Make API Request with Authentication

Source: https://context7_llms

Demonstrates how to make a POST request to create a payment link using cURL, including the Base64 encoded API key in the 'x-api-key' header.

```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
  }'
```

--------------------------------

### GET /api/v2/subscriptions

Source: https://context7_llms

Retrieves a list of subscriptions with support for pagination, filtering, and sorting.

```APIDOC
## GET /api/v2/subscriptions

### Description
Lists all subscriptions with pagination, filtering, and sorting options.

### Method
GET

### Endpoint
/api/v2/subscriptions

### Parameters
#### Query Parameters
- **filters** (object) - Required - Filters for listing subscriptions. See SubscriptionListFilters for details.
  - **statuses** (array[string]) - Optional - Filter by subscription status. Possible values: 'INACTIVE', 'ACTIVE', 'EXPIRED', 'CANCELED', 'FROZEN'.
  - **latest_invoice_is_paid** (boolean) - Optional - Filter subscriptions based on whether their latest invoice is paid or partially paid.
  - **from_date** (string) - Optional - Filter by creation date from this date onwards (format: date-time).
  - **to_date** (string) - Optional - Filter by creation date up to this date (format: date-time).
  - **current_period_start_from_date** (string) - Optional - Filter subscriptions with current_period_start from this date onwards (format: date-time).
  - **current_period_start_to_date** (string) - Optional - Filter subscriptions with current_period_start up to this date (format: date-time).
  - **current_period_end_from_date** (string) - Optional - Filter subscriptions with current_period_end from this date onwards (format: date-time).
  - **current_period_end_to_date** (string) - Optional - Filter subscriptions with current_period_end up to this date (format: date-time).
  - **from_price** (number | string | null) - Optional - Limit list by minimum subscription amount inclusive.
  - **to_price** (number | string | null) - Optional - Limit list by maximum subscription amount inclusive.
  - **organization_consumer_id** (string) - Optional - Filter subscriptions belonging to a specific organization consumer (format: uuid4).
  - **search_term** (string) - Optional - Search by product name or description.
  - **product_ids** (array[string]) - Optional - Filter by a list of product IDs (format: uuid).
- **page** (integer) - Optional - Page number, defaults to 1. Must be greater than 0.
- **limit** (integer) - Optional - Size of a page, defaults to 10. Maximum is 100.
- **sort_field** (string) - Optional - Field to sort by (e.g., 'amount', 'scheduled_on').
- **sort_direction** (string) - Optional - Sorting direction ('asc' or 'desc').

### Request Body
This endpoint does not accept a request body.

### Response
#### Success Response (200)
- **subscriptions** (array) - A list of subscription objects.
- **total_count** (integer) - The total number of subscriptions matching the query.
- **page** (integer) - The current page number.
- **limit** (integer) - The number of subscriptions per page.

#### Response Example
```json
{
  "subscriptions": [
    {
      "id": "sub_123",
      "product_id": "prod_abc",
      "status": "ACTIVE",
      "amount": 1000,
      "currency": "USD",
      "created_at": "2023-10-27T10:00:00Z",
      "current_period_start": "2023-10-27T10:00:00Z",
      "current_period_end": "2023-11-27T10:00:00Z"
    }
  ],
  "total_count": 50,
  "page": 1,
  "limit": 10
}
```
```

--------------------------------

### POST /api/v2/consumers

Source: https://docs.streampay.sa/api/v2-consumers-create

Creates a new consumer with contact information and payment details.

```APIDOC
## POST /api/v2/consumers

### Description
Creates a new consumer with contact information and payment details.

### Method
POST

### Endpoint
/api/v2/consumers

### Parameters
#### Request Body
- **name** (string) - Required - The name of the consumer.
- **email** (string) - Required - The email address of the consumer.
- **phone** (string) - Optional - The phone number of the consumer.
- **address** (object) - Optional - The address of the consumer.
  - **street** (string) - Required - Street name and number.
  - **city** (string) - Required - City name.
  - **state** (string) - Required - State name.
  - **zip_code** (string) - Required - ZIP code.
  - **country** (string) - Required - Country name.

### Request Example
```json
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210",
    "country": "USA"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created consumer.
- **name** (string) - The name of the consumer.
- **email** (string) - The email address of the consumer.
- **phone** (string) - The phone number of the consumer.
- **address** (object) - The address of the consumer.

#### Response Example
```json
{
  "id": "con_12345abcde",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210",
    "country": "USA"
  }
}
```

#### Error Response (422)
- **message** (string) - A message describing the validation error.
- **errors** (object) - An object containing specific field errors.
  - **field_name** (array) - An array of error messages for the field.
```