Base URL
All API requests should be made to:
https://api.shoppex.io/dev/v1
Authentication
The Shoppex API uses Bearer token authentication with API keys. Include your API key in the Authorization header:
Authorization: Bearer shx_your_api_key_here
Keep your API keys secure. Never expose them in client-side code or public repositories.
Getting Your API Key
- Log in to dashboard.shoppex.io
- Go to Settings → API Keys
- Click Generate New Key
- Copy and store your key securely (it starts with
shx_)
API keys are shown only once when created. Store them in a secure location like a password manager or environment variables.
- Use
Content-Type: application/json
- Send JSON-encoded request bodies
- Include the Authorization header
curl https://api.shoppex.io/dev/v1/invoices \
-H "Authorization: Bearer shx_your_api_key" \
-H "Content-Type: application/json"
Success Response
{
"data": {
"id": "abc123",
"status": "COMPLETED"
}
}
List Response
{
"data": [
{ "id": "abc123" },
{ "id": "def456" }
],
"pagination": {
"next_cursor": "eyJpZCI6MTIzfQ",
"has_more": true
}
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email address",
"details": [
{ "field": "email", "message": "must be a valid email" }
],
"doc_url": "https://docs.shoppex.io/api/errors#VALIDATION_ERROR"
}
}
HTTP Status Codes
| Code | Description |
|---|
200 | Success |
201 | Resource created |
400 | Bad request (validation error) |
401 | Unauthorized (invalid or missing API key) |
403 | Forbidden (shop suspended) |
404 | Resource not found |
429 | Rate limit exceeded |
500 | Internal server error |
Rate Limiting
API requests are limited to protect the service. When you exceed the limit, you’ll receive a 429 Too Many Requests response.
If rate limited, wait a few seconds before retrying your request.
List endpoints use cursor-based pagination for efficient data retrieval:
| Parameter | Type | Description |
|---|
cursor | string | Pagination cursor from previous response |
limit | number | Items per page (1-100, default: 50) |
# First request
GET /invoices?limit=25
# Next page
GET /invoices?limit=25&cursor=eyJpZCI6MTIzfQ
{
"data": [...],
"pagination": {
"next_cursor": "eyJpZCI6OTh9",
"has_more": true
}
}
has_more is false.
Filtering
Many list endpoints support filtering via query parameters:
# Filter invoices by status
GET /invoices?status=COMPLETED
# Filter by customer email
GET /[email protected]
