App guides
The Omnisend app keeps Omnisend up to date with your Swell store. Customers, carts, orders and products are sent to Omnisend as they change, so Omnisend automations, like abandoned cart emails and order follow-ups, run on your store's data. A page in your Swell dashboard sends your existing contacts, products and orders when you first connect.
The app replaces Swell's built-in Omnisend integration and syncs the same records.
| When | What the app does |
| A customer account is created | Creates the contact in Omnisend, subscribed to email if the customer accepts email marketing. |
| A customer account is updated | Updates the contact's name and address. |
| A cart linked to a customer is created or updated | Creates or updates the cart in Omnisend, with a link back to checkout. |
| A cart is deleted | Deletes the cart in Omnisend. |
| An order is placed | Creates the order in Omnisend. |
| An order is updated | Updates the order, including its payment and fulfillment status. |
| A product is created, updated or deleted | Creates, updates or deletes the product in Omnisend. A variant change updates its product. |
| You run a sync from Omnisend sync | Sends existing contacts, products or orders to Omnisend in batches. |
Nothing is sent until Enable Integration is on in the app settings.
- An Omnisend account, and an API key with access to Contacts, Products, Carts and Orders. You create it in Omnisend in step 1.
- Your storefront's URL, starting with https://. The app uses it to build product and cart item links.
- If your store uses Swell's built-in Omnisend integration, plan to turn it off when you install the app. Running both sends every change to Omnisend twice.
Install Omnisend from the Swell App Store, and set it up in your test environment before the live one.
If the built-in Omnisend integration is on when you install the app, Swell asks how to handle the conflict. Click Disable conflicting integration to turn off the built-in integration and install the app. Ignore conflict installs the app and leaves the built-in integration on. You can turn the built-in integration on again later from Integrations, and its settings are kept.
Create an API key
In Omnisend, go to Store settings > API keys and click Create API key. Name it, for example Swell, give it access to Contacts, Products, Carts and Orders, then create it and copy the key. Omnisend shows the key only once.
Add it to the app
In Swell, go to Apps > Omnisend > Settings. Enter the API Key and your Store URL, turn on Enable Integration, and click Save settings. From now on, changes in your store are sent to Omnisend.
Sync your existing data
Open Omnisend sync in your dashboard menu. With All records selected, click Sync contacts and Sync products, and when both show Complete, click Sync orders. Keep the page open until each sync completes.
Place a test order
Place a test order as a customer who accepts email marketing. In Omnisend, go to Audience > Contacts and open the customer. The Email channel shows in Channels, and Placed order is in the contact activity.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 and 3. Use a separate Omnisend store for the test environment, so test customers and orders stay out of your live audience.
- Records to sync: All records, or Records created on or after a date. The date is the start of that day in your time zone. These options apply to every sync and are locked while one is running.
- Page size: 10, 100, 200, 500 or 1000 records per request.
- Contacts, Products and Orders each have their own row, with a progress bar, the number of records sent and the details of any error. Sync contacts and products before orders.
- Stop finishes the page in progress, then stops. Resume from page continues with the same options. 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.
- Syncing contacts also lets the app update customers who existed before you installed it.
A contact is created with the customer's name, address and email. Customers who accept email marketing are subscribed to email, and the others are added as not subscribed. The opt-in is sent once, when the contact is created or synced. Later changes to the customer's name or address are sent to Omnisend, but changes to their opt-in aren't, so manage consent in Omnisend after that.
Carts linked to a customer are sent with their items, total, currency and a link back to checkout, and kept up to date as they change. Use them in Omnisend's abandoned cart automation. Carts without a customer aren't sent, because Omnisend needs an email.
Orders are sent with their items, totals, addresses, shipping method and statuses, and updated when they change:
- Payment status: paid, partially paid, awaiting payment, refunded or partially refunded.
- Fulfillment status: fulfilled when the order is delivered with no returned items, and unfulfilled while items are still to be delivered.
- Canceled orders get the cancel date from Swell.
Products are sent with their name, description, tags, stock status, first image and variants, with sale and option prices. Product and item links are your Store URL followed by the product's SKU or slug, for example https://alderandco.com/linen-shirt.
With Use Display Locale on, carts and orders placed in another language are sent in that language, so product names match what the customer saw.
Settings are in Apps > Omnisend > Settings and are saved separately for each environment.
| Setting | Description | Default |
| API Key | Your Omnisend API key, with access to Contacts, Products, Carts and Orders. Required. | None |
| Store URL | Your storefront URL, starting with https://. Used for product and cart item links. Required. | None |
| Enable Integration | Sends store changes to Omnisend. The Omnisend sync page needs it on too. | Off |
| Use Display Locale | Sends carts and orders in the customer's language. | Off |
- Email consent is sent only when a contact is created or synced. Later opt-in changes in Swell aren't sent.
- SMS consent isn't synced. Phone numbers are sent as contact properties, not as an SMS channel.
- Customers who existed before the app was installed are updated in Omnisend only after you sync contacts.
- Carts without a customer aren't sent.
- Product links are your Store URL followed by the SKU or slug. If your storefront serves products at another path, the links in Omnisend emails won't match it.
- Changes aren't retried. If Omnisend rejects a change or can't be reached, the error is logged and the change isn't sent again.
- Omnisend processes each synced page in the background. A page counts as sent once Omnisend accepts it, and Omnisend can still reject a record in it afterwards.
The app logs each change it sends and each error. In the Swell dashboard, the logs are under Developer > Console > Logs.
Check that Enable Integration is on and that the API Key is filled in, then save the settings. Changes made while the integration was off aren't sent later; run a sync to send them.
The page shows "Omnisend integration is disabled in app settings" or "Omnisend API key is not set in app settings". Fill in the API Key, turn on Enable Integration and save, then start the sync again.
Open Error details under the error to see the response from Omnisend. Fix the cause, then click Resume from page.
Sync contacts and products before orders, then sync orders again.
The app updates contacts it created or synced. For customers who existed before the app was installed, sync contacts from Omnisend sync.
Check Store URL. Links are the Store URL followed by the product's SKU or slug, so they only work if your storefront serves products at that path.
Uninstalling the app stops sending changes to Omnisend and removes Omnisend sync from your dashboard menu. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Contacts, carts, orders and products already in Omnisend stay there. To sync with the built-in integration again, turn it on in Integrations.
The app sends records to the Omnisend API v3 with the API key. Amounts are sent in cents, and order numbers with digits only.
| Function | Runs on |
| account-events | account.created, account.updated |
| cart-events | cart.created, cart.updated, cart.deleted |
| order-events | order.submitted, order.updated |
| product-events | product.created, product.updated, product.variant.updated, product.deleted |
After creating a contact, the app saves the contact's email on the account in omnisend_email, and uses it to find the contact on later updates. The sync page calls the app's frontend Worker, which only accepts requests from a signed-in dashboard user of the store.
The private route /functions/omnisend/sync sends one page of an entity, the same as the sync page. Call it with entity (contacts, products or orders) and page, and optionally limit and created_after, until the response has done: true. Without entity, it runs the whole sync in one request, which can stop at the function timeout on large stores. This writes to Omnisend.
swell api post /functions/omnisend/sync --body '{"entity": "contacts", "page": 1, "limit": 100}'The response has entity, page, limit, count, synced and done. The route /functions/omnisend/validate-login checks an API key by creating a test contact, validate@test.com, in Omnisend.
Swell builds and maintains the Omnisend app. For help with the app, email support@swell.is. For questions about your Omnisend account, automations or audience, contact Omnisend.