ShopVista API Documentation

Authentication

All API requests require authentication via Bearer tokens. Generate your key from the ShopVista Developer Dashboard.

🔑 API Key

Include your secret key in the Authorization header. Never expose this in client-side code.

Header

Authorization: Bearer sk_live_9f8e7d6c5b4a3210

🌐 OAuth 2.0 (For Partners)

Use OAuth for third-party marketplace integrations requiring user consent.

POST /oauth/token

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

API Reference

Core endpoints for managing your e-commerce operations.

GET /products

Retrieve a paginated list of products. Supports filtering, sorting, and category scoping.

Parameter	Type	Description
limitoptional	integer	Number of items per page (max 100)
offsetoptional	integer	Pagination offset
categoryoptional	string	Filter by category slug

Response: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "prod_8x9y7z6w",
      "name": "Wireless Noise-Canceling Headphones",
      "price": 129.99,
      "currency": "USD",
      "stock": 45,
      "status": "active"
    }
  ],
  "meta": {
    "total": 1240,
    "page": 1,
    "limit": 20
  }
}

POST /orders

Create a new order. Automatically reserves inventory and triggers payment processing.

Parameter	Type	Description
itemsrequired	array	List of line items
shipping_addressrequired	object	Destination address
customer_emailrequired	string	Recipient email

Request Body

{
  "items": [
    {
      "product_id": "prod_8x9y7z6w",
      "quantity": 2
    }
  ],
  "shipping_address": {
    "line1": "123 Commerce Ave",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US"
  },
  "customer_email": "buyer@example.com"
}

GET /orders/{order_id}/status

Track real-time order status and fulfillment details.

Response: 200 OK

{
  "success": true,
  "data": {
    "order_id": "ord_a1b2c3d4",
    "status": "shipped",
    "tracking": "1Z999AA10123456784",
    "carrier": "UPS",
    "estimated_delivery": "2024-03-15T00:00:00Z",
    "history": [
      { "event": "placed", "timestamp": "2024-03-10T14:22:00Z" },
      { "event": "shipped", "timestamp": "2024-03-12T09:15:00Z" }
    ]
  }
}

Rate Limits & Errors

API calls are throttled to ensure platform stability. Headers included in every response.

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1710345600
Retry-After: 3600 // Only present when rate limited

Plan	Requests / Hour	Burst Limit
Starter	1,000	10
Business	10,000	50
Enterprise	Unlimited	200

HTTP Status Codes

Standard REST status codes with platform-specific meanings.

200

Request succeeded. Data returned.

201

Created

Resource successfully created.

400

Bad Request

Invalid parameters or malformed JSON.

401

Unauthorized

Missing or invalid API key.

404

Not Found

Endpoint or resource doesn't exist.

429

Too Many Requests

Rate limit exceeded. Retry after header.

500

Server Error

Internal ShopVista error. Contact support.