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: Order Limit, Shipping Rate, Extra Fee, Payment Term (Coming soon)

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:

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 a daily request limit. There is no longer a per-request/short-interval throttle — you can call the API as often as needed as long as you stay within your plan’s daily quota.

The daily limit depends on the store’s pricing plan:

Plan	Daily Request Limit
Free	5 requests/day
Starter	50 requests/day
Growth	250 requests/day
Enterprise	500 requests/day

The daily counter resets at midnight (server time) each day.

If the daily limit is exceeded, the system will return:

429 – Too Many Requests

{
  "message": "Daily request limit exceeded (X requests/day)."
}