Skip to content
StockrHub Docs

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

Section titled “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

Section titled “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

Section titled “Authentication”

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

Rate Limits

Section titled “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

Section titled “Response Format”

Successful Responses

Section titled “Successful Responses”

Successful responses return a JSON object with the requested data:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Example Supplier",
    "email": "supplier@example.com"
  }
}

For list endpoints, data is returned as an array:

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

Error Responses

Section titled “Error Responses”

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

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

HTTP Status Codes

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

Error Handling Best Practices

Section titled “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

Section titled “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

Section titled “Next Steps”