ShopVista API Documentation

Welcome to the ShopVista REST API. This guide covers everything you need to integrate with our e-commerce platform. Our API uses standard HTTP methods, returns JSON responses, and requires authentication via Bearer tokens.

💡 Note

All API requests must include the `Authorization` header. Sandbox credentials are available in your developer dashboard.

Authentication

ShopVista uses API keys and OAuth 2.0 Bearer tokens for authentication. Include your token in the `Authorization` header of every request.

curl -X GET https://api.shopvista.com/v1/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

const response = await fetch('https://api.shopvista.com/v1/products', { method: 'GET', headers: { 'Authorization': `Bearer ${YOUR_API_KEY}`, 'Content-Type': 'application/json' } });

import requests response = requests.get( "https://api.shopvista.com/v1/products", headers={"Authorization": f"Bearer {YOUR_API_KEY}"} )

Token Scopes

Scope	Description
`products:read`	View product listings and details
`products:write`	Create, update, or delete products
`orders:read`	Retrieve order information
`orders:write`	Place or modify orders

Products

Manage your product catalog. Supports filtering, pagination, and bulk operations.

GET /v1/products

Retrieve a paginated list of products matching your query parameters.

Parameter	Type	Description
category OPTIONAL	string	Filter by category slug
min_price OPTIONAL	number	Minimum price in USD
page OPTIONAL	integer	Page number (default: 1)
limit OPTIONAL	integer	Items per page (max: 100)

curl -X GET "https://api.shopvista.com/v1/products?category=electronics&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"

{ "data": [ { "id": "prod_8xK2mP9vL4", "name": "Wireless Noise-Cancelling Headphones", "price": 89.99, "currency": "USD", "stock": 42, "category": "electronics", "created_at": "2025-01-15T08:30:00Z" } ], "pagination": { "total": 1284, "page": 1, "limit": 10 } }

POST /v1/products

Create a new product in the catalog.

{ "name": "Eco-Friendly Water Bottle", "price": 24.50, "currency": "USD", "category": "home-kitchen", "description": "Double-walled stainless steel...", "stock": 150, "images": ["https://cdn.shopvista.com/..."] }

Orders

Handle order creation, status tracking, and fulfillment updates.

POST /v1/orders

Create a new customer order. Supports multiple items, shipping addresses, and payment intents.

{ "customer_id": "cust_9Yz2Qw8mN", "items": [ { "product_id": "prod_8xK2mP9vL4", "quantity": 1 } ], "shipping_address": { "street": "123 Commerce Blvd", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country": "US" }, "payment_method": "stripe_pm_card_visa_4242" }

Webhooks

Subscribe to real-time events such as `order.created`, `payment.failed`, `inventory.low`, and `product.updated`. Configure endpoints in your dashboard or via the API.

⚠️ Important

Always verify webhook signatures using your `webhook_secret`. Unverified requests may be malicious.

Error Handling

ShopVista uses standard HTTP status codes. Errors return a JSON payload with details.

Code	Meaning	Common Cause
`400`	Bad Request	Invalid JSON or missing required fields
`401`	Unauthorized	Missing or expired API key
`403`	Forbidden	Insufficient token scopes
`404`	Not Found	Resource ID doesn't exist
`429`	Too Many Requests	Exceeded rate limits
`500`	Server Error	Internal platform issue

Rate Limits

API requests are limited to 1,000 requests per minute per API key. Headers indicate your current usage:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests left in current window
X-RateLimit-Reset: Unix timestamp when the window resets

When limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.