Products API

The Products API enables you to synchronize your product catalog with VesuvioPay, manage product information, track inventory levels, and link products with external platform identifiers. This API is essential for e-commerce integrations and maintaining accurate product data.

Overview

The Products API provides comprehensive product management capabilities:

• Product Synchronization: Bulk sync products from external platforms (Shopify, WooCommerce, etc.)
• CRUD Operations: Create, read, update, and delete individual products
• Inventory Management: Update stock levels and track inventory across variants
• External Linking: Connect VesuvioPay products with external platform product IDs
• Variant Management: Handle product variants (sizes, colors, etc.) and link them to external systems

Products in VesuvioPay can have multiple variants, each with its own pricing, inventory, and external identifiers.

Use Cases

Initial Product Catalog Sync

When integrating VesuvioPay with your e-commerce platform, perform a bulk synchronization of your entire product catalog:

// Sync products from your platform
const syncResult = await vesuvioPay.products.sync({
  products: [
    {
      externalId: 'shop_prod_123',
      name: 'Premium T-Shirt',
      description: 'High-quality cotton t-shirt',
      variants: [
        {
          externalId: 'shop_var_456',
          sku: 'TSHIRT-BLK-M',
          price: 29.99,
          inventory: 50,
          options: { size: 'M', color: 'Black' }
        }
      ]
    }
  ]
});

Real-Time Inventory Updates

Keep inventory synchronized between your platform and VesuvioPay:

// Update inventory when stock changes
await vesuvioPay.products.updateInventory('variant_id', {
  quantity: 25,
  trackInventory: true
});

Product Lifecycle Management

Create new products when launched, update details when changed, and remove discontinued items:

// Create a new product
const product = await vesuvioPay.products.create({
  name: 'New Product',
  description: 'Product description',
  variants: [{ sku: 'NEW-001', price: 49.99 }]
});

// Update product details
await vesuvioPay.products.update('product_id', {
  name: 'Updated Product Name',
  description: 'Updated description'
});

// Delete discontinued product
await vesuvioPay.products.delete('product_id');

Platform Migration

When migrating from one e-commerce platform to another, use linking endpoints to maintain product relationships:

// Link existing VesuvioPay product to new platform ID
await vesuvioPay.products.linkExternal(productId, {
  externalProductId: 'new_platform_prod_789'
});

Authentication

Private API Key Required

All Products API endpoints require authentication using a Private API Key. These operations modify your product catalog and must be protected.

Include your private API key in the request header:

X-API-Key: your_private_api_key_here

Key Concepts

Product Structure

Products consist of:

• Base Product: Top-level product information (name, description, images)
• Variants: Different versions of the product (SKUs, sizes, colors)
• Pricing: Per-variant pricing information
• Inventory: Stock tracking at the variant level
• External IDs: Links to products in external platforms

Product Identifiers

Products and variants can be identified by:

1. Internal ID: VesuvioPay's GUID identifier
2. External ID: Your platform's product/variant identifier
3. SKU: Stock Keeping Unit for variants

Most endpoints accept either internal or external IDs for flexibility.

Product Synchronization

The sync endpoint provides intelligent merging:

• Create: New products are added to your catalog
• Update: Existing products (matched by external ID) are updated
• Merge: Variants are intelligently merged to avoid duplicates
• Preserve: Unspecified fields retain their current values

Sync operations return detailed results showing which products were created, updated, or failed.

Inventory Tracking

VesuvioPay supports flexible inventory management:

• Tracked Inventory: Quantities are monitored and decremented on orders
• Untracked Inventory: Products always available (digital goods, services)
• Stock Alerts: Get notified when inventory runs low
• Backorder Support: Allow purchases when out of stock

Product Variants

Variants represent different options of the same product:

• Each variant has unique pricing and inventory
• Variants can have multiple options (size, color, material, etc.)
• Each variant can have its own external ID and SKU
• Variants inherit images from parent product unless specified

External ID Linking

Link products and variants to external systems:

• Supports multiple platform integrations simultaneously
• Enables bidirectional synchronization
• Maintains relationships during platform migrations
• Allows lookup by either internal or external identifiers

Response Format

Product sync operations return detailed results:

{
  "success": true,
  "data": {
    "created": 5,
    "updated": 12,
    "failed": 0,
    "products": [
      {
        "externalId": "shop_prod_123",
        "status": "created",
        "internalId": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }
}

Individual product operations return full product details:

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "shop_prod_123",
    "name": "Premium T-Shirt",
    "description": "High-quality cotton t-shirt",
    "variants": [
      {
        "id": "variant_guid",
        "externalId": "shop_var_456",
        "sku": "TSHIRT-BLK-M",
        "price": 29.99,
        "inventory": 50,
        "trackInventory": true
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  }
}

Error Handling

Common error scenarios:

• 404 Not Found: Product or variant doesn't exist
• 400 Bad Request: Invalid product data (missing required fields, invalid prices)
• 409 Conflict: External ID already exists for different product
• 401 Unauthorized: Missing or invalid API key
• 403 Forbidden: API key doesn't have access to the specified store

See the Error Handling guide for detailed error response formats.

Best Practices

Bulk Operations

Use the sync endpoint for initial imports and bulk updates rather than individual create/update calls:

// Efficient: Single sync call
await vesuvioPay.products.sync({ products: bulkProducts });

// Inefficient: Multiple individual calls
for (const product of products) {
  await vesuvioPay.products.create(product); // Avoid this pattern
}

Idempotent Operations

Always include external IDs to make sync operations idempotent:

const result = await vesuvioPay.products.sync({
  products: [
    {
      externalId: 'shop_123', // Include for idempotency
      name: 'Product Name'
    }
  ]
});

Incremental Syncs

For ongoing synchronization, only sync products that changed:

// Track last sync timestamp
const lastSync = getLastSyncTime();
const changedProducts = getProductsModifiedSince(lastSync);

await vesuvioPay.products.sync({ products: changedProducts });
setLastSyncTime(Date.now());

Error Handling

Handle partial failures in sync operations gracefully:

const result = await vesuvioPay.products.sync({ products });

if (result.failed > 0) {
  // Log failed products for retry
  result.products
    .filter(p => p.status === 'failed')
    .forEach(p => console.error(`Failed to sync ${p.externalId}: ${p.error}`));
}

Rate Limiting

Product sync operations process large amounts of data and may take time. Consider:

• Batching large catalogs into multiple sync calls
• Implementing exponential backoff for retries
• Monitoring rate limit headers in responses

See the Rate Limiting documentation for details.

Webhooks Integration

Subscribe to product events to maintain synchronization:

• product.created: New product added
• product.updated: Product details changed
• product.deleted: Product removed
• product.inventory_updated: Stock level changed

See the Webhooks API for setup instructions.

Next Steps

• Review specific endpoint documentation in the API reference below
• Integrate with Cart API for customer shopping experiences
• Set up webhooks to receive product change notifications
• Connect with Orders API for inventory adjustments

---

Interactive API Reference

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