Orders API

The Orders API provides comprehensive order management capabilities, enabling you to retrieve order information, update order status, handle cancellations, and synchronize orders between VesuvioPay and external e-commerce platforms.

Overview

The Orders API enables you to:

• Retrieve Orders: Fetch orders with filtering by status, date range, and pagination
• Order Details: Get complete order information including line items and customer data
• Status Updates: Update order fulfillment status with metadata
• Order Cancellation: Cancel orders with optional refund processing
• Platform Integration: Create orders from external platforms and link existing orders
• Bidirectional Sync: Maintain order state consistency across systems

All order operations are scoped to your store, ensuring secure access to order data.

Use Cases

Order Management Dashboard

Build administrative interfaces to view and manage orders:

// Get recent orders
const orders = await vesuvioPay.orders.list({
  limit: 50,
  status: 'pending',
  dateFrom: '2024-01-01',
  dateTo: '2024-01-31'
});

// Get detailed order information
const order = await vesuvioPay.orders.get(orderId);

Fulfillment Integration

Update order status as fulfillment progresses:

// Mark order as shipped
await vesuvioPay.orders.updateStatus(orderId, {
  status: 'shipped',
  metadata: {
    trackingNumber: 'TRACK123',
    carrier: 'UPS',
    shippedAt: new Date().toISOString()
  }
});

// Mark as delivered
await vesuvioPay.orders.updateStatus(orderId, {
  status: 'delivered',
  metadata: {
    deliveredAt: new Date().toISOString(),
    signedBy: 'John Doe'
  }
});

Order Cancellation and Refunds

Handle order cancellations with proper tracking:

// Cancel an order with reason
await vesuvioPay.orders.cancel(orderId, {
  reason: 'Customer requested cancellation',
  refundAmount: 99.99, // Optional partial refund
  notifyCustomer: true
});

External Platform Synchronization

Create orders from external platforms (Shopify, WooCommerce, etc.):

// Import order from external platform
const order = await vesuvioPay.orders.createFromPlatform({
  externalOrderId: 'shop_order_123',
  customerId: 'customer_guid',
  items: [
    {
      externalProductId: 'prod_123',
      externalVariantId: 'var_456',
      quantity: 2,
      price: 29.99
    }
  ],
  total: 59.98,
  status: 'pending',
  metadata: {
    platformOrderNumber: '#1234',
    platformName: 'Shopify'
  }
});

Order Linking

Link existing VesuvioPay orders to external platform orders:

// Link order to external platform
await vesuvioPay.orders.linkToPlatform(orderId, {
  externalOrderId: 'shop_order_456',
  platformName: 'WooCommerce'
});

Authentication

Private API Key Required

All Orders API endpoints require authentication using a Private API Key. Order data is sensitive and must be protected.

Include your private API key in the request header:

X-API-Key: your_private_api_key_here

Key Concepts

Order Lifecycle

Orders progress through several states:

1. Created: Order placed by customer
2. Confirmed: Payment confirmed and order accepted
3. Processing: Order being prepared for fulfillment
4. Shipped: Order dispatched to customer
5. Delivered: Order received by customer
6. Cancelled: Order cancelled (before or after fulfillment)
7. Refunded: Payment refunded to customer

Order Identifiers

Orders can be identified using:

• Internal ID: VesuvioPay's GUID identifier
• External ID: Your platform's order identifier

Most endpoints accept either identifier type for flexibility.

Order Structure

Orders contain comprehensive information:

• Customer Information: Customer ID, contact details, delivery address
• Line Items: Products, variants, quantities, and pricing
• Payment Details: Total amount, payment method, transaction ID
• Status: Current order state and status history
• Metadata: Custom fields for tracking and integration data
• Timestamps: Created, updated, and status change times

Status Updates

Status updates support:

• Status Transition: Change order to new status
• Metadata Attachment: Add tracking numbers, notes, timestamps
• Status History: Automatically tracked for audit trail
• Webhooks: Trigger notifications on status changes

Order Metadata

Metadata enables flexible data storage:

• Track external platform information
• Store fulfillment provider details
• Attach custom business logic data
• Maintain integration state

Metadata is preserved during order operations and returned in order responses.

Filtering and Pagination

List operations support filtering:

• Status Filter: Retrieve orders in specific states
• Date Range: Filter by creation date (dateFrom, dateTo)
• Pagination: Control result size with limit parameter (1-50)

Results are ordered by creation date (newest first).

External Platform Integration

Platform integration features:

• Create from Platform: Import orders from external systems
• Link Orders: Connect existing orders to external IDs
• Bidirectional Sync: Keep order status synchronized
• External ID Lookup: Query orders by platform identifier

Response Format

Order list responses include pagination:

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "order_guid",
        "externalId": "shop_order_123",
        "orderNumber": "ORD-001234",
        "status": "shipped",
        "customerId": "customer_guid",
        "total": 99.99,
        "currency": "USD",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-16T14:20:00Z"
      }
    ],
    "total": 150,
    "limit": 50
  }
}

Detailed order responses include line items:

{
  "success": true,
  "data": {
    "id": "order_guid",
    "externalId": "shop_order_123",
    "orderNumber": "ORD-001234",
    "status": "shipped",
    "customer": {
      "id": "customer_guid",
      "email": "customer@example.com",
      "phoneNumber": "+1234567890"
    },
    "items": [
      {
        "id": "line_item_id",
        "productId": "product_guid",
        "variantId": "variant_guid",
        "externalProductId": "prod_123",
        "quantity": 2,
        "price": 29.99,
        "subtotal": 59.98,
        "product": {
          "name": "Premium T-Shirt",
          "sku": "TSHIRT-BLK-M"
        }
      }
    ],
    "subtotal": 59.98,
    "tax": 5.40,
    "shipping": 10.00,
    "total": 75.38,
    "currency": "USD",
    "metadata": {
      "trackingNumber": "TRACK123",
      "carrier": "UPS"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T14:20:00Z"
  }
}

Error Handling

Common error scenarios:

• 404 Not Found: Order with specified ID doesn't exist
• 400 Bad Request: Invalid status transition or missing required fields
• 409 Conflict: Order state prevents requested operation
• 401 Unauthorized: Missing or invalid API key
• 403 Forbidden: API key doesn't have access to the specified store

Order-specific errors:

• Invalid Status Transition: Cannot move from current status to requested status
• Already Cancelled: Cannot update or cancel already cancelled order
• External ID Conflict: External order ID already linked to different order

See the Error Handling guide for detailed error response formats.

Best Practices

Status Transition Validation

Validate status transitions before updating:

const validTransitions = {
  'pending': ['confirmed', 'cancelled'],
  'confirmed': ['processing', 'cancelled'],
  'processing': ['shipped', 'cancelled'],
  'shipped': ['delivered', 'cancelled']
};

if (validTransitions[currentStatus].includes(newStatus)) {
  await vesuvioPay.orders.updateStatus(orderId, { status: newStatus });
}

Idempotent Order Creation

Use external IDs to prevent duplicate order creation:

// Safe to retry - won't create duplicates
await vesuvioPay.orders.createFromPlatform({
  externalOrderId: 'shop_order_123', // Ensures idempotency
  // ... other order data
});

Rich Metadata

Store relevant tracking information in metadata:

await vesuvioPay.orders.updateStatus(orderId, {
  status: 'shipped',
  metadata: {
    // Fulfillment details
    trackingNumber: 'TRACK123',
    carrier: 'UPS',
    service: 'Ground',
    estimatedDelivery: '2024-01-20',

    // Warehouse info
    warehouseId: 'WH-01',
    packedBy: 'John D.',

    // Integration data
    fulfillmentProvider: 'ShipStation',
    externalShipmentId: 'ss_ship_789'
  }
});

Incremental Sync

For ongoing synchronization, track and sync only changed orders:

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

// Get orders modified since last sync
const orders = await vesuvioPay.orders.list({
  dateFrom: lastSync,
  limit: 50
});

// Process and sync with external platform
for (const order of orders.data.orders) {
  await syncToExternalPlatform(order);
}

setLastSyncTime(Date.now());

Error Recovery

Handle errors gracefully with retry logic:

async function updateOrderWithRetry(orderId, update, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await vesuvioPay.orders.updateStatus(orderId, update);
    } catch (error) {
      if (i === retries - 1) throw error;
      await delay(1000 * Math.pow(2, i)); // Exponential backoff
    }
  }
}

Webhooks Integration

Subscribe to order events for real-time updates:

• order.created: New order placed
• order.status_updated: Order status changed
• order.confirmed: Payment confirmed
• order.shipped: Order dispatched
• order.delivered: Order received
• order.cancelled: Order cancelled
• order.refunded: Refund processed

See the Webhooks API for setup instructions.

Rate Limiting

Order operations are subject to rate limiting. Consider:

• Batching status updates when possible
• Implementing exponential backoff for retries
• Caching frequently accessed order data

See the Rate Limiting documentation for details.

Data Retention

Order data is retained according to your store's retention policy:

• Active orders: Retained indefinitely
• Completed orders: Retained per compliance requirements
• Cancelled orders: Retained for audit trail

Consult your VesuvioPay agreement for specific retention periods.

Next Steps

• Review specific endpoint documentation in the API reference below
• Integrate with Customers API for customer information
• Connect with Products API for inventory management
• Set up webhooks for order event notifications

---

Interactive API Reference

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