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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.samita.io/samita-wholesale-b2b/api-integration/public-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.