Skip to main content

Create order from external platform

POST 
/api/v1/orders

This endpoint creates a new order in VesuvioPay from an external platform (POS, e-commerce site, mobile app, etc.). Use this for importing orders created outside VesuvioPay.

Authentication: Requires Private API Key (sk_*)

Order Creation Behavior:

  • Order is created with "confirmed" status by default
    • Customer is created if customerInfo provided and doesn't exist
    • Inventory is decremented for order items
    • order.created webhook is triggered
    • Order appears in customer order history
    • External order ID is linked if provided

Use Cases:

  • POS system order imports
    • E-commerce platform order synchronization
    • Mobile app order creation
    • Third-party marketplace order imports
    • Manual order creation for phone/email orders

Important Notes:

  • Product variants must exist in VesuvioPay before creating order
    • Prices in request are used (not current product prices)
    • Inventory is checked and decremented
    • This does NOT process payment - assumes payment already handled externally

Error Scenarios:

  • 400 BAD REQUEST - Missing required fields, invalid data, or insufficient inventory (Error code: INVALID_REQUEST, VALIDATION_ERROR, or INSUFFICIENT_INVENTORY)
    • 404 NOT FOUND - Product variants or customer not found (Error code: VARIANT_NOT_FOUND or CUSTOMER_NOT_FOUND)
    • 409 CONFLICT - External order ID already exists (Error code: EXTERNAL_ORDER_ID_EXISTS)
    • 401 UNAUTHORIZED - Invalid or missing API key (Error code: INVALID_API_KEY)
    • 403 FORBIDDEN - API key doesn't have access to this store (Error code: NO_STORE_ACCESS)

Request​

Responses​

Order created successfully with assigned ID - webhook triggered