API Overview

The StockrHub API provides programmatic access to inventory management, procurement, and stock operations. All API endpoints are accessible within the embedded Shopify app context.

API Design

The StockrHub API follows REST conventions:

• JSON-based — all request and response bodies use JSON format.
• Standard HTTP methods — GET for reading, POST for creating, PUT for updating, DELETE for removing.
• Resource-oriented URLs — endpoints are organized around resources (e.g., /api/suppliers, /api/purchase-orders).

Base URL

All API endpoints are relative to your app’s installation URL:

https://<your-app-domain>/api/...

Since StockrHub is an embedded Shopify app, API calls are made from within the Shopify admin context. The base URL is handled automatically by App Bridge.

Authentication

All API requests require authentication via Shopify session tokens. See the Authentication page for details.

Note

The API is designed to be consumed by the StockrHub frontend running inside Shopify admin. Direct external API access is not supported — all requests must originate from an authenticated Shopify session.

Rate Limits

StockrHub itself does not impose rate limits on API requests. However, operations that interact with Shopify (inventory updates, product lookups, order data) are subject to Shopify’s API rate limits:

• GraphQL Admin API: 50 points per second, with a 1,000-point bucket (throttled cost-based).
• StockrHub handles rate limit responses from Shopify automatically and will retry throttled requests.

For operations that only read from or write to StockrHub’s own database (D1), there are no rate limit constraints.

Response Format

Successful Responses

Successful responses return a JSON object with the requested data:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Example Supplier",
    "email": "[email protected]"
  }
}

For list endpoints, data is returned as an array:

{
  "success": true,
  "data": [
    { "id": 1, "name": "Supplier A" },
    { "id": 2, "name": "Supplier B" }
  ]
}

Error Responses

Error responses include an error message and appropriate HTTP status code:

{
  "success": false,
  "error": "Supplier not found"
}

HTTP Status Codes

Status Code	Meaning
200	Success — request completed successfully
201	Created — resource was created successfully
400	Bad Request — invalid parameters or missing required fields
401	Unauthorized — session token is missing or invalid
403	Forbidden — insufficient permissions
404	Not Found — requested resource does not exist
422	Unprocessable Entity — validation failed
429	Too Many Requests — Shopify rate limit exceeded
500	Internal Server Error — unexpected server error

Error Handling Best Practices

When working with the StockrHub API:

1. Always check the success field in the response body.
2. Handle HTTP status codes appropriately in your error handling logic.
3. Retry on 429 errors — these indicate Shopify rate limiting and are transient.
4. Do not retry on 4xx errors (except 429) — these indicate client-side issues that need to be fixed.
5. Log 500 errors — these indicate server-side problems that may need investigation.

Content Type

All requests that include a body must set the Content-Type header:

Content-Type: application/json

GET and DELETE requests do not require a request body.

Next Steps

• Authentication — learn how session tokens work
• API Endpoints — complete endpoint reference
• Webhooks — Shopify webhook integrations