Summary of URL: https://docs.zid.

sa/:
## Zid APIs Documentation Summary

### Overview
Zid offers APIs that enable developers to interact with merchant stores, manage
data, and integrate customized functionalities. These APIs are designed
specifically for developers looking to build applications to help merchants
optimize their online presence.

### Key Concepts

- **Merchant APIs**: A set of endpoints that allow for direct interaction with
merchants' stores, facilitating tasks such as order management, product catalog
adjustments, and promotional settings.

- **Themes**: Documentation that assists developers in creating, customizing, and

managing visual themes for merchants' stores.

### Important APIs and Methods

#### Merchant API Capabilities
1. **Order Management**:
- Manage customer orders, including tracking reversed orders and abandoned
carts.

2. **Product Catalog Management**:

- Access and modify the product catalog, manage variants, and set product
configurations.

3. **Stock Management**:
- Monitor and adjust stock levels across various locations.

4. **Shipping Options**:
- Create and list shipping options available to stores.

5. **Promotions and Discounts**:

- Create and manage promotions and discount offers.

6. **Customer Management**:
- List customers and access profile information including addresses.

7. **Store Settings**:
- Access general store settings, payment methods, and preferences.

8. **Location-Based Settings**:
- List geographic regions for shipping and other location-dependent settings.

9. **Notifications**:
- Set up automated notifications for specific store events.

10. **Custom Scripts**:

- Allow integration of custom scripts for enhanced store functionality.

### Resources and Support

- **Getting Started Guides**: Detailed guides are available for developers to
configure their testing environment and understand dashboard features.

- **Feedback Mechanism**: Developers can submit requests for specific endpoints not
listed.

- **Support Channels**:
 - **Chat**: For instant help via the dashboard.
- **Email**: Direct support via email.
- **Slack**: Community channel for discussions.
- **Meetings**: Book meetings for technical troubleshooting.

### Important Notes

- Developers are primarily encouraged to use Python for integration with Zid APIs.
Other languages (Node.js, PHP, Ruby) are not supported or recommended for
downloading data.
- It is advisable to stay updated with the latest changes by referring to the
changelog and help center frequently.

### Conclusion
Zid provides robust APIs designed to empower developers in enhancing the
functionality of merchant online stores. Understanding the capabilities of Merchant
APIs and utilizing the available resources will aid in successful app development
and deployment.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/create-first-app:

### Zid APIs Documentation Summary

#### Overview
Zid provides APIs designed to gather data from a customer’s selling partner and
post data to the customer's selling account. This documentation outlines the
process for creating a subscription app within the Zid App Market.

### Getting Started

1. **Account Registration**: Ensure you have a registered partner account with Zid.
2. **Creating an App**:
- Navigate to “My Apps” in the Partner Dashboard.
- Click the **Create Application** button and select either **Private** or
**Public Application**.

#### App Configuration

- **App Details**: Fill in the following fields:

- **Application Name**: Name in Arabic and English.
- **App Categories**: Choose up to 3 relevant categories.
- **Application Language**: Specify supported languages (only Python is allowed).
- **Maintainer Email**: Email for merchant support.

- **OAuth Credentials**:
- **OAuth 2.0 End-Point**: URL for OAuth requests.
- **Client ID**: Unique identifier for your app.
- **Client Secret**: Secret key for authentication.

- **App Scopes**: Define the scopes required for app functionality with
justifications.

#### Essential URLs

To enable seamless access for Zid merchants, provide:
- **Application URL**: Main URL for app access.
- **Redirection URL**: URL for redirection post-installation.
- **Callback URL**: URL for OAuth communications.
#### App Description and Media
- Add a description highlighting app features and benefits for merchants.
- Provide developer information for support queries.
- Include an embedded YouTube video URL and images related to the app.
- Design a distinctive application icon for representation in Zid App Market.

#### Webhooks
- Manage app webhooks to receive real-time updates about app subscriptions.
- Specify a Webhook URL for receiving events.

#### Pricing Plans

- **Public Plans**: Define pricing plans for merchants to select from.
- **Private Plans**: Enable custom plans for merchants who require them.

#### Important Notes

- Ensure all configurations including URLs and Scopes are correctly filled to
facilitate smooth approval and deployment.
- Review all app details and links to test functionality on development stores
before publishing.
- For language support, only Python data should be downloaded or referenced; do not
utilize other languages like Node.js, PHP, or Ruby.

This summary provides a structured overview of the steps and requirements necessary
to create and manage a Zid App, focusing on Python API integration and essential
configurations.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/authorization:

### Summary of Zid APIs - Authorization

#### Key Concepts

- **OAuth 2.0**: A standard protocol for authorizing applications to access

resources securely without sharing sensitive data like passwords. Zid employs the
**authorization code grant type** which is suitable for confidential clients.

- **Tokens**:
- **Authorization Token**: Grants access to the Zid API.
- **X-MANAGER-TOKEN**: Provides access to a specific store on the Zid platform,
enhancing security for store-specific resources.
- **Access-Token**: Used interchangeably with X-MANAGER-TOKEN, particularly in
product component API endpoints.

#### Important Requirements

- Your application must run server-side to store the Client Secret securely.
- All API requests must be authorized by sending **Authorization** and **X-MANAGER-
TOKEN** headers.

#### Base URIs

- **Base API URL**: `https://api.zid.sa/v1` (for various resources)

- **Base OAuth Server URL**: `https://oauth.zid.sa` (for handling app
authentication)

#### Implementation Steps

1. **Generate Client ID and Client Secret**:
- Create an app in the Zid Partner Dashboard to retrieve the API ID and API
Secret Key.

```plaintext
Log into the Partner Dashboard → Click Apps → Create app → Fill details → Create
App → View API Keys.
```

2. **Redirect for Merchant Permission**:

- Redirect the user to the Authorization endpoint.

```php
public function redirect()
{
$queries = http_build_query([
'client_id' => 'your_client_id',
'redirect_uri' => 'http://yourapp.com/oauth/callback',
'response_type' => 'code'
]);
return redirect('https://oauth.zid.sa/oauth/authorize?' . $queries);
}
```

3. **Callback Method (Get Tokens)**:

- After receiving the authorization code, your app makes a POST request to fetch
the access token.

```python
import requests

def callback(code):
payload = {
'grant_type': 'authorization_code',
'client_id': 'your_client_id',
'client_secret': 'your_client_secret',
'redirect_uri': 'http://yourapp.com/oauth/callback',
'code': code
}
response = requests.post('https://oauth.zid.sa/oauth/token', data=payload)
return response.json()
```

- Example cURL request to obtain tokens:

```bash
curl -X POST https://oauth.zid.sa/oauth/token \
-d "grant_type=authorization_code" \
-d "client_id=your_client_id" \
-d "client_secret=your_client_secret" \
-d "redirect_uri=http://yourapp.com/oauth/callback" \
-d "code=authorization_code_received_here"
```

4. **Token Management**:
- **Authorization Token**: Sent as a header in API requests.
- **X-MANAGER-TOKEN**: Required alongside the Authorization Token in every
request.
 ```bash
curl -X GET "https://api.zid.sa/v1/resource" \
-H "Authorization: Bearer AUTH_TOKEN" \
-H "X-MANAGER-TOKEN: MANAGER_TOKEN"
```

5. **Refresh Tokens**:
- Refresh tokens before they expire (valid for 1 year).

```python
response = requests.post('https://oauth.zid.sa/oauth/token', data={
'grant_type': 'refresh_token',
'refresh_token': 'your_refresh_token',
'client_id': 'your_client_id',
'client_secret': 'your_client_secret',
'redirect_uri': 'http://yourapp.com/oauth/callback',
})
```

#### Security and Best Practices

- Store tokens securely and manage their expiration proactively.

- Monitor the expiry of the X-MANAGER-TOKEN and refresh it to maintain access.

#### Important Notes

- All API calls must be made over HTTPS.

- Tokens must be kept confidential; improper handling may lead to unauthorized
access or block your application.
- The latest API version is **v1**; older versions are deprecated.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/zid-apps-overview:

### Summary of Zid Apps Documentation

#### Overview
Zid offers a platform for developing applications that enhance online store
functionality. Developers must decide whether to create public or private apps,
both of which have distinct access and publishing processes.

#### App Types

1. **Subscription Apps**:
- Offer multiple pricing plans with ongoing services.
- Generate recurring revenue for developers.
- Can be public (available to all merchants) or private (restricted to specific
stores).

2. **Shipping Apps**:
- Facilitate integration with logistics and shipping services.
- Types include:
- **Shipping and Fulfillment Company Apps**: Manage the logistics chain
(warehousing and shipping).
- **Shipping Company Only Apps**: Focus solely on shipping.

#### Prerequisites for Developing Private Apps

- The app must not be of the "logistic" type; all logistics apps need to be public.
- The store must have a Professional or Enterprise subscription, and API Access
must be enabled.

#### App Development Cycle

1. Complete the partnership agreement (not required for private apps).
2. Follow the [step-by-step
guide](https://docs.zid.sa/docs/quick-start/pjpdjl8b750c0-create-a-shipping-app)
for app creation.
3. Utilize Zid’s APIs available in the documentation.
4. Submit for review after app development; the app will be tested before
publishing.
5. Once approved, the app is listed in the Zid App Market or installed directly for
private apps.

#### Additional Features

- **Promotions Management**: Manage promotional offers and coupons.
- **Analytics & Reporting**: Gain insights into app performance.
- **Payouts**: Access detailed monthly payout reports and invoice uploads.
- **Webhook Logs**: Monitor data exchanges and troubleshoot using webhook activity
logs.

### Important Notes

- Only Python data is to be used from the available language options (no Node.js,
PHP, Ruby).
- Ensure to follow API release notes for updates and changes.
- Consider local regulations and compliance when integrating shipping and
fulfillment services.

This summary encapsulates the critical aspects a developer needs to understand in

order to successfully develop and integrate apps within the Zid ecosystem.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/responses:

# Summary of Zid API Responses Documentation

## API Response Codes, Error Handling, and Best Practices

Zid API adheres to REST principles. This section provides an overview of HTTP
response codes, error handling mechanisms, and best practices for developers.

### Success Response Codes

| Status Code | Meaning | Usage

|
|-------------|-----------------------------------------------------|--------------
----------------------------------|
| **200** | OK - Request was successful, returning data. | Use when the
request succeeds and returns data.|
| **201** | Created - New resource created. | Use after
adding a new resource to the database.|
| **202** | Accepted - Request accepted for processing. | Use for
asynchronous processes. |
| **204** | No Content - Request successful, no content returned.| Use when an
action was executed successfully. |

**Example Success Response:**

```json
{
 "status": 200,
"success": true,
"data": {
"message": "Request processed successfully.",
"code": 200
}
}
```

### Client Error Response Codes

| Status Code | Meaning | Troubleshooting

Tips |
|-------------|------------------------------------------------|-------------------
-------------------------------------|
| **400** | Bad Request - Invalid syntax. | Check syntax and
ensure required fields are included. |
| **401** | Unauthorized - Authentication required. | Verify API keys or
credentials. |
| **403** | Forbidden - Request understood but not authorized.| Ensure user has
necessary permissions. |
| **404** | Not Found - Resource does not exist. | Double-check the
URL and resource ID. |
| **405** | Method Not Allowed - Invalid HTTP method. | Verify correct
HTTP method usage. |
| **422** | Validation Failed - Unable to process request. | Review submitted
data for missing/incorrect fields. |
| **429** | Too Many Requests - Rate limit exceeded. | Implement retry
logic or reduce request rate. |

**Example Client Error Response:**

```json
{
"status": 422,
"success": false,
"error": {
"code": "validation_failed",
"message": "Invalid input data.",
"fields": {
"email": [
"Email format is invalid."
],
"password": [
"Password must be at least 8 characters."
]
}
}
}
```

### Server Error Response Codes

| Status Code | Meaning | Troubleshooting Tips

|
|-------------|-------------------------------------|------------------------------
-------------|
| **500** | Internal Server Error - Unexpected condition. | Retry later,
contact support if persistent.|
| **503** | Service Unavailable - Temporary overload or maintenance. | Wait and
retry later. |

**Example Server Error Response:**

```json
{
"status": 500,
"success": false,
"error": {
"code": "server_error",
"message": "An unexpected error occurred. Please try again later."
}
}
```

### Handling Multiple Errors in 4xx Responses

When multiple errors occur, the API returns a structured response with affected
fields and their associated error messages.

**Example of Multiple Field Errors:**

```json
{
"status": 422,
"success": false,
"error": {
"code": "validation_failed",
"message": "Multiple fields have invalid data.",
"fields": {
"username": [
"Username is required."
],
"email": [
"Email format is invalid."
],
"password": [
"Password must be at least 8 characters."
],
"password_confirmation": [
"Password confirmation does not match."
]
}
}
}
```

### Best Practices for API Integration

- **Validate Inputs**: Validate inputs before sending requests to minimize errors.

- **Handle Rate Limits Gracefully**: Implement exponential backoff for handling
"Too Many Requests" responses.
- **Check for Updates**: Regularly check for API updates.
- **Use Correct HTTP Methods**: Use appropriate HTTP methods (GET, POST, PUT,
DELETE).
- **Test in a Safe Environment**: Thoroughly test integrations in a non-production
environment.

### Important Notes for Developers

- **Response Headers**: Additional context for errors may be found in response

headers. Always check these during debugging.
- **Logging**: Maintain logs of requests and responses, especially during
development for easier troubleshooting.

This summary provides essential information for using the Zid API, focusing on
response handling, best practices, and troubleshooting tips.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/start-here:

### Zid APIs Documentation Summary

#### Overview
Zid offers Merchant APIs that enable developers to interact with merchant stores,
performing various tasks such as managing products, tracking orders, setting up
webhooks, and more. As a partner, you can build and offer applications and themes
to help merchants enhance their online stores.

#### Key APIs and Their Functions

1. **Merchant API**
- **Purpose**: Interact directly with merchant stores.
- **Capabilities**:
- **Manage Customer Orders**: Track orders, including reversed and abandoned
carts.
- **Product Catalog Management**: Access, modify, and manage the store's
product listings, including variants and settings.
- **Stock Monitoring**: Adjust stock levels for products across various
locations.
- **Shipping Options**: Set up and list shipping methods for stores.
- **Promotions & Discounts**: Create and manage marketing tools like
promotions and discounts.
- **Customer Information**: List store customers, including profiles and
addresses.
- **Store Settings**: Access general store settings, payment methods, and
geographic regions for shipping.
- **Automated Notifications**: Set up notifications for specific store events.
- **Integration of Custom Scripts**: Enhance store functionality through
custom scripts.

#### Important Concepts

- **Webhooks**: Use webhooks for real-time data synchronization. Implement specific
endpoints that can be tailored upon request.
- **Custom Scripts**: Integrate scripts to enhance the functionality of stores,
allowing for automation and additional features.

#### Access and Support

- **Partner Dashboard**: After registration, partners can manage their apps, track
stores, and monitor payouts.
- **Resources Available**:
- Detailed guides and troubleshooting tips.
- Updates on platform changes.
- Options to provide feedback and suggestions.

#### Support Channels

- **Chat**: Instant help via the dashboard chat widget.
- **Email Support**: Get assistance directly through email.
- **Community Slack**: Join a Slack channel for collaboration.
- **Scheduled Meetings**: Book meetings for technical troubleshooting.

#### Notes and Caveats

- Focus on using Python for integrations and avoid other languages such as Node.js,
PHP, or Ruby as per user instructions.
- Developers are encouraged to explore the Merchant Help Center for an
understanding of dashboard features and for configuring their testing environment.

This structured summary provides essential information about Zid APIs, their
capabilities, and support resources, allowing developers to efficiently utilize the
platform for building and managing retail solutions.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/webhooks:

# Zid Webhooks Documentation Summary

## Overview
Webhooks allow you to receive real-time data updates for various events related to
customer and merchant interactions, such as order creation, customer logins, and
subscription events. The webhooks facilitate the integration of Zid APIs with
external systems by delivering notifications based on specified activities.

## Important Concepts

- **Currency Handling for Orders**: Partners must convert order totals when the
store currency differs from the order or shipping currency. The order details will
provide necessary currency types and conversion rates.

## How to Subscribe
To subscribe to webhook events:

1. Choose the desired event(s) from the Supported Webhook Events.

2. (Optional) Review the Event Conditions section for filter criteria.
3. Use the Merchant API to request the **Create a Webhook** endpoint.

### Sample Webhook Request Structure

The following JSON structure is shared by all webhook events:

```json
{
"app_id": 65,
"status": "active",
"end_date": "2021-11-11T19:36:36.000000Z",
"store_id": 12594,
"store_uuid": "afa2f0a9-7d72-4999-8bfd-5a04c6cf8e1e",
"plan_name": "Super 30",
"plan_type": "Paid",
"store_url": "http://zid.store/abcd/",
"event_name": "app.market.subscription.active",
"start_date": "2021-10-13T19:36:36.000000Z",
"amount_paid": 1150,
"old_plan_name": null,
"merchant_email": "appmarket@zid.sa",
"merchant_phone_no": "966501666607"
}
```
## Subscription Events
The following events can be subscribed to:

| Event Name | Description

|
|--------------------------------------|-------------------------------------------
----------------|
| `app.market.subscription.active` | Notification on activation of subscription
|
| `app.market.subscription.warning` | Warning 3 days before subscription expiry
|
| `app.market.subscription.suspended` | Notification on suspension of subscription
|
| `app.market.subscription.expired` | Notification 5 days after subscription
expiry |
| `app.market.subscription.renew` | Successful renewal notification before
last date |
| `app.market.application.install` | Notification on application installation
|
| `app.market.application.uninstall` | Notification on application
uninstallation |

## Merchant Events
These events notify about different activities related to orders, products, and
customers:

### Order Events

| Event Name | Description
|
|----------------------------------|-----------------------------------------------
------|
| `order.create` | Triggered when a new order is created (supports
conditions) |
| `order.status.update` | Triggered when an order's status changes
(supports conditions) |
| `order.payment_status.update` | Triggered when payment status changes
|

### Product Events

| Event Name | Description
|
|---------------------------------|------------------------------------------------
------|
| `product.create` | Triggered when a new product is created
|
| `product.update` | Triggered when a product's details are updated
|
| `product.delete` | Triggered when a product is deleted
|

### Customer Events

| Event Name | Description
|
|---------------------------------|------------------------------------------------
------|
| `customer.create` | Triggered when a new customer account is created
|
| `customer.update` | Triggered when a customer's details are updated
|
## Event Conditions
Conditions can filter webhook notifications based on specific criteria. Supported
conditions include:
- `delivery_option_id`: filters based on the delivery option ID.
- `status`: filters based on order status (e.g., new, preparing, delivered).
- `payment_method`: filters based on the payment method used (e.g., Cash On
Delivery, Credit Card).

### Example Usage for Conditions

To set conditions when creating or updating a webhook subscription:

```json
{
"conditions": {
"delivery_option_id": "55",
"payment_method": "Cash On Delivery"
}
}
```

## Important Notes
- Conditions are only supported for the `order.create` and `order.status.update`
events.
- Ensure that both currency conversion and correct condition settings are applied
to maintain accurate data handling.

This summary provides the key elements needed to utilize Zid webhooks effectively,
facilitating smooth integration for data exchanges regarding customer actions and
subscription management.
_____________________________

Summary of URL: https://docs.zid.sa/apidoc/project-613905/get-order-by-id:

### Summary of "Get Order by ID" - Zid APIs Documentation

#### API Overview

The "Get Order by ID" API allows users to retrieve a specific order from Zid by
using its unique order ID. This API is part of the Zid Merchant APIs and is
essential for accessing order details in a customer's selling account.

#### Endpoint
- **GET Request:** `v1/managers/store/orders/{order-id}/view`

#### Request Parameters

- **Path Parameters:**
- `order-id`: *required* (number) - The unique ID of the order that you want to
retrieve.

- **Header Parameters:**
- `Authorization`: *required* (string) - A Bearer token used for authenticating
the API requests. This token verifies the partner's identity.
- `X-Manager-Token`: *required* (string) - This token authenticates access to
store-related information, obtained through an OAuth mechanism.
- `Accept-Language`: *optional* (enum<string>) - Preferred language for the
response (defaults to "en").

#### Example Request

```http
GET https://api.zid.sa/v1/managers/store/orders/{order-id}/view
Authorization: Bearer {your_auth_token}
X-Manager-Token: {your_manager_token}
Accept-Language: en
```

#### Response
- **HTTP Code:** 200 (Success)
- **Content Type:** `application/json`
- **Response Schema:** The response will include the order details, and may include
the following optional fields:
- `status`: The status of the response.
- `message`: Contains additional messages or error information.

#### Key Concepts

- **Currency Handling:** If the store currency, order currency, and the currency
for cash on delivery are different, the API will provide conversion rates to ensure
correct processing. This is important for transactions involving multiple
currencies.

- **Data Masking for Marketplace Orders:** If `is_marketplace_order` is true,

certain customer information, such as name, email, and phone, will be masked for
privacy. For example:
- `customer.name` → "J*** D***"
- `customer.email` → "t***@."
- `customer.phone` → "***00" (may be null if not provided for marketplace
orders).

#### Notes and Caveats

- Ensure to include both `Authorization` and `X-Manager-Token` in the request
header for successful API calls.
- The API response may include masked information for privacy when dealing with
marketplace orders.
- The `Accept-Language` header can be used to specify the desired response
language, with English being the default.

### Conclusion
The "Get Order by ID" API provides an efficient way for developers to access order
details from a customer's selling account within the Zid platform. Proper handling
of authentication tokens and understanding of currency conversion and data privacy
practices are crucial for effective implementation.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/webhooks#supported-webhook-

events:
# Zid Webhooks Documentation Summary

## Overview
Webhooks in Zid allow you to receive real-time data updates for various events such
as order creation, customer login, and more. This guide covers supported webhook
events, payload structures, and conditions for subscriptions.

## How to Subscribe to Webhooks

1. Choose the event(s) you want to subscribe to from the Supported Webhook Events
list.
2. (Optional) If applicable, review event conditions.
3. Use the Merchant API to make a request to the **Create a Webhook** endpoint.

## Subscription Events

| Event Name | Description

|
|---------------------------------------|------------------------------------------
-------------|
| `app.market.subscription.active` | Notify on successful activation of
subscription |
| `app.market.subscription.warning` | Notify 3 days before the last
subscription date |
| `app.market.subscription.suspended` | Notify on completion of subscription
|
| `app.market.subscription.expired` | Notify 5 days after subscription expiry
(grace period)|
| `app.market.subscription.renew` | Notify 5 days before renewal of
subscription |
| `app.market.subscription.upgrade` | Notify on upgrade of subscription
|
| `app.market.subscription.refunded` | Notify on subscription refund
|
| `app.market.application.install` | Notify on application installation
|
| `app.market.application.uninstall` | Notify on application uninstallation
|

## Sample Webhook Request Structure

The request data structure for webhook events is uniform across different events
and includes the following fields:

```json
{
"app_id": 65,
"status": "active",
"end_date": "2021-11-11T19:36:36.000000Z",
"store_id": 12594,
"store_uuid": "afa2f0a9-7d72-4999-8bfd-5a04c6cf8e1e",
"plan_name": "Super 30",
"plan_type": "Paid",
"store_url": "http://zid.store/abcd/",
"event_name": "app.market.subscription.active",
"start_date": "2021-10-13T19:36:36.000000Z",
"amount_paid": 1150,
"old_plan_name": null,
"merchant_email": "appmarket@zid.sa",
"merchant_phone_no": "966501666607"
}
```

## Merchant Events

### Order Events

| Event Name | Description |

|------------------------------|-------------------------------------------------|
| `order.create` | Triggered when a new order is created |
| `order.status.update` | Triggered when an order's status is updated |
| `order.payment_status.update`| Triggered when an order's payment status changes|
### Product Events

| Event Name | Description |

|-------------------|------------------------------------------------|
| `product.create` | Triggered when a new product is created |
| `product.update` | Triggered when a product's details are updated|
| `product.publish` | Triggered when a product is published |
| `product.delete` | Triggered when a product is deleted |

### Customer Events

| Event Name | Description |

|---------------------------|-------------------------------------------------|
| `customer.create` | Triggered when a new customer account is created|
| `customer.update` | Triggered when a customer's details are updated |
| `customer.login` | Triggered when a customer logs in |

### Abandoned Cart Events

| Event Name | Description |

|----------------------------------|---------------------------------------------|
| `abandoned_cart.created` | Triggered when a cart is abandoned |
| `abandoned_cart.completed` | Triggered when an abandoned cart is completed|

### Product Category Events

| Event Name | Description |

|-------------------------|-----------------------------------------------|
| `category.create` | Triggered when a new category is created |
| `category.update` | Triggered when a category's details are updated|
| `category.delete` | Triggered when a category is deleted |

## Event Conditions
Conditions can be applied to filter webhook notifications based on specific
criteria. Currently, conditions are supported for `order.create` and
`order.status.update` events.

### Supported Condition Keys

| Condition Key | Data Type | Description | Possible

Values |
|-----------------------|-----------|------------------------------------|---------
--------------------------------|
| `delivery_option_id` | Integer | The delivery option ID in Zid | Any valid
delivery option ID |
| `status` | String | Filters based on order status | new,
preparing, ready, inDelivery, delivered, cancelled |
| `payment_method` | String | Filters based on payment method | Cash On
Delivery, Credit Card, Bank Transfer|

### Example Usage for Setting Conditions

```json
{
"conditions": {
"delivery_option_id": "55",
"payment_method": "Cash On Delivery"
}
}
```

## Important Notes
- When handling orders in multiple currencies, ensure to convert the order total to
the appropriate currency based on the order and shipping details.
- For further customization or if you require additional events or conditions,
please send suggestions to Zid App Market Support.

This summary provides developers with a concise resource for implementing and using
Zid API webhooks effectively.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/webhooks#event-conditions:

## Zid Webhooks Documentation Summary

### Overview
Zid Webhooks provide real-time data updates for various events related to merchant
activities, including order creation, customer actions, and subscription
management. This documentation covers the subscription process, event definitions,
payload structures, and conditions for filtering events.

---

### **How to Subscribe to Webhooks**

1. **Choose Events**: Select the event(s) you want to subscribe to from the list of
supported events.
2. **Set Conditions (Optional)**: If applicable, refer to the Event Conditions
section to define criteria for triggering the webhook.
3. **Create Webhook**: Use the Merchant API to make a request to the "Create a
Webhook" endpoint.

---

### **Subscription Events**

Here's a summary of the key subscription events available:

| Event Name | Description

|
|-------------------------------------|--------------------------------------------
-------------------|
| `app.market.subscription.active` | Notification on successful activation of
subscription |
| `app.market.subscription.warning` | Notification 3 days before the last
subscription date |
| `app.market.subscription.suspended` | Notification on completion of subscription
|
| `app.market.subscription.expired` | Notification 5 days after subscription
expiration |
| `app.market.subscription.renew` | Notification on successful renewal of
subscription |
| `app.market.subscription.upgrade` | Notification on subscription upgrade
|
| `app.market.subscription.refunded` | Notification on subscription refund
|
| `app.market.application.install` | Notification on application installation
|
| `app.market.application.uninstall` | Notification on application uninstallation
|

---

### **Sample Webhook Request**

Webhook requests share a common structure. Below is an example payload for webhook
notifications:

```json
{
"app_id": 65,
"status": "active",
"end_date": "2021-11-11T19:36:36.000000Z",
"store_id": 12594,
"store_uuid": "afa2f0a9-7d72-4999-8bfd-5a04c6cf8e1e",
"plan_name": "Super 30",
"plan_type": "Paid",
"store_url": "http://zid.store/abcd/",
"event_name": "app.market.subscription.active",
"start_date": "2021-10-13T19:36:36.000000Z",
"amount_paid": 1150,
"old_plan_name": null,
"merchant_email": "appmarket@zid.sa",
"merchant_phone_no": "966501666607"
}
```

---

### **Merchant Events**

Events categorized per type are as follows:

#### **Order Events**

| Event Name | Description
| Payload Schema |
|----------------------------------|-----------------------------------------------
--|-----------------------|
| `order.create` | Triggered when a new order is created.
| [Order schema] |
| `order.status.update` | Triggered when an order's status is updated.
| [Order schema] |
| `order.payment_status.update` | Triggered by changes in order's payment
status. | [Order schema] |

#### **Product Events**

| Event Name | Description
| Payload Schema |
|----------------------------------|-----------------------------------------------
--|-----------------------|
| `product.create` | Triggered when a new product is created.
| [Product schema] |
| `product.update` | Triggered when a product's details are
updated. | [Product schema] |
| `product.delete` | Triggered when a product is deleted.
| [Product deleted schema] |

#### **Abandoned Cart Events**

| Event Name | Description
| Payload Schema |
|----------------------------------|-----------------------------------------------
--|-----------------------|
| `abandoned_cart.created` | Triggered when a shopping cart is abandoned.
| [Abandoned Cart schema] |
| `abandoned_cart.completed` | Triggered when an abandoned cart is completed.
| [Abandoned Cart schema] |

#### **Customer Events**

| Event Name | Description
| Payload Schema |
|----------------------------------|-----------------------------------------------
--|-----------------------|
| `customer.create` | Triggered when a new customer account is
created. | [Customer schema] |
| `customer.update` | Triggered when customer details are updated.
| [Customer schema] |

#### **Product Category Events**

| Event Name | Description
| Payload Schema |
|----------------------------------|-----------------------------------------------
--|-----------------------|
| `category.create` | Triggered when a new category is created.
| [Category schema] |
| `category.delete` | Triggered when a category is deleted.
| [Category schema] |

---

### **Event Conditions**

Conditions allow you to filter the events that trigger the webhook notifications.
Currently, conditions are supported for `order.create` and `order.status.update`.

| Condition Key | Data Type | Description

| Possible Values |
|---------------------|-----------|------------------------------------------------
--------|--------------------------------------------------|
| `delivery_option_id`| Integer | The delivery option ID in Zid.
| Any valid delivery option ID |
| `status` | String | Filters events based on order status.
| `new`, `preparing`, `ready`, `inDelivery`, `delivered`, `cancelled` |
| `payment_method` | String | Filters events based on the payment method
used. | `Cash On Delivery`, `Credit Card`, `Bank Transfer` |

#### **Example Usage of Conditions**

Include the conditions field in the subscription request body:

```json
{
"conditions": {
"delivery_option_id": "55",
"payment_method": "Cash On Delivery"
}
}
```

---

### **Notes**
- Ensure you handle currency conversions when dealing with payments, especially if
multiple currencies are involved.
- The webhook payload structures must be adhered to as defined to guarantee
successful integrations.
- Developers should refer to the respective schemas linked with event names for
precise payload structures.

This summary provides essential information for integrating with Zid webhooks and
should serve as a concise reference for developers working with the Zid API.
_____________________________

Summary of URL: https://docs.zid.sa/apidoc/project-613905/webhook-events-order:

### Summary of Zid APIs Documentation for Order Webhook Events

#### Key Concepts

1. **Order Handling**:
- Zid APIs allow gathering data from the customer's selling partner and posting
data to the customer's selling account related to orders.
- Important to manage different currencies effectively when handling orders. The
total order amount must be converted to the appropriate currency, considering the
store currency, order currency, and shipping address currency.

2. **Currency Handling**:
- When dealing with orders, ensure the currency type and conversion rate are
utilized for proper processing.
- API responses will include both the currency type being used and the
conversion rate for accurate calculations.

3. **Webhook Payloads**:
- Some webhook payloads may contain placeholder email addresses. These addresses
are operational and will not reach actual customers, so they should not be relied
upon for communication.

#### Important Notes/Caveats

- When implementing the APIs, be aware of the need for currency conversions if
different currencies are involved in orders.
- Pay attention to the email handling in webhook responses. Placeholder emails do
not represent real customer emails.

#### Code Examples & API Snippets

The documentation did not provide specific code examples or API snippets. The focus
was on operational and handling aspects rather than direct coding interfaces. For
Python API implementations, you may refer to the general guidelines on how to
structure the requests to Zid APIs using libraries like `requests` or `httpx`.

#### Class and Method Usage

While the content did not detail specific classes or functions within the API,
understanding the handling of orders, currencies, and webhooks is crucial for
effective implementation and troubleshooting.

### Conclusion

For developers looking to integrate with the Zid APIs for order management, a clear
understanding of currency handling, webhook functionalities, and the operational
behavior of the API payloads is essential. Please consult the Zid API documentation
directly for more in-depth examples and API method specifics. Only Python language
implementations are to be considered per user instructions.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/embedded-apps:

# Zid Embedded Apps Documentation Summary

## Overview
Zid Embedded Apps allow seamless integration within the Zid Merchant Dashboard via
iframes, enhancing the user experience and ensuring merchants can access third-
party applications without leaving the platform.

## Key Benefits for Partners

- **Seamless Integration**: Applications are embedded within the Merchant
Dashboard.
- **Enhanced Visibility**: Increased exposure and engagement for applications.
- **Simplified Access**: No separate login is required.
- **Improved Security**: Utilizes Zid’s authentication and security policies.
- **Increased Adoption**: Easy integration encourages more usage.
- **Customer Loyalty**: Promotes satisfaction and long-term use.

## Authentication Flow
1. **Initial Token Storage**: After installation, partners store a token within
Zid’s system.
2. **Token Transmission**: The stored token is sent as a query parameter in the
iframe URL when a merchant accesses the app.
3. **Secure Data Handling**: Applications manage their storage (local storage and
cookies).
4. **Scope Requirement**: Include the `embedded_apps_tokens_write` scope in
authorization requests.
5. **Security Recommendations**: Update and invalidate old tokens regularly for
security integrity.

## Content Security Policy

The following Content Security Policy must be included in the HTTP response
headers:

```http
Content-Security-Policy:
style-src 'self' 'unsafe-inline' *;
font-src 'self' 'unsafe-inline' data: *;
default-src 'self' *.zid.dev web.zid.sa;
script-src 'self' 'unsafe-inline' *;
frame-ancestors 'self' *.zid.dev web.zid.sa;
connect-src 'self' 'unsafe-inline' *
```

## Token Management
### Token Expiry and Management
- Token expiry is determined by the partner.
- Regular updates to authorization tokens are recommended.

### Create / Update User Token

To update the authentication token for a merchant:
#### Endpoint
```http
POST https://api.zid.sa/v1/managers/embedded-apps-token
```

#### cURL Example

```bash
curl -X POST --location 'https://api.zid.sa/v1/managers/embedded-apps-token' \
--header 'Authorization: Bearer {{authorization_token}}' \
--header 'x-manager-token: {{x-manager-token}}' \
--header 'Content-Type: application/json' \
--data '{
"token": "{your_authorization_token_for_this_merchant}"
}'
```

### Delete User Token

To revoke access when a merchant uninstalls the application:

#### Endpoint
```http
DELETE https://api.zid.sa/v1/managers/embedded-apps-token
```

#### cURL Example

```bash
curl -X DELETE --location 'https://api.zid.sa/v1/managers/embedded-apps-token' \
--header 'Authorization: Bearer {{authorization_token}}' \
--header 'x-manager-token: {{x-manager-token}}'
```

## Important Notes
- Ensure that you only use Python SDK for integration; avoid using other languages
like Node.js, PHP, or Ruby.
- A focus on security through token management and proper implementation of the
Content Security Policy is crucial.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/doc-649611:

# Summary of Zid APIs for App Scripts

## Overview
Zid App Scripts enable the insertion of custom JavaScript into a merchant's
storefront, allowing for dynamic interactions and tailored user experiences. The
scripts can respond to various user actions in real-time through event-driven
scripting.

## Key Concepts

### Global and Customer Object Scripting

Two types of global objects are utilized:
1. **Global Object**: Loads upon page initialization.
- **Parameters**:
- `window.customer`: Contains details of the logged-in customer (empty if no
user is logged in).

2. **Customer Object**: Contains logged-in customer details.

 - **Blueprint Parameters**:
- `id`: Unique identifier for the customer.
- `name`: Full name of the customer.
- `mobile`: Mobile number.
- `email`: Email address.

### Event-Driven Scripting

Supported events that trigger specific JavaScript functions:
- **Purchase Event**
- **Product View Event**
- **Add to Cart Event**
- **Remove from Cart Event**
- **Start Checkout Event**

### Parameters for Supported Events

1. **Purchase Event**
- `transactionItems`: List of purchased products.
- Additional parameters include `id`, `product_id`, `name`, `sku`, `category`,
`price`, `quantity`, `currency`, and `total`.

2. **Product View Event**

- `productViewd`: Details of the viewed product.
- Parameters include `id`, `name`, `category`, `price`, and `position`.

3. **Add to Cart Event**

- `productCart`: Details of the added product.
- Parameters include `id`, `name`, `category`, `price`, `position`, `list`, and
`quantity`.

4. **Remove from Cart Event**

- `productCart`: Details of the removed product.
- Same as Add to Cart Event parameters.

5. **Start Checkout Event**

- Parameters include `cart_id`, `cart_total`, `currency`, `items` (with
details), `user_id`, `session_id`, `cart_discount`, `shipping_cost`,
`checkout_step`, and `payment_method`.

## API Usage and Examples

### Example JSON Representation of a Shopping Cart

```json
{
"id": 3180851825,
"session_id": "HR8XY3IyCNvs1aMKbHMMhzDfN9cKwPnl",
"sub_total_value": 29.96,
"items": [
{
"product_id": "12345",
"name": "Product Name",
"quantity": 2,
"price": 14.98
}
]
}
```

### cURL Command Example

To manage app script functionalities:
```bash
curl --location 'https://api.zid.sa/v1/managers/app-scripts' \
--header 'Accept: */*' \
--header 'Accept-Language: ar' \
--header 'Authorization: Bearer <your_token_here>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: Zid/1.113.00 (web)' \
--header 'X-MANAGER-TOKEN: <your_token_here>' \
--form 'url="https://yourdomain.com/your-script.js"' \
--form 'purchase_event="console.log(transactionItems)"' \
--form 'product_details_event="console.log(productViewed)"' \
--form 'add_to_cart_event="console.log(productCart)"' \
--form 'remove_from_cart_event="console.log(productCart)"' \
--form 'start_checkout_event="console.log(cart)"'
```
*(Replace `<your_token_here>` with actual token values.)*

## Getting Started with Script Injection

1. **App Scope and Permissions**: Ensure "Extra Addons" scope is enabled in the app
settings on the Zid Developer Dashboard.

2. **API for Script Management**:

- **Create Script**: Initiates a new script injection.
- **Retrieve Scripts**: Lists all scripts associated with a store.
- **Update Script**: Modifies an existing script.
- **Delete Script**: Removes a script.

3. **Request Injection Approval**: Contact Zid for approval after creating your
hybrid app. Once approved, subsequent scripts will be injected automatically.

## Important Notes
- The product identifiers for cart and view events have non-standard naming
conventions (e.g., `productViewd`).
- Future enhancements to supported events and improved API responses are expected,
and user feedback is encouraged for platform improvement.

This information serves as a guide for developers looking to implement Zid APIs for
script insertion and event handling within their storefronts.
_____________________________

Summary of URL: https://docs.zid.sa/project-613905/doc-644369:

### Summary of Zid APIs Rate Limiting Documentation

**Overview:**
Zid APIs allow you to interact with the customer's selling partner through data
gathering and posting. This document focuses on the Rate Limiting policies that
control the number of requests accepted within a specified timeframe to ensure
optimal performance.

---

### Rate Limiting Policy

- **New Limitation Rule:**

- When external systems call the API, there is a rate limit of **60 requests per
application per store**. This rule is currently applied only to product endpoints.

- **Quota and Throttling Policy:**

- Requests exceeding the limit are temporarily held and retried. If the maximum
retry attempts are unsuccessful, the requests are rejected.
- You can configure:
- **Retry Delay:** The time between retry attempts.
- **Retry Limit:** The maximum number of retries allowed.

### Rate Limiting Algorithm

- **Leaky Bucket Algorithm:**

- Incoming requests are queued (like filling a bucket), and the system processes
them at a consistent leak rate. If the bucket is full, incoming requests will be
rejected.

### Polling vs. Webhooks

1. **Polling:**
- Makes periodic requests to check for updates or new data.
- If no new data is present, no response will be given.

2. **Webhooks:**
- Provides immediate notifications for status updates, reducing the need for
frequent API calls.

### Important Notes

- **Avoid Frequent Requests:**

- To prevent system overload, avoid continuously checking for status updates.
Instead, use Webhook APIs for tracking orders and payments efficiently.

- **Exceptions Handling:**
- If you have a valid case that requires exceptions to the rate limit, reach out
via email with the details for evaluation.

---

### Usage Scenarios

#### Example Snippet for Rate Limit Handling (Hypothetical Python Example)

```python
import requests
import time

def call_zid_api(url, headers, data):

max_retries = 5
retries = 0
while retries < max_retries:
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
return response.json()
elif response.status_code == 429: # Rate limit exceeded
time.sleep(2 ** retries) # Exponential backoff
retries += 1
else:
raise Exception(f"API Error: {response.status_code}")
raise Exception("Max retries exceeded")
```

### Conclusion

This documentation addresses crucial aspects of using Zid APIs, particularly the
rate limiting that ensures stability and performance. Developers are urged to adopt
best practices by implementing retries and using webhooks to manage API
interactions effectively.
_____________________________