Table of Contents

Migration Guidelines: Open API V1 → V2

This page provides a step-by-step guide for partners migrating from Open API V1 to Open API V2.

1. Key Differences

Key changes include:

  • Consistent use of locationId instead of companyProfileId.
  • Introduction of requestId for traceability.
  • New endpoints for each calls.
  • Asynchronous calls flow.
  • Refactored menu structure with clear hierarchy (Main Items, Variations, Modifiers).
  • Refactored Create Order to facilitate integration and support.
  • Standardized error handling format.

2. Update Authentication

  • V1: API keys sometimes passed in query parameters.
  • V2: All requests require x-api-key in headers.
  • V2: All requests require version in headers.

x-api-key: YOUR_API_KEY_HERE

3. Adjust Endpoints

  • Replace /v1/pos/integration/... with /v2/orders and /v2/menu.
  • Implement new endpoints:
    • POST /v2/order for order creation.
    • POST /v2/order/status for status updates.

4. Refactor Payloads

  • Replace companyProfileId with locationId.
  • Add requestId for tracking.
  • Ensure menu and order payloads follow the new structure:
    • Nested modifiers and variations.
    • Clear separation of fees, promotions, and taxes.

5. Handle Status Management

  • Remove reliance on UpdateOrderState from V1.
  • Implement the new status update flow:
    • Accept ACCEPTED or REJECTED responses.
    • Support manual resend for rejected orders.

6. Validate Menu Synchronization

  • Use the new menu model for HQ-level menus and location-level orders.
  • Test with the Menu Template provided for certification.

7. Test in Sandbox

  • Use the dedicated test URL and API keys.
  • Validate:
    • Menu sync.
    • Order creation.
    • Status handling.
    • Special use cases (Hub, Kiosk).

8. Certification & Go-Live

  • Complete the Certification Grid checklist.
  • Ensure logging and error handling are in place.
  • Deploy to production after successful pilot.
  • Align with UEAT on the merchants migration timeline to the new version

Best Practices

  • Maintain separate API keys for each environment.
  • Log all API calls and responses.
  • Use version control for configuration changes.

What's New in V2

Compared to the previous version, the v2 API introduces:

  • A more structured and consistent data model.
  • Improved Error Handling and response formats.
  • Clear separation of concerns between menu management and order workflows.
  • Enhanced support for asynchronous operations.