Skip to main content
Sellvy
Back to Blog
March 15, 202612 min readSellvy Team

Sellvy API Documentation

Complete reference for the Sellvy REST API. Authenticate with API keys, manage products, orders, customers, and coupons programmatically, and receive real-time webhook events.

The Sellvy API lets you manage your store programmatically. Create products, fetch orders, update customers, and receive real-time webhook notifications — all through a clean REST interface.

Base URL

All API requests are made to:

https://api.sellvy.io/v1

Authentication

Every API request requires an API key passed in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

Creating an API Key

  1. Go to Settings → Integrations → API Keys in your dashboard.
  2. Click Create API Key.
  3. Give it a descriptive name (e.g., "Production Backend", "Inventory Script").
  4. Select the permissions this key should have (read-only, write, or full access).
  5. Copy the key immediately — it will not be shown again.

Key Types

| Prefix | Environment | Use Case | |--------|-------------|----------| | sk_live_ | Production | Real orders and data | | sk_test_ | Sandbox | Testing and development |

Test keys work against a sandboxed copy of your store. No real payments are processed.

Rate Limits

| Plan | Requests per minute | Burst limit | |------|-------------------|-------------| | Free | 60 | 10 | | Pro | 300 | 50 | | Business | 1,000 | 100 | | Enterprise | Custom | Custom |

When you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Response Format

All responses are JSON. Successful responses include a data field:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142
  }
}

Error responses include an error object:

{
  "error": {
    "code": "not_found",
    "message": "Product not found",
    "status": 404
  }
}

Endpoints

Products

List Products

GET /products

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | page | number | Page number (default: 1) | | per_page | number | Items per page (default: 25, max: 100) | | search | string | Search by title | | type | string | Filter by product type | | category_id | string | Filter by category | | visible | boolean | Filter by visibility | | sort | string | Sort field: created_at, price, title, total_sold | | order | string | Sort direction: asc or desc |

JavaScript Example:

const response = await fetch('https://api.sellvy.io/v1/products?per_page=10', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});
const { data, meta } = await response.json();
console.log(`Found ${meta.total} products`);

Python Example:

import requests

response = requests.get(
    "https://api.sellvy.io/v1/products",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
    params={"per_page": 10}
)
data = response.json()
print(f"Found {data['meta']['total']} products")

Get Product

GET /products/:id

Returns a single product with all fields including category, stock count, and variant information.

Create Product

POST /products

Request Body:

{
  "title": "Premium Icon Pack",
  "type": "digital_download",
  "price": 29.99,
  "currency": "USD",
  "description": "500+ hand-crafted icons in SVG and PNG formats.",
  "category_id": "cat_abc123",
  "is_visible": true,
  "images": ["https://..."],
  "file_url": "https://..."
}

Required fields: title, type, price

JavaScript Example:

const response = await fetch('https://api.sellvy.io/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Premium Icon Pack',
    type: 'digital_download',
    price: 29.99,
    description: '500+ hand-crafted icons'
  })
});
const { data } = await response.json();
console.log(`Created product: ${data.id}`);

Python Example:

import requests

response = requests.post(
    "https://api.sellvy.io/v1/products",
    headers={
        "Authorization": "Bearer sk_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "title": "Premium Icon Pack",
        "type": "digital_download",
        "price": 29.99,
        "description": "500+ hand-crafted icons"
    }
)
product = response.json()["data"]
print(f"Created product: {product['id']}")

Update Product

PATCH /products/:id

Send only the fields you want to update. All fields are optional.

Delete Product

DELETE /products/:id

Returns 204 No Content on success.

Orders

List Orders

GET /orders

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | page | number | Page number | | per_page | number | Items per page | | status | string | Filter: pending, processing, completed, cancelled, refunded | | payment_status | string | Filter: pending, paid, failed, refunded | | customer_email | string | Filter by customer email | | product_id | string | Filter by product | | date_from | string | ISO 8601 date | | date_to | string | ISO 8601 date |

Get Order

GET /orders/:id

Returns full order details including product info, payment details, delivery status, and fraud score.

Refund Order

POST /orders/:id/refund

Request Body:

{
  "amount": 29.99,
  "reason": "Customer requested refund"
}

Omit amount for a full refund. Partial refunds are supported for Stripe payments.

Customers

List Customers

GET /customers

Returns all customers who have purchased from your store, with their total orders and lifetime spend.

Get Customer

GET /customers/:id

Blacklist Customer

POST /customers/:id/blacklist

{
  "reason": "Fraudulent chargebacks"
}

Coupons

List Coupons

GET /coupons

Create Coupon

POST /coupons

{
  "code": "SUMMER20",
  "type": "percentage",
  "value": 20,
  "max_uses": 100,
  "expires_at": "2026-09-01T00:00:00Z",
  "min_order_amount": 10,
  "applies_to_products": ["prod_abc123"]
}

Required fields: code, type, value

Delete Coupon

DELETE /coupons/:id

Categories

List Categories

GET /categories

Create Category

POST /categories

{
  "name": "Templates",
  "description": "Website and app templates"
}

Webhooks

Webhooks let your server receive real-time notifications when events happen in your store.

Setting Up Webhooks

Go to Settings → Integrations → Webhooks and add your endpoint URL. Select which events you want to receive.

Webhook Payload

All webhook payloads follow this structure:

{
  "id": "evt_abc123",
  "type": "order.completed",
  "created_at": "2026-03-20T15:30:00Z",
  "data": {
    "id": "ord_xyz789",
    "order_number": "ORD-1234",
    "customer_email": "buyer@example.com",
    "total": 29.99,
    "currency": "USD",
    "payment_method": "stripe",
    "product": {
      "id": "prod_abc123",
      "title": "Premium Icon Pack"
    }
  }
}

Verifying Webhook Signatures

Every webhook request includes a X-Sellvy-Signature header. Verify it using your webhook secret:

JavaScript:

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Event Types

| Event | Description | |-------|-------------| | order.created | A new order has been placed | | order.completed | Order payment confirmed and product delivered | | order.refunded | Order has been fully or partially refunded | | order.cancelled | Order has been cancelled | | order.disputed | A dispute/chargeback has been opened | | payment.received | Payment has been received (for async methods like crypto) | | payment.failed | Payment attempt failed | | product.created | A new product was created | | product.updated | A product was modified | | product.deleted | A product was deleted | | product.low_stock | Product stock fell below threshold | | customer.created | A new customer made their first purchase | | review.created | A customer left a review | | subscription.created | New subscription started | | subscription.renewed | Subscription payment processed | | subscription.cancelled | Subscription cancelled |

Retry Policy

If your endpoint returns a non-2xx status code, Sellvy will retry the webhook with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: After 1 minute
  • Attempt 3: After 5 minutes
  • Attempt 4: After 30 minutes
  • Attempt 5: After 2 hours

After 5 failed attempts, the webhook is marked as failed. You can view failed webhooks and manually retry them from Settings → Integrations → Webhook Logs.

Error Codes

| Code | Status | Description | |------|--------|-------------| | unauthorized | 401 | Invalid or missing API key | | forbidden | 403 | API key lacks required permissions | | not_found | 404 | Resource does not exist | | validation_error | 422 | Request body failed validation | | rate_limited | 429 | Too many requests | | internal_error | 500 | Server error (contact support) |

SDKs and Libraries

Official SDKs are coming soon. In the meantime, the API works with any HTTP client. The examples above use the standard fetch API for JavaScript and the requests library for Python.

Need Help?

  • Join our Discord for developer discussions.
  • Email api-support@sellvy.io for API-specific issues.
  • Check the webhook logs to debug delivery issues.
All articles