DeprecatrAI

Migrate from 2024-01-18 to 2024-04-17

Update your API calls to account for the deprecation of the `merchant_id` parameter in the List Merchants endpoint.

within 90 days~2h effort1 breaking changes

What Changed

Medium

Deprecated `merchant_id` in List Merchants

The `merchant_id` parameter is no longer supported in the List Merchants API endpoint. This change affects integrations that previously filtered merchants by ID.

Before
squareClient.merchantsApi.listMerchants(merchantId='YOUR_MERCHANT_ID')
After
squareClient.merchantsApi.listMerchants()

Migration Steps

  1. 1

    Review API Changes

    code

    Familiarize yourself with the changes between the '2024-01-18' and '2024-04-17' versions of the Square API. Pay close attention to any deprecated or removed fields and parameters.

    • ↳Check the official Square API changelog for detailed information.
    • ↳Focus on breaking changes, especially those affecting your active integrations.
  2. 2

    Update SDK/Client Initialization

    config

    Ensure your Square API client or SDK is updated to a version compatible with the '2024-04-17' API version. Update the API version used in your client initialization.

    • ↳Consult the Square SDK documentation for the correct initialization parameters.
    • ↳Ensure you are using the latest stable version of the SDK.
  3. 3

    Modify API Calls

    code

    Adjust your code to accommodate the '2024-04-17' API version. Specifically, remove the `merchant_id` parameter when calling the `listMerchants` endpoint.

    • ↳Replace `squareClient.merchantsApi.listMerchants(merchantId='YOUR_MERCHANT_ID')` with `squareClient.merchantsApi.listMerchants()`.
    • ↳If you need to filter merchants, consider fetching all and filtering client-side or using alternative endpoints if available.
  4. 4

    Implement Comprehensive Testing

    test

    Thoroughly test all affected parts of your application. This includes unit tests, integration tests, and end-to-end tests to ensure functionality remains intact.

    • ↳Create specific test cases for the modified `listMerchants` endpoint.
    • ↳Use mock data that simulates various scenarios.
  5. 5

    Deploy to Staging

    deploy

    Deploy the updated code to a staging or pre-production environment. Conduct final testing in an environment that closely mirrors your production setup.

    • ↳Monitor logs closely for any unexpected errors.
    • ↳Perform user acceptance testing (UAT) if applicable.
  6. 6

    Production Deployment

    deploy

    Once confident, deploy the changes to your production environment. Monitor system performance and error rates immediately after deployment.

    • ↳Consider a phased rollout strategy if possible.
    • ↳Have a rollback plan in place.
  7. 7

    Post-Deployment Verification

    verify

    After deployment, actively monitor your application's behavior and error logs. Verify that all Square API interactions are functioning as expected.

    • ↳Check key business metrics that rely on Square data.
    • ↳Be prepared to address any immediate issues.

Testing Checklist

  1. 1.

    Verify `listMerchants` endpoint without `merchant_id` parameter

    Execute API calls and assert expected response structure and data.

  2. 2.

    Test merchant filtering (if previously done via `merchant_id`)

    Implement client-side filtering or investigate alternative server-side methods.

  3. 3.

    Validate other Square API endpoints

    Ensure no unintended side effects on unrelated API interactions.

  4. 4.

    Check application error logs

    Monitor for any new exceptions or warnings related to Square integration.

Common Mistakes

✗ Forgetting to remove the `merchant_id` parameter from `listMerchants` calls.

The API call will fail with a `400 Bad Request` error due to an invalid parameter.

✓ Remove the `merchant_id` argument from the `listMerchants` method call in your code.

✗ Not updating the Square SDK version.

The SDK might not be aware of the API changes, leading to incorrect requests or unexpected behavior.

✓ Update to the latest compatible version of the Square SDK for your language and re-initialize the client.

✗ Assuming filtering logic will remain the same.

If `merchant_id` was used for filtering, the integration might start returning all merchants unexpectedly, or failing if subsequent logic relies on a single merchant.

✓ Re-evaluate and adjust any logic that depended on filtering by `merchant_id` in the `listMerchants` response.

Never get blindsided by an API change again

Deprecatr AI monitors 150+ providers, maps changes to your codebase, and delivers migration checklists before your team hits a breaking change.

Join the Waitlist