REST API v1

API Reference

The Shopvo Storefront API lets you build custom frontends, mobile apps, and integrations on top of any Shopvo store. All endpoints return JSON.

Base URL

All API requests are made to the domain of the storefront you are integrating with. Shopvo uses host-based routing — the server identifies which store to use from the Host header of your request.

https://yourstore.shopvo.eu/api/storefront/

In development with the preview query parameter:

https://yourstore.shopvo.eu/api/storefront/cart?siteId=SITE_ID

Authentication

Most storefront API endpoints are public — they do not require authentication. The store is identified by the request's Host header.

Customer-specific endpoints (cart merge, saved addresses, order history) use a session cookie (customer_session) set when the customer logs in.

Admin API: The admin API uses NextAuth session tokens. These are not intended for third-party use — use only with your own admin dashboard.

Response format

All endpoints return JSON. Successful responses:

{ "data": { ... } }         // or flat object depending on endpoint
{ "cart": { ... } }
{ "success": true, "id": "..." }

Error responses:

{ "error": "Product not found" }           // 4xx errors
{ "success": false, "error": "Insufficient stock" }  // business logic errors

Inventory conflicts return 409 Conflict with { "error": "OUT_OF_STOCK" }.

Products

GET/api/storefront/{siteId}/products/grid

Fetch a grid of products for display. Supports filtering, sorting, and pagination.

Query Parameters

Name	Type	Description
`source`	string	newest \| featured \| popular_orders \| popular_reviews \| category \| tags
`limit`	number	Number of products to return. Max 48. Default 8.
`categoryId`	string	Filter by category slug (when source=category).
`tags`	string	Comma-separated tag slugs (when source=tags).

Example Response

{
  "products": [
    {
      "id": "prod_abc",
      "name": "Organic Cotton T-Shirt",
      "slug": "organic-cotton-tshirt",
      "price": 2999,
      "images": ["https://cdn.shopvo.io/..."],
      "inventoryCount": 42,
      "averageRating": 4.7,
      "reviewCount": 38
    }
  ]
}

Cross-sells

GET/api/storefront/cross-sells

Fetch cross-sell product recommendations for a given product. Useful for 'You might also like' sections on product and cart pages.

Query Parameters

Name	Type	Description
`productId`	string	Source product ID to find cross-sells for.
`siteId`	string	The store's site ID.
`limit`	number	Maximum number of recommendations to return. Default 4.

Example Response

{
  "products": [
    {
      "id": "prod_def",
      "name": "Matching Shorts",
      "slug": "matching-shorts",
      "price": 1999,
      "images": ["https://cdn.shopvo.eu/..."]
    }
  ]
}

Cart

GET/api/storefront/cart

Retrieve the active cart for the current session or logged-in customer.

Example Response

{
  "cart": {
    "id": "cart_xyz",
    "items": [
      {
        "productId": "prod_abc",
        "variantId": "var_001",
        "name": "Organic Cotton T-Shirt",
        "variantName": "Blue / M",
        "quantity": 2,
        "price": 2999
      }
    ],
    "subtotal": 5998,
    "total": 5998
  }
}

POST/api/storefront/cart

Create or update the cart. Validates inventory before saving.

Request Body

{
  "items": [
    {
      "productId": "prod_abc",
      "variantId": "var_001",
      "quantity": 2,
      "price": 2999
    }
  ],
  "subtotal": 5998,
  "total": 5998,
  "email": "customer@example.com"  // optional for guest carts
}

Example Response

{
  "cart": { "id": "cart_xyz", "sessionId": "sess_...", ... }
}

POST/api/storefront/cart/validate

Validate all cart items against current inventory levels without creating an order.

Request Body

{ "cartId": "cart_xyz" }

Example Response

{
  "valid": false,
  "invalidItems": [
    { "productId": "prod_abc", "requested": 5, "available": 2 }
  ]
}

Shipping quotes

GET/api/storefront/{siteId}/shipping-quotes

Fetch available shipping methods and rates for a given destination.

Query Parameters

Name	Type	Description
`country`	string	ISO 3166-1 alpha-2 country code.
`state`	string	State/province code (required for US, CA).
`zip`	string	Postal / ZIP code.
`weight`	number	Total cart weight in grams (optional).
`subtotal`	number	Cart subtotal in cents (for price-based rules).

Example Response

{
  "quotes": [
    { "id": "method_std", "name": "Standard Shipping", "price": 599, "estimatedDays": "3-5" },
    { "id": "method_exp", "name": "Express Shipping",  "price": 1299, "estimatedDays": "1-2" }
  ]
}

Payment methods

GET/api/storefront/{siteId}/payment-methods

Fetch all enabled payment gateways for a store.

Example Response

{
  "paymentMethods": [
    { "id": "pm_stripe", "name": "Credit / Debit Card", "provider": "stripe" },
    { "id": "pm_paypal", "name": "PayPal", "provider": "paypal" }
  ]
}

Checkout

POST/api/storefront/checkout/create-order

Submit a completed checkout and create an order. Pass either a sessionId (recommended) or full order data.

Request Body

// Option A: session-based (recommended)
{
  "sessionId": "sess_abc123",
  "idempotencyKey": "checkout_unique_key_001"
}

// Option B: direct order data
{
  "email": "customer@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+1 555 1234",
  "shippingAddress": {
    "address": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90210",
    "country": "US"
  },
  "billingAddress": {      // optional; defaults to shippingAddress
    "address": "456 Oak Ave",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "shippingMethod": "method_std",
  "paymentMethod": "pm_stripe",
  "items": [
    { "productId": "prod_abc", "variantId": "var_001", "quantity": 2, "price": 2999 }
  ],
  "subtotal": 5998,
  "shipping": 599,
  "tax": 540,
  "discount": 0,
  "total": 7137,
  "customAttributes": {
    "gift_message": "Happy Birthday!",
    "pickup_date": "2026-03-15"
  },
  // Required when shippingMethod is a BOX NOW Locker method:
  "pickupPointData": {
    "lockerId": "BOX-00123",
    "lockerName": "BOX NOW — Syntagma Square",
    "lockerAddress": "Syntagma Square 1",
    "lockerCity": "Athens",
    "lockerPostcode": "10557",
    "lockerLatitude": 37.9755,
    "lockerLongitude": 23.7348
  }
}

Example Response

{
  "success": true,
  "id": "order_xyz",
  "number": "ORD-1042",
  "total": 7137
}

BOX NOW lockers

GET/api/storefront/box-now/lockers

Fetch the list of active BOX NOW pickup lockers for a site that has BOX NOW shipping configured. Results are cached for 15 minutes.

Query Parameters

Name	Type	Description
`siteId`	string	Required. The site ID.

Example Response

{
  "lockers": [
    {
      "id": "BOX-00123",
      "name": "BOX NOW — Syntagma Square",
      "address": "Syntagma Square 1",
      "city": "Athens",
      "postcode": "10557",
      "latitude": 37.9755,
      "longitude": 23.7348,
      "isActive": true
    }
  ]
}

Mastercard (MPGS) payment

POST/api/payments/mastercard/initiate

Create an MPGS hosted payment session for a placed order and return the Mastercard-hosted checkout URL.

Request Body

{
  "orderId": "order-cuid",
  "siteId":  "site-cuid"
}

Example Response

{
  "success": true,
  "redirectUrl": "https://eu.gateway.mastercard.com/checkout/pay/<sessionId>?merchant=MERCHANT_ID"
}

GET/api/payments/mastercard/callback

Callback endpoint invoked by Mastercard after the customer completes or cancels payment. Verifies the resultIndicator and updates the order to PAID or VOIDED.

Query Parameters

Name	Type	Description
`orderId`	string	The Shopvo order ID.
`resultIndicator`	string	Token returned by MPGS after the payment session. Compared against the stored successIndicator using a constant-time comparison.

Example Response

// Redirects to /checkout/confirmation?orderId=...  (PAID)
// or      /checkout/payment?error=payment_failed   (VOIDED)

Inventory

GET/api/storefront/inventory

Check inventory levels for one or more products/variants.

Query Parameters

Name	Type	Description
`productId`	string	Check a single product. Returns its inventoryCount.
`variantIds`	string	Comma-separated variant IDs to check in bulk.

Example Response

{
  "inventory": {
    "prod_abc": { "count": 42, "trackInventory": true },
    "var_001": { "count": 10 },
    "var_002": { "count": 0 }
  }
}

Back-in-stock alerts

POST/api/storefront/notify-me

Subscribe an email address to be notified when a product is back in stock.

Request Body

{
  "email": "customer@example.com",
  "productId": "prod_abc",
  "variantId": "var_001"  // optional
}

Example Response

{ "success": true }

Price rules

GET/api/storefront/price-rules

Fetch active automatic price rules for the store. Used internally by checkout to calculate automatic discounts.

Query Parameters

Name	Type	Description
`subtotal`	number	Cart subtotal in cents to evaluate rule eligibility.

Example Response

{
  "rules": [
    {
      "id": "rule_001",
      "name": "10% off orders over $50",
      "type": "PERCENTAGE",
      "value": 10,
      "minimumAmount": 5000
    }
  ]
}

Webhooks

Webhooks allow Shopvo to push real-time events to your system. Configure webhook URLs from Settings → Webhooks in the admin.

Available events:

order.created

Fired when a customer completes checkout and an order is created.

order.updated

Fired when an order status changes (processing, shipped, delivered).

payment.confirmed

Fired when a payment is successfully captured.

payment.failed

Fired when a payment attempt fails.

inventory.low

Fired when a product's inventory count drops below the threshold.

cart.abandoned

Fired 1 hour after a cart is left inactive with items.

review.created

Fired when a customer submits a product review.

Webhook payload format:

{
  "event": "order.created",
  "timestamp": "2026-03-05T12:00:00Z",
  "siteId": "site_abc",
  "data": {
    "id": "order_xyz",
    "number": "ORD-1042",
    "total": 7137,
    ...
  }
}

Shopvo signs all webhook payloads with an X-Shopvo-Signature header (HMAC-SHA256). Verify the signature to ensure the payload was sent by Shopvo.

Error codes

400 Bad Request

Invalid request body or missing required fields. Check the error message for details.

401 Unauthorized

Authentication required. Ensure the customer session cookie is set.

404 Not Found

The requested resource (site, product, order) does not exist or does not belong to this store.

409 Conflict

Inventory conflict (OUT_OF_STOCK). Requested quantity exceeds available stock.

500 Internal Server Error

Unexpected server error. Retry the request. If the problem persists, contact support.

API Reference

Base URL

Authentication

Response format

Products

Cross-sells

Cart

Shipping quotes

Payment methods

Promo codes

Checkout

BOX NOW lockers

Mastercard (MPGS) payment

Inventory

Back-in-stock alerts

Newsletter subscribe

Price rules

Webhooks

Error codes