Brevo

The Brevo app keeps your store's customers in sync with Brevo contacts, and sends cart and order events you can use to trigger Brevo automations. Customers who accept email marketing are added to your email list, and customers who accept SMS marketing can have their phone number saved for SMS.

With order sync on, orders also go to Brevo eCommerce for revenue reporting and segmentation. An action in the dashboard imports the customers you already have.

Events and orders are sent only for carts and orders linked to a customer account with an email. Each event can be turned off in the app settings, and nothing is sent while Enabled is off.

Install Brevo from the Swell App Store, and set it up in your test environment before the live one.

Each event reaches Brevo with its name below and the customer's email, so you can use it to trigger automations. For example, trigger cart recovery emails on cart_abandoned, order follow-ups on order_submitted and review requests on order_fulfilled.

Each event's properties are the cart's or order's id, number, status, currency, grand_total, sub_total, discount_total, tax_total, shipment_total, coupon_code and items, and for carts checkout_url, which brings the shopper back to their cart. Each item has id, product_id, variant_id, name, slug, sku, image_url, quantity, price, price_total and discount_total. Amounts are in the record's currency, not in cents. Properties without a value in Swell are left out.

Each event also sends the customer's first and last name as contact properties, under the attribute names in the settings.

A cart is usually created when the shopper adds the first item. At that point most carts don't have a customer yet, so checkout_started is sent only for carts that do, such as a cart started by a customer who's logged in.

Swell marks a cart abandoned 3 hours after its items, shipping or billing details last changed, or after the delay set for the abandoned cart email in Settings > Notifications. Swell marks carts abandoned whether that email is on or off. A cart that's abandoned again after the shopper comes back sends cart_abandoned again. If Brevo sends your cart recovery emails, turn off Abandoned cart in Settings > Notifications, so customers don't get both.

Each customer account with an email becomes a Brevo contact, identified by email, with the first and last name. Account changes that don't affect the contact, such as a new order count, aren't sent.

With Sync phone for SMS opt-ins on, a customer who accepts SMS marketing gets their phone number in the contact's SMS attribute. The app uses the account's phone number, or the phone number of its shipping or billing address. Numbers without a country code use the shipping country, or the billing country, and are sent in international format, such as +15035550142. Numbers that aren't valid are left out.

If Brevo refuses the number, for example because another contact already has it, the contact is saved without it. A customer who turns off SMS marketing in Swell keeps their number in Brevo.

To create contacts for the customers you already have, go to Apps > Brevo, choose Actions > Import existing customers, and click Start import. To import only customers who accept email marketing, check Only customers who opted in to email first.

Import existing customers is in the Actions menu only while Sync customer accounts is on.

With Sync orders to Brevo eCommerce on, each order is sent to Brevo eCommerce when it's placed, and sent again when it's fully fulfilled or canceled. Each order has its order number, total, creation and update dates, the customer's email, the coupon, and each item's product ID, variant ID, price and quantity.

The order's status is its status in Swell, such as payment_pending, delivery_pending, complete or canceled. Brevo's copy is updated only at those three moments, so payments, refunds and edits in between aren't sent. Orders are sent whether or not their events are turned on.

Settings are in Apps > Brevo > Settings and are saved separately for each environment.

API key and Enabled are at the top. The other settings are on the Contacts, Events and eCommerce tabs.

Test connection and Import existing customers show their messages in the dashboard. The app also logs each contact, event and order it sends, and each error. In the Swell dashboard, the logs are under Developer > Console > Logs.

Check that Enabled is on and the API key is filled in, and click Save settings. The logs show "Brevo: missing API key in app settings" when the key is empty. Then choose Actions > Test connection. Changes made while the app was off aren't sent later. To bring contacts up to date, run Import existing customers.

Test connection checks the saved settings. Enter the key and click Save settings before you test.

Copy the key again from Settings > SMTP & API > API Keys in Brevo, and check that it starts with xkeysib- and hasn't been deleted. Paste it, click Save settings, and test again.

Brevo's Authorized IPs check is on, so Brevo refuses calls from the app even with a valid key. Swell has no fixed IP addresses to add. In Brevo, go to Security > Authorized IPs, turn off blocking of unknown IP addresses, and run Test connection again. While it's on, every sync and event fails with a 401 in the logs, and the import counts every customer as failed.

Check the Email list ID against Contacts > Lists in Brevo. The message shows only when Brevo answers that the list doesn't exist.

Brevo answered the list check with an error, and its reason follows the message. When the message says try again, Brevo couldn't be reached, rate-limited the app or had a server error: test again in a minute.

Brevo answered with another error or couldn't be reached. The reason follows the message. Try again in a minute.

Check that the customer accepted email marketing: the Swell customer page shows Accepts email marketing. Then check that Sync customer accounts is on and the Email list ID is right. Customers who existed before you set up the app are added when you run Import existing customers.

Check that Sync phone for SMS opt-ins is on, that the customer page shows Accepts SMS marketing, and that the customer has a valid phone number with a country code, or a shipping or billing country. The logs show "Brevo: SMS rejected for …, retrying without it" when Brevo refuses the number, for example because another contact has it.

Check that First name attribute and Last name attribute match the names of the contact attributes in your Brevo account.

The logs show "Brevo: checkout_started skipped", or the name of another event, followed by "has no customer email" when the cart or order isn't linked to a customer with an email. Also check that the event is turned on in the Events tab. cart_abandoned arrives only after Swell marks the cart abandoned.

An event that failed with a network error, timeout or Brevo server error is logged with "(not retried, Brevo may have recorded it)" and isn't sent again.

Check that Sync orders to Brevo eCommerce is on and that eCommerce is activated in Brevo. Orders are sent when they're placed, fully fulfilled or canceled after you turn it on. The logs show the reason when Brevo refuses an order, after "order sync for order" and the order ID.

When Brevo refuses the import to your list for a group of customers, the logs show "Brevo: import job for … contacts rejected, syncing them one by one:" with Brevo's reason, and those customers are created or updated one by one instead. If that fails too, for example because the list was deleted, they're counted as failed. Check the Email list ID and the Authorized IPs setting with Actions > Test connection, then run the import again.

Brevo adds the customers who accept email marketing to your list in a background job of its own, so the logs don't show contacts that Brevo refuses there, and the totals count them as added to list.

The import fails without sending anyone, with "Import not started: the Brevo app is disabled in its settings." when Enabled is off, or "Import not started: add your Brevo API key in the app settings." when the API key is empty. Fix the setting, click Save settings, and run the import again.

Enabled was turned off or the API key was removed while the import was running. The import finished the 100 customers it was sending and stopped before the next 100. The message gives the reason and the totals sent until then, such as "Import stopped: the app was disabled in settings. Before stopping: added to list 100, synced 0, skipped 0, failed 0." Fix the setting, click Save settings, and run the import again. Customers already sent are updated, not duplicated.

Open the run on the Workflows tab to see its error and the step that failed. On temporary errors, such as when Brevo can't be reached, rate-limits the app or has a server error, each group of 100 customers is tried up to 5 more times before the import fails. Running the import again is safe.

Turn on Sync customer accounts and click Save settings.

Uninstalling the app stops syncing contacts and sending events and orders to Brevo, so automations triggered by the app's events don't start for new activity. It removes the app's functions and settings, including the API key, and the Test connection and Import existing customers actions. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

Contacts, list members, events and orders already in Brevo stay there. The app isn't notified when it's uninstalled, so if you no longer need the API key, delete it in Brevo under Settings > SMTP & API > API Keys. To pause syncing without uninstalling, turn off Enabled.

The app adds no fields to Swell records. It reads its settings from brevo in the app settings, applies the defaults to values not saved yet, upper-cases the attribute names, and accepts the list ID as 7 or #7. Every function except test-connection stops when enabled is false or api_key is empty.

All calls go to https://api.brevo.com/v3 with the api-key header:

An event payload looks like this. No event_date is sent, and contact_properties is left out when the account has no name:

{
  "event_name": "order_submitted",
  "identifiers": { "email_id": "maya.chen@example.com" },
  "contact_properties": { "FIRSTNAME": "Maya", "LASTNAME": "Chen" },
  "event_properties": {
    "id": "6acc9e5f3b1d2a0012f4c771", "number": "1042", "status": "delivery_pending", "currency": "USD",
    "grand_total": 128, "sub_total": 118, "discount_total": 0, "tax_total": 10, "shipment_total": 0,
    "items": [{
      "id": "6acc9e5f3b1d2a0012f4c772", "product_id": "66e1a7c09b3f2a0012c5d8e5",
      "name": "Oak Desk Lamp", "slug": "oak-desk-lamp", "sku": "LAMP-OAK",
      "image_url": "https://cdn.schema.io/alder/lamp.jpg",
      "quantity": 1, "price": 118, "price_total": 118, "discount_total": 0
    }]
  }
}

The eCommerce order has id (the order number, or the order ID without one), status (the Swell order status, not mapped), amount (grand_total), createdAt and updatedAt (from date_created and date_updated, in YYYY-MM-DDTHH:mm:ssZ), identifiers.email_id, products with productId, variantId, price and quantity, and coupons with the coupon code.

SMS numbers are parsed with libphonenumber-js's parsePhoneNumberWithError, using the account's phone, then shipping.phone, then billing.phone, with shipping.country or billing.country as the default country. Numbers that fail to parse or isValid() are dropped, and the rest are sent as E.164.

For contacts and eCommerce orders, network errors, 429 and 5xx responses are rethrown, so Swell retries the function. Events are rethrown only on a 429 (handleEventError): after a network error or 5xx Brevo may have recorded the event, so it's logged with (not retried, Brevo may have recorded it). Other errors are logged with console.error and the function succeeds. In order-events, the order sync runs first, then the event. A retryable order sync failure is rethrown before the event is sent, and a retry repeats the order sync, which updates the same order. A 401 whose message mentions an IP address or authorised_ips is Brevo's Authorized IPs check (BrevoError.ipBlocked), which Test connection reports apart from a rejected key.

The step load settings returns only enabled and has_api_key, so the API key isn't stored in the run's step output. Each page step reads the settings again and uses them for that page. The workflow returns imported, upserted, skipped and failed. When enabled is false or api_key is empty, it throws instead, so the run ends as failed: with Import not started: … before the first page, or with Import stopped: … and the totals so far when a page step finds the app disabled or the key removed. The modal's only_optin value arrives in req.data.

Swell builds and maintains the Brevo app. For help with the app, email support@swell.is. For questions about your Brevo account, automations or lists, contact Brevo.