# Public APIs

### 1. API Usage Scope

#### a. Supported Features via API

The Public API allows interaction with the main features of the Wholesale app, including:

* **Core Features:** Wholesale Pricing, Volume Pricing, Registration form, Quick Order Form, Quick Buy Collection, Quick Buy Variant
* **Addon Features:** <mark style="color:$info;">Order Limit, Shipping Rate, Extra Fee, Payment Term (Coming soon)</mark>

#### b. Supported Methods

The API supports full CRUD operations with the following HTTP methods:

* **GET** – Retrieve data
* **POST** – Create new data
* **PUT** – Update existing data
* **DELETE** – Remove data

API keys can be granted the following permission levels: **Read Only/Write Only, Read & Write**

Supported actions include: **Get list - Get item - Create item - Update item - Delete item**

#### c. Shopify plans supported:&#x20;

The Public API of the Wholesale application is available for Shopify stores that meet the following requirements:

* Must be a **Production store** (not applicable for development or test stores)
* Must be subscribed to the **Gold plan**

***

### 2. Authentication

All API requests must be properly authenticated before being processed.

#### a. Required Parameters

Each API request must include the following mandatory parameters:

| Parameter | Description                                       |
| --------- | ------------------------------------------------- |
| `shop`    | Shopify shop domain (e.g., mystore.myshopify.com) |
| `api_key` | API key generated from the Wholesale app          |

If either of these parameters is missing, the request will be rejected.

#### b. API Key Management

API keys are created and managed directly within the Wholesale app admin interface.\
Store owners can configure specific permissions for each API key: Read only/Write only, Read & Write

***

### 3. API Structure & Response Format

#### a. API Endpoint

All API requests should use the following base URL:

```
https://wholesale.samita.io/v1/
```

#### b. Feature-Specific Endpoints

Each feature group has its own specific endpoint. For example:

* Wholesale feature:

  ```
  https://wholesale.samita.io/v1/wholesale/
  ```
* Volume Pricing feature:

  ```
  https://wholesale.samita.io/v1/volume/
  ```

(Actual endpoints may vary depending on the specific functionality.)

#### c. Supported Query Parameters

The API supports several common query parameters:

| Parameter | Description                |
| --------- | -------------------------- |
| `status`  | Status of the records      |
| `page`    | Page number for pagination |
| `limit`   | Number of records per page |
| `sort`    | Sorting criteria           |
| `query`   | Search or filter condition |

Example request:

```
GET /wholesale?page=1&limit=20&sort=created_at
```

***

### 4. Response Codes

Each API request will return one of the following status codes:

#### a. Common Error Responses

**401 – Unauthorized**

Possible reasons:

* Missing shop URL
* Missing API key
* Invalid shop URL
* Invalid API key
* API key does not match the shop

***

**403 – This action is unauthorized**

* The API key does not have permission to perform the requested action
* Insufficient permissions for View / Create / Update / Delete

***

**429 – Too Many Requests**

* Request limit has been exceeded
* API call frequency exceeds the allowed rate limit

***

#### b. Success Response

**200 – Success**

* The request is valid
* The API action was executed successfully
* Data is returned in the correct format

***

### 5. Rate Limit

To ensure system performance and stability, API usage is subject to the following limits:

| Limit Type                | Value                       |
| ------------------------- | --------------------------- |
| Maximum request frequency | **1 request per 5 minutes** |
| Daily request limit       | **50 requests per day**     |

If these limits are exceeded, the system will return:

```
429 – Too Many Requests
```