Upgrading from V1 to V2

This guide outlines the major changes introduced in API V2 and the steps required to upgrade your existing integrations from V1.

[!secondary] Looking for version 1 of the api? API V1 Introduction

Endpoint Path Changes

All API V2 endpoints are now prefixed with /api/v2/ instead of /api/.

| Endpoint | V1 Path | V2 Path | |----------|---------|---------| | Create Order | /api/orders/create | /api/v2/orders/create | | List Orders | N/A | /api/v2/orders |

Standardized Response Envelope

One of the most significant changes in V2 is the introduction of a standardized JSON response envelope for all requests. This ensures a predictable structure for both success and error responses.

Successful Response

All successful responses in V2 wrap the returned data in a data object and include a success boolean set to true. Metadata, such as trace_id, is now placed inside a meta object.

V2 Success Envelope Example:

{
  "success": true,
  "data": {
    "order": {
      "uuid": "9c8b7f6a-5d4e-3c2b-1a0z-9y8x7w6v5u4t",
      "order_no": "54321"
    }
  },
  "errors": null,
  "meta": {
    "trace_id": "20260321:api:abc12"
  }
}

Error Response

Validation failures and other errors now return a consistent structure with success set to false. Error details are provided in the errors object.

V2 Error Envelope Example:

{
  "success": false,
  "data": null,
  "errors": {
    "email": [
      "The email field is required."
    ]
  },
  "meta": {
    "trace_id": "20260321:api:abc12"
  }
}

Summary of Changes

1. Prefix: Update all API calls to use the /api/v2/ prefix.
2. Parsing: Update your JSON parsing logic to expect the { success, data, errors, meta } envelope.
3. Trace ID: You can now find the trace_id for every request in meta.trace_id. Use this whenever contacting support about a specific request.