Inventory Management

Open Sky Commerce supports three inventory modes: managing products directly inside the admin panel (Internal), or syncing your catalog and stock levels from a POS system — Clover or Square. You switch between modes from Admin → Settings → Inventory Settings.

Inventory Modes

Switching Modes

Go to Admin → Settings → Inventory Settings, select your desired source, and click Save Source. Switching modes does not automatically delete external data — use the Clear External Data button if you want to remove a previous provider's synced catalog from the database before switching.

Clover Setup

1. Log in to your Clover developer dashboard and create a REST API token for your merchant account.
2. Add the following to your .env file (see Environment Variables for the full reference):

   CLOVER_MERCHANT_ID="your-merchant-id"
   CLOVER_REST_API_TOKEN="your-rest-api-token"
   CLOVER_ENVIRONMENT="production"   # or "sandbox"

3. In the admin panel, select Clover POS as your inventory source and click Save Source.
4. Click Sync Now to perform the initial catalog import. Categories, items, and stock levels will be pulled from Clover and stored locally.
5. Register the webhook URL in your Clover developer dashboard:

   https://your-domain.com/api/webhooks/clover

   Clover will send notifications for inventory and category changes, triggering an automatic re-sync.

Square Setup

1. Create a Square application at developer.squareup.com and generate an access token.
2. Add the following to your .env file:

   SQUARE_ACCESS_TOKEN="your-access-token"
   SQUARE_ENVIRONMENT="production"   # or "sandbox"
   SQUARE_LOCATION_ID="your-location-id"   # optional; omit to sync all locations

3. In the admin panel, select Square POS as your inventory source and click Save Source.
4. Click Sync Now to perform the initial catalog import. Categories, catalog items, and inventory counts per variation will be pulled from Square.
5. Register the webhook URL in your Square developer dashboard:

   https://your-domain.com/api/webhooks/square

   Subscribe to the catalog.version.updated and inventory.count.updated event types so changes in Square propagate to the storefront automatically.

How External Products Are Stored

When you sync from Clover or Square, products are stored in the ExternalProductEnrichment table — separate from the internal Product table. This means:

• Switching back to Internal mode leaves your manually-created products untouched.
• You can enrich external products (add images, descriptions, and SEO metadata) from Admin → Products → External Products without modifying the source record in Clover or Square.
• Stock decrements on checkout are written back to the POS system in real time so in-store and online inventory stay in sync.

Verifying Credentials

Both Clover and Square integrations include a Check Credentials button in the Inventory Settings panel. This makes a test API call and displays the response status so you can confirm your keys are valid before running a full sync.

Troubleshooting

Sync completes but no products appear

Check that your API token has the correct scopes. For Clover, the token needs read access to Inventory and Items. For Square, the token needs ITEMS_READ and INVENTORY_READ permissions.

Stock not decrementing after checkout

Confirm that CLOVER_MERCHANT_ID / SQUARE_ACCESS_TOKEN are set correctly in your production environment and that the active inventory source in the admin panel matches your POS. Stock write-back is skipped when the source is set to internal.

Webhooks not triggering re-sync

Ensure your webhook URL is publicly reachable (not localhost) and that the URL is registered in the correct POS developer dashboard. You can manually trigger a sync at any time from Admin → Settings → Inventory Settings → Sync Now.