App guides
The Algolia app keeps your Swell products in an Algolia index. Active products are sent to Algolia when they are created or edited, and removed when they are deactivated or deleted. A page in your Swell dashboard sends your whole catalog, or only the products created since a date, whenever you need to fill or refresh the index.
The app doesn't add search to your storefront. Your storefront searches Algolia directly, for example with Algolia's InstantSearch library and a Search-Only API key.
| When | What the app does |
| An active product is created or edited | Sends the product to Algolia. The record with the same ID is replaced. |
| A product is deactivated or deleted | Removes its record from Algolia. |
| You run a sync from Products > Algolia sync | Sends all active products, or only those created on or after a date, one page at a time. |
Automatic updates can be turned off with the Sync product changes setting. The sync page works either way.
The app sends the same record fields as Swell's built-in Algolia integration.
- An Algolia account and application. Algolia creates the index the first time the app writes to it.
- The application's Application ID and Admin API Key, from Settings > API Keys in the Algolia dashboard. The app needs the Admin API Key: the sync checks the key by listing your API keys, which a Search-Only or other restricted key cannot do.
- If your store uses Swell's built-in Algolia integration, turn it off in Integrations. Running both sends every product to Algolia twice, and they overwrite each other's records if they use the same index.
Install Algolia from the Swell App Store, and set it up in your test environment before the live one.
Copy your Algolia keys
In the Algolia dashboard, go to Settings > API Keys and copy the Application ID and the Admin API Key.
Add the keys to the app
In Swell, go to Apps > Algolia > Settings, enter the Application ID and Admin API Key, and click Save settings. Products are sent to the products index. To use another index, enter its name in Index Name.
Sync your catalog
Go to Products > Algolia sync, choose All products and click Start sync. Keep the page open until it shows Complete. The first page checks your keys before any products are sent.
Test with a product
Edit an active product and save it. In the Algolia dashboard, search your index for the product. Its record ID is the Swell product ID, and the record shows your change.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 1 to 3 with the keys and index your storefront uses. Use a separate index, or a separate Algolia application, for the test environment, so testing doesn't change the index your storefront searches.
- With Sync product changes on, products you create, edit, deactivate or delete are updated in Algolia within moments.
- Inactive products are never sent. A product becomes searchable when you make it active.
- Changes made while Sync product changes is off are not sent later. Run a sync to send them.
- Products to sync: All products, or Products created on or after a date. The date is the start of that day in your time zone.
- Page size: 10, 100, 200, 500 or 1000 products per request. Larger pages need fewer requests.
- Products are sent oldest first. The page shows a progress bar, how many products were processed and how many were sent to Algolia.
- Stop finishes the page in progress, then stops. Resume from page continues a stopped or failed sync with the same products and page size. Start new sync starts over.
- The sync runs in your browser, one page at a time, so keep the page open until it shows Complete.
- Run a sync after bulk changes, such as an import, or after changing the index or the keys.
The app sends product records. Searchable attributes, facets, ranking and synonyms are set in the Algolia dashboard. For category filters, use the categories attribute. For Algolia's hierarchical menu, use the category level attributes. See For developers below for the record fields.
| Location | What it shows |
| Products > Algolia sync | The sync page: products to sync, page size, progress, and the details of any error. |
| Apps > Algolia > Settings | Your Algolia keys, the index name and the Sync product changes switch. |
Settings are in Apps > Algolia > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Application ID | ID of your Algolia application. Required. | None |
| Admin API Key | Admin API Key of the application. Required. Used only on Swell's servers to write to the index, and never sent to the browser. | None |
| Index Name | Algolia index that receives the product records. An empty value uses products. | products |
| Sync product changes | Sends product creates, edits and deletes to Algolia as they happen. The sync page works either way. | On |
- The app doesn't add search to your storefront.
- Only active products are indexed, one record per product. Variants, categories and content pages are not indexed as their own records.
- A sync replaces existing records but doesn't delete records of products that no longer exist in Swell, such as products deleted while Sync product changes was off. To clean up the index, clear it in Algolia, then sync all products.
- The app doesn't configure searchable attributes, facets or ranking.
- Algolia's plan limits apply, including the maximum record size and monthly operations. Every automatic update and every synced product counts as an operation.
The keys don't work, or the key is not the Admin API Key. Copy the Application ID and Admin API Key again from Settings > API Keys in Algolia, save the settings and start the sync again.
Enter both keys in Apps > Algolia > Settings and click Save settings.
The key can't write to the index. Use the Admin API Key, or a key with write access to the index.
Open Error details under the error. It shows the step that failed, the HTTP status and the response. Fix the cause, then click Resume from page. If records are too large for a page, start a new sync with a smaller page size.
Check that Sync product changes is on, that both keys are set, and that the product is active. Then save the product again, or run a sync of the products created on or after its creation date.
Products deleted or deactivated while Sync product changes was off are not removed by a sync. Clear the index in Algolia, then sync all products.
The page works only inside the Swell dashboard, signed in to the store it syncs. Open it from Products > Algolia sync.
Uninstalling the app stops automatic updates and removes Algolia sync from the Products menu. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Uninstalling doesn't change your Algolia index. The records the app sent stay there until you delete them in Algolia.
The app adds no fields to Swell records. Each active product becomes one Algolia record:
| Field | Description |
| objectID | The Swell product ID. |
| name, description, content, meta_description, slug | Product fields, as in Swell. |
| price, orig_price, currency, sku | Product price fields and SKU. |
| images | Product images, with id, caption, and the file url, width and height. |
| stock_status, stock_tracking, stock_purchasable | Product stock fields. |
| attributes | Product attributes. |
| bundle, bundle_items | For bundles, the quantity and name of each bundled product. |
| categories | The full path of every category the product is in, for category filters. |
| Levels (lvl0, lvl1, and so on) of each nested category path, named after the category, for the hierarchical menu. | |
| Localized values when the store has more than one language, for example name_fr. meta_title, meta_description and tags are then left out. |
Category paths keep the spacing of the built-in integration, for example Clothing > Shirts . Fields with empty, zero or false values are left out of the record.
Automatic updates run in a function on the product.created, product.updated and product.deleted events. Algolia errors with a 4xx status, such as a wrong key or an oversized record, are not retried. 5xx and network errors are retried.
The private route /functions/algolia/sync-products sends one page of products, the same as the sync page. Call it with page, and optionally limit and created_after, then with the next page until the response has done: true. This writes to Algolia.
swell api post /functions/algolia/sync-products --body '{"page": 1, "limit": 100}'The response has page, limit, count, synced and done.
Swell builds and maintains the Algolia app. For help with the app, email support@swell.is. For questions about your Algolia account, plan or search setup, contact Algolia.