Skip to main content

Store API

The Store API provides access to store-specific configuration and branding information. Use this API to retrieve checkout settings and company branding details needed to build customized shopping experiences that match your brand identity.

Overview​

The Store API enables you to:

  • Checkout Settings: Retrieve store-specific checkout configuration
  • Company Branding: Access logo, colors, and visual identity elements
  • Store Configuration: Get operational settings and preferences
  • Multi-Store Support: Manage settings across multiple store locations

This API is designed for building custom storefronts and checkout experiences that maintain consistent branding across all customer touchpoints.

Use Cases​

Custom Checkout Interface​

Build branded checkout experiences by retrieving store branding:

// Get branding for checkout page
const branding = await vesuvioPay.store.getBranding(storeId);

// Apply to your UI
document.documentElement.style.setProperty('--primary-color', branding.primaryColor);
document.getElementById('logo').src = branding.logoUrl;
document.getElementById('company-name').textContent = branding.companyName;

Checkout Configuration​

Retrieve checkout settings to configure your payment flow:

// Get checkout settings
const settings = await vesuvioPay.store.getCheckoutSettings(storeId);

// Configure checkout based on settings
if (settings.requirePhoneVerification) {
  enablePhoneVerificationStep();
}

if (settings.allowGuestCheckout) {
  showGuestCheckoutOption();
}

// Apply tax settings
setTaxCalculation(settings.taxSettings);

Multi-Store Applications​

For merchants with multiple stores, retrieve settings per location:

// Get settings for each store location
const stores = ['store_id_1', 'store_id_2', 'store_id_3'];

const storeSettings = await Promise.all(
  stores.map(async (storeId) => ({
    storeId,
    branding: await vesuvioPay.store.getBranding(storeId),
    settings: await vesuvioPay.store.getCheckoutSettings(storeId)
  }))
);

White-Label Solutions​

Build white-label e-commerce solutions that dynamically adapt to each merchant's branding:

// Dynamically load merchant branding
async function initializeMerchantStore(storeId) {
  const branding = await vesuvioPay.store.getBranding(storeId);

  // Apply merchant's visual identity
  applyTheme({
    logo: branding.logoUrl,
    primaryColor: branding.primaryColor,
    secondaryColor: branding.secondaryColor,
    fontFamily: branding.fontFamily
  });

  // Set merchant information
  setMerchantInfo({
    name: branding.companyName,
    supportEmail: branding.supportEmail,
    website: branding.website
  });
}

Authentication​

Public API Key Required

Store API endpoints require authentication using a Public API Key. These endpoints do not require customer authentication (JWT).

Include your public API key in the request header:

X-API-Key: your_public_api_key_here

Store ID Validation​

The API key must have access to the requested store. The system validates:

  • API key belongs to the store being queried
  • Store ID in the request matches the API key's store
  • Store is active and properly configured

Key Concepts​

Checkout Settings​

Checkout settings control payment and checkout behavior:

  • Phone Verification: Whether phone verification is required
  • Guest Checkout: Allow checkout without account creation
  • Address Validation: Require shipping address validation
  • Tax Settings: Tax calculation rules and rates
  • Payment Methods: Enabled payment options
  • Shipping Options: Available delivery methods
  • Terms and Conditions: Required acceptance of terms

Settings are configured in the VesuvioPay merchant dashboard and retrieved via the API.

Company Branding​

Branding information includes:

  • Visual Identity: Logo, colors, fonts
  • Company Information: Name, tagline, description
  • Contact Details: Support email, phone, website
  • Social Media: Links to social profiles
  • Custom Styling: CSS variables and theme customization

Branding ensures consistent customer experience across all touchpoints.

Store Configuration​

Store-level settings that affect operations:

  • Business Hours: Operating hours and timezone
  • Currency: Primary currency and accepted currencies
  • Language: Default language and supported locales
  • Regional Settings: Date formats, number formats
  • Features: Enabled features and capabilities

Theme Customization​

Branding includes theme customization options:

  • Primary Color: Main brand color
  • Secondary Color: Accent color
  • Font Family: Brand typography
  • Border Radius: UI element roundness
  • Button Styles: Button appearance preferences

These settings enable pixel-perfect brand matching.

Multi-Tenant Architecture​

VesuvioPay supports multiple stores per merchant:

  • Each store has independent branding
  • Settings are isolated by store ID
  • Shared products across stores (optional)
  • Centralized order management

Response Format​

Checkout settings response:

{
  "success": true,
  "data": {
    "storeId": "store_guid",
    "requirePhoneVerification": true,
    "allowGuestCheckout": false,
    "enableAddressValidation": true,
    "taxSettings": {
      "enabled": true,
      "rate": 0.08,
      "includedInPrices": false
    },
    "paymentMethods": [
      {
        "type": "card",
        "enabled": true,
        "displayName": "Credit/Debit Card"
      },
      {
        "type": "bnpl",
        "enabled": true,
        "displayName": "Buy Now, Pay Later"
      }
    ],
    "shippingOptions": [
      {
        "id": "standard",
        "name": "Standard Shipping",
        "price": 5.99,
        "estimatedDays": "3-5"
      },
      {
        "id": "express",
        "name": "Express Shipping",
        "price": 15.99,
        "estimatedDays": "1-2"
      }
    ],
    "currency": "USD",
    "locale": "en-US"
  }
}

Company branding response:

{
  "success": true,
  "data": {
    "storeId": "store_guid",
    "companyName": "Acme Store",
    "tagline": "Quality Products, Great Prices",
    "logoUrl": "https://cdn.example.com/logos/acme-logo.png",
    "faviconUrl": "https://cdn.example.com/logos/acme-favicon.ico",
    "primaryColor": "#FF6B35",
    "secondaryColor": "#004E89",
    "fontFamily": "Inter, sans-serif",
    "contactInfo": {
      "email": "support@acmestore.com",
      "phone": "+1234567890",
      "website": "https://acmestore.com"
    },
    "socialMedia": {
      "facebook": "https://facebook.com/acmestore",
      "instagram": "https://instagram.com/acmestore",
      "twitter": "https://twitter.com/acmestore"
    },
    "customCss": {
      "primaryColor": "#FF6B35",
      "secondaryColor": "#004E89",
      "borderRadius": "8px",
      "buttonStyle": "rounded"
    }
  }
}

Error Handling​

Common error scenarios:

  • 404 Not Found: Store doesn't exist or is inactive
  • 401 Unauthorized: Missing or invalid API key
  • 403 Forbidden: API key doesn't have access to the specified store
  • 400 Bad Request: Invalid store ID format

See the Error Handling guide for detailed error response formats.

Best Practices​

Caching​

Store settings change infrequently, so cache them to improve performance:

// Cache branding for 1 hour
const CACHE_TTL = 60 * 60 * 1000; // 1 hour in ms

async function getBrandingCached(storeId) {
  const cacheKey = `branding_${storeId}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const branding = await vesuvioPay.store.getBranding(storeId);
  cache.set(cacheKey, { data: branding, timestamp: Date.now() });

  return branding;
}

Theme Application​

Apply branding systematically across your application:

function applyStoreTheme(branding) {
  // CSS variables
  const root = document.documentElement;
  root.style.setProperty('--primary-color', branding.primaryColor);
  root.style.setProperty('--secondary-color', branding.secondaryColor);
  root.style.setProperty('--font-family', branding.fontFamily);
  root.style.setProperty('--border-radius', branding.customCss.borderRadius);

  // Meta tags
  document.title = branding.companyName;
  document.querySelector('link[rel="icon"]').href = branding.faviconUrl;

  // Open Graph tags
  document.querySelector('meta[property="og:title"]').content = branding.companyName;
  document.querySelector('meta[property="og:image"]').content = branding.logoUrl;
}

Fallback Values​

Provide sensible defaults when branding is unavailable:

async function getStoreBranding(storeId) {
  try {
    return await vesuvioPay.store.getBranding(storeId);
  } catch (error) {
    console.warn('Failed to load branding, using defaults');
    return {
      companyName: 'Store',
      primaryColor: '#000000',
      secondaryColor: '#666666',
      // ... other defaults
    };
  }
}

Responsive Design​

Ensure branding assets work across devices:

// Load appropriate logo size
function getResponsiveLogo(branding) {
  const screenWidth = window.innerWidth;

  if (screenWidth < 768) {
    return branding.logoMobileUrl || branding.logoUrl;
  } else {
    return branding.logoUrl;
  }
}

Settings Validation​

Validate retrieved settings before use:

function validateCheckoutSettings(settings) {
  // Ensure required fields exist
  if (!settings.currency || !settings.paymentMethods) {
    throw new Error('Invalid checkout settings');
  }

  // Validate payment methods
  if (!settings.paymentMethods.some(m => m.enabled)) {
    throw new Error('No payment methods enabled');
  }

  return true;
}

Rate Limiting​

Store API endpoints have generous rate limits since settings change infrequently. However:

  • Cache responses to minimize API calls
  • Avoid polling for changes
  • Use webhooks for real-time updates (when available)

See the Rate Limiting documentation for details.

Store Settings Management​

Store settings are managed through:

  • Merchant Dashboard: Primary interface for configuration
  • Admin API: Programmatic settings management (separate from SDK)
  • Store API: Read-only access for client applications

This API provides read-only access. To modify store settings, use the merchant dashboard or contact support.

Next Steps​

  • Review specific endpoint documentation in the API reference below
  • Integrate with Cart API to build complete shopping experiences
  • Apply branding to checkout flows
  • Set up consistent themes across all customer touchpoints

Interactive API Reference​

Detailed endpoint documentation is auto-generated from our OpenAPI specification. See the interactive API reference below for complete request/response schemas, available fields, and the ability to test endpoints directly.