Skip to content

Migration Guide

Gearment has moved to the Next App platform, which serves API v3 and Webhook v3 with better performance, more scalable endpoints, and new features.

Backward compatibility is preserved. Existing integrations on API v1/v2 and Webhook v1/v2 keep working out of the box, and you can adopt v3 at your own pace.

1. What stays the same

  • Your current v1/v2 API calls and registered webhooks continue to work exactly as before.
  • A compatibility layer routes those calls to the new system.
  • No immediate action is required for existing apps.

2. Endpoints

Version Base URL Sandbox Notes
v1/v2 https://api.gearment.com - Still supported through the compatibility layer
v3 https://apiv2.gearment.com/integration-handler https://api.gearmentinc.com/integration-handler Next App API, where new features land

3. What is new in v3

  • Modernised endpoints with richer queries and faster responses.
  • Consistent authentication and more detailed error handling.
  • Access to new features and data models that v1/v2 does not expose.
  • Updated documentation and examples in the API console.

For example, you can filter catalog variants on several criteria at once - here, product G5000, two variant ids, size 3XL, colour Daisy, in stock only:

curl -i -X GET \
  -H "X-Gearment-Client-Key: YOUR_GEARMENT_CLIENT_KEY" \
  -H "X-Gearment-Client-Secret: YOUR_GEARMENT_CLIENT_SECRET" \
  'https://apiv2.gearment.com/integration-handler/api/v3/catalog/variants/stock?filter.product_ids=G5000&filter.variant_ids=GM0002003147&filter.variant_ids=GM0002005986&filter.sizes=3XL&filter.color_codes=daisy&filter.stock_labels=VENDOR_CATALOG_VARIANT_STOCK_LABEL_IN_STOCK&paging.page=1&paging.limit=100'

You can also list and delete webhooks through the webhook operations rather than only in the dashboard.

4. Webhooks in v3

The v3 payload shape changed: order identifiers moved into a nested order object and were renamed. Configure your endpoints in Developer Settings > Webhooks.

Shipping address verified, in v1/v2:

{
  "type": "shipping_address_verified",
  "data": {
    "gearment_ord_id": "ORD123456789",
    "gearment_ord_name": "#10001",
    "ord_status": "pending",
    "verify_address": "verified",
    "order_id": "EXT-1234567"
  }
}

The same event in v3:

{
  "type": "shipping_address_verified",
  "order": {
    "gearment_id": "ORD123456789",
    "gearment_name": "#10001",
    "vendor_id": "EXT-1234567",
    "verify_address": "verified",
    "ord_status": "pending"
  }
}

Full delivery, retry, and signature rules are in the Gearment Webhook guide.

5. Migration path

  1. Read the Overview and Using API Key.
  2. Generate v3 credentials in Developer Settings > API credentials.
  3. Review the updated endpoint list and request and response shapes in the API console.
  4. Move your integration onto v3 endpoints at your own pace.

6. Recommendations

  • Short term: stay on v1/v2 if everything works.
  • Medium term: build new development against v3.
  • Long term: plan a full migration. v1/v2 may be deprecated in future, and deprecation timelines will be communicated well in advance.

7. Support