Skip to main content

Link existing order to platform order

PUT 
/api/v1/orders/:orderId/link

This endpoint links an existing VesuvioPay order to an external platform order ID. Useful when orders were created in VesuvioPay but need to be linked to your platform.

Authentication: Requires Private API Key (sk_*)

Use Cases:

  • Linking VesuvioPay checkout orders to your platform
    • Post-order synchronization between systems
    • Fixing missing order linkages
    • Migrating orders between platforms

Important Notes:

  • Once linked, order can be retrieved using external ID
    • External order ID must be unique within the store
    • Cannot change existing external order ID (must be null)

Error Scenarios:

  • 404 NOT FOUND - Order not found (Error code: ORDER_NOT_FOUND)
    • 400 BAD REQUEST - Order already linked or external ID in use (Error code: ORDER_ALREADY_LINKED or EXTERNAL_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 linked successfully to external platform