How to Test Square Integration for Multiple Locations

Set Up Multiple Locations in the Square Sandbox

Before you can test multi-location behavior, you need more than one location in your sandbox account. Square automatically creates a main location when you sign up for a sandbox account. To add additional locations, use the Square Dashboard or the Locations API.

• Using the Dashboard: Log in to your Square Developer Dashboard, navigate to the sandbox account, and go to Locations. Click Create Location and fill in the details (name, address, time zone). You can create locations that represent different physical stores, online marketplaces, or warehouses.
• Using the Locations API: Call the CreateLocation endpoint with a valid access token from your sandbox application. The request body must include a location object with at least a name and country. The API returns the new location's ID, which you will use in subsequent tests.

After creating the locations, list them using the ListLocations endpoint to confirm they all appear and have unique IDs. This step verifies that your integration can retrieve the full list of locations.

Test Transactions Per Location

Each payment, order, or checkout request in Square requires a location_id. To test multi-location support, you must send requests using different location IDs and confirm the data is recorded under the correct location.

1. Create a test payment for Location A: Use the CreatePayment endpoint with the location ID of your first sandbox location. Use a test card number (e.g., 4111111111111111) and a nonce generated from the Square Sandbox. The response should include the location ID you sent.
2. Create a test payment for Location B: Repeat the same process but use the location ID of your second sandbox location. Use a different test card or the same one — the key is that the location ID changes.
3. Verify in the Sandbox Dashboard: Log in to your sandbox account and go to the Transactions or Payments section. Filter by location. You should see each payment under its respective location. If both payments appear under the same location, your integration is not passing the location ID correctly.

This test confirms that your integration can create transactions for any location and that Square correctly attributes them.

Test Data Retrieval Per Location

Multi-location integrations often need to fetch data for a specific location — for example, retrieving all orders for a particular store. Square's ListOrders, ListPayments, and SearchCatalogObjects endpoints all support filtering by location.

• List orders for Location A: Call ListOrders with the location ID of Location A. The response should include only orders created under that location.
• List orders for Location B: Repeat with Location B's ID. The response should be different (or empty if no orders exist).
• Search catalog items by location: If your integration uses location-specific pricing or inventory, call SearchCatalogObjects with a location filter. Verify that items with location-specific overrides appear correctly.

If your integration retrieves data without a location filter, it may return data from all locations. That is acceptable for some use cases, but you must ensure you can isolate data per location when needed.

Test Location-Specific Inventory

Square supports tracking inventory at the location level. To test this, create an inventory item and adjust its quantity for each location separately.

1. Create a catalog item using the UpsertCatalogObject endpoint. Set track_quantity to true.
2. Set inventory for Location A: Call BatchChangeInventory with the location ID of Location A and a positive quantity change (e.g., +10).
3. Set inventory for Location B: Call the same endpoint with Location B's ID and a different quantity (e.g., +5).
4. Retrieve inventory counts: Use RetrieveInventoryCount with the catalog object ID and each location ID. The counts should differ, confirming that inventory is tracked per location.

This test is critical for businesses that sell the same product in multiple stores and need accurate stock levels per location.

Test Location-Specific Settings and Configurations

Square allows you to configure different settings per location, such as business hours, payment processing options, and tax rates. Your integration should respect these differences.

• Retrieve location details: Call RetrieveLocation for each location ID. Verify that fields like business_hours, timezone, and capabilities are correct.
• Test location-specific taxes: If you have set up different tax rates for different locations, create an order for each location and confirm the tax calculation matches the expected rate.
• Test location-specific payment methods: Some locations may support different payment methods (e.g., cash vs. card). Use the ListPaymentMethods endpoint (if available) or check the location's capabilities.

If your integration ignores location-specific settings, it may apply incorrect taxes or offer unavailable payment methods, leading to errors in production.

Test Webhooks for Multiple Locations

Square sends webhooks for events like payment created, order updated, or inventory changed. Each webhook payload includes a location_id field. Your integration must use this field to route the event to the correct location's data pipeline.

1. Set up a webhook endpoint in your sandbox application. Use a tool like webhook.site or your own server.
2. Trigger events for different locations: Create a payment for Location A, then create a payment for Location B. Check the webhook payloads. Each should contain the correct location_id.
3. Verify your handler logic: Ensure your code reads the location_id and processes the event accordingly. A common mistake is to ignore the location ID and update a single data store, which would mix data from different locations.

This test ensures that your integration can handle real-time updates correctly when multiple locations are active.

Common Mistakes and How to Avoid Them

Even experienced developers make errors when testing multi-location integrations. Here are the most frequent pitfalls:

• Using the main location ID for everything: Some developers hardcode the main location ID during testing and forget to make it dynamic. Always use a variable for the location ID.
• Not testing with multiple locations in the sandbox: If you only test with one location, you won't catch issues where the location ID is missing or incorrect.
• Ignoring location ID in webhook handlers: Webhooks include a location ID, but if your handler ignores it, you may update the wrong location's data.
• Assuming all locations have the same settings: Tax rates, business hours, and payment methods can differ. Test with locations that have different configurations.

To avoid these mistakes, create a test plan that covers at least two locations with different settings and run all your test cases against both.

Key Facts About Square Multi-Location Testing

Fact	Details
Sandbox environment	Square provides a free sandbox for testing. You can create multiple locations within a single sandbox account.
Location ID required	Every API call that creates or retrieves data must include a valid location ID.
Test card numbers	Use Square's test card numbers (e.g., 4111111111111111) to simulate payments. They work in the sandbox only.
Webhook payloads	Each webhook includes a location_id field. Your handler must use it to route the event.
Inventory tracking	Inventory is tracked per location. You must specify the location ID when adjusting or retrieving stock.
Location-specific settings	Tax rates, business hours, and payment methods can vary by location. Test with different configurations.

Limitations of Sandbox Testing

The Square Sandbox is a powerful tool, but it has limitations you should know before moving to production.

• No real payments: You cannot process actual credit card transactions. Use test card numbers only.
• Limited data retention: Sandbox data may be periodically reset. Do not rely on it for long-term testing.
• No real-time processing: Some features, like instant transfers, are not available in the sandbox.
• Rate limits: The sandbox has lower rate limits than production. If you are load testing, use production credentials carefully.

Despite these limitations, the sandbox is sufficient for validating multi-location logic. Plan to run a final verification in production with a small test transaction before going live.

Frequently Asked Questions

How do I create multiple locations in the Square Sandbox?

Use the Square Developer Dashboard: navigate to your sandbox account, go to Locations, and click Create Location. Alternatively, use the CreateLocation API endpoint with a valid sandbox access token.

Can I use the same test card for multiple locations?

Yes. Test card numbers work for any location in the sandbox. The location ID in the request determines which location the payment is attributed to.

What happens if I forget to include a location ID?

Square returns an error. Most endpoints that require a location ID will return a 400 BAD_REQUEST with a message like "location_id is required".

Do webhooks include the location ID?

Yes. Every webhook payload from Square includes a location_id field. Your webhook handler must read this field to process the event for the correct location.

How do I test location-specific inventory?

Create a catalog item with inventory tracking enabled. Then use BatchChangeInventory with different location IDs to set stock levels. Retrieve counts with RetrieveInventoryCount to verify.

Can I test location-specific tax rates in the sandbox?

Yes. Set up different tax rates for different locations in the sandbox Dashboard. Then create orders for each location and verify the tax calculation.

What is the most common mistake when testing multi-location integrations?

Hardcoding the main location ID and not testing with multiple locations. Always use a variable for the location ID and test with at least two locations.

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

• How to Integrate Square With Jotform
• Test Square APIs in the Sandbox
• Locations API

How Seatext AI can help

Seatext AI helps you test and optimize your Square integration by automating the creation of location-specific landing pages and content. With the AI SEO Content Factory, you can publish thousands of indexed Q&A pages that answer customer questions about each of your locations. The Local AI SEO agent ensures your pages rank for "near me" and neighborhood searches, driving traffic to the correct location. Seatext AI also provides AI Copy A/B Testing to test headlines and CTAs per location, and Website Translation to serve content in 125 languages. Note that you need a separate Seatext AI account for each domain, and development URLs like localhost are restricted.