App guides
The Segment app sends your store events to Segment as track calls. You choose the events, such as orders, carts and customers, and each one arrives in your Segment source with a readable name, like Order Paid, and the record as its properties. From Segment, you can send the events on to the destinations you connect there.
The app replaces Swell's built-in Segment integration and sends the same event names and data.
| When | What the app does |
| An event you checked happens in your store | Sends a track call to Segment with the event name, the record as properties, and your store ID as the user ID. |
| An event you didn't check happens | Nothing. The event isn't sent. |
| Segment can't be reached or returns a server error | Swell retries the event later. Segment ignores repeat deliveries of the same event. |
| Segment rejects the event, for example because it's over 32 KB | Logs the error. The event isn't sent again. |
- A Segment workspace and a source to receive the events. An HTTP API source works, or another server-side source you already use.
- The source's write key, from Settings > API Keys on the source in Segment.
- Your workspace's region. Workspaces are in the US unless EU data residency was set up for your Segment account.
- If your store uses Swell's built-in Segment integration, plan to turn it off when you install the app. Running both sends the events that are on in both to Segment twice.
Install Segment from the Swell App Store, and set it up in your test environment before the live one.
If the built-in Segment 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.
Copy your write key
In Segment, go to Connections > Sources and open the source that should receive the events. Go to Settings > API Keys and copy the Write Key. To add a source, click Add Source and choose HTTP API.
Add the key to the app
In Swell, go to Apps > Segment > Settings and paste the key in Segment write key. In Segment region, choose the region of your Segment workspace, US or EU. Keep Enabled on.
Choose the events
Under Events, check the events to send, then click Save settings. No events are checked at first, so nothing is sent until you check at least one.
Send a test event
Trigger one of the events you checked. For example, check account.created and create a test customer. In Segment, open the source's Debugger. The event shows up as a track call named Account Created.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 and 3 with the write key of the source for your live data. Use a separate Segment source for the test environment, so test events don't mix with live data.
The Swell event type is split into words and each word is capitalized. order.paid becomes Order Paid, order.payment_failed becomes Order Payment Failed, and product.review.created becomes Product Review Created.
The properties of each event are the record it's about: the order for order events, the cart for cart events, the customer for account events, and so on. Records include personal data, such as customers' names, email addresses and addresses, and that data is sent to Segment too.
Events are grouped by model. Check only the events you use in Segment. Changes apply to events that happen after you save, and events you uncheck stop being sent.
Turn off Enabled and save to stop sending events. Your write key and event selection are kept. Events that happen while sending is paused aren't sent later.
Settings are in Apps > Segment > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Segment write key | Write key of the Segment source that receives the events. Required. | None |
| Segment region | Region of your Segment workspace: US (api.segment.io) or EU (events.eu1.segmentapis.com). | US |
| Enabled | Sends the events you checked. Turn off to pause sending without losing your settings. | On |
| Events | One list of events for each model. Only checked events are sent. | None checked |
| Model | Events |
| Account | account.created, account.updated, account.deleted, account.card.created, account.card.updated, account.card.deleted, account.address.created, account.address.updated, account.address.deleted, account.credit.created, account.credit.updated, account.credit.deleted |
| Cart | cart.created, cart.deleted, cart.converted, cart.abandoned |
| Category | category.created, category.updated, category.deleted, category.product.added, category.product.removed |
| Coupon | coupon.created, coupon.updated, coupon.deleted, coupon.code.created, coupon.code.deleted, coupon.generation.completed |
| Invoice | invoice.created, invoice.updated, invoice.deleted, invoice.payment_succeeded, invoice.payment_failed |
| Order | order.created, order.updated, order.deleted, order.submitted, order.canceled, order.paid, order.payment_failed, order.refunded, order.delivered, order.trial_started, order.trial_will_end, order.trial_ended |
| Page | page.created, page.updated, page.deleted |
| Payment | payment.succeeded, payment.failed, payment.voided, payment.refund.succeeded, payment.refund.failed, payment.refund.voided |
| Product | product.created, product.updated, product.deleted, product.stock_adjusted, product.variant.created, product.variant.updated, product.variant.deleted, product.review.created, product.review.updated, product.review.deleted |
| Promotion | promotion.created, promotion.updated, promotion.deleted |
| Shipment | shipment.created, shipment.updated, shipment.deleted, shipment.canceled |
| Subscription | subscription.created, subscription.updated, subscription.deleted, subscription.activated, subscription.trial_will_end, subscription.trial_ended, subscription.invoiced, subscription.payment_failed, subscription.paid, subscription.canceled, subscription.paused, subscription.resumed, subscription.completed |
- The app sends track calls only. It doesn't send identify, page or group calls, so it doesn't create or update profiles of people in Segment.
- Events use your store ID as the user ID, not the customer's ID, the same as the built-in integration. Destinations that build profiles of people from the user ID attribute every event to that one ID. Customer details, such as account_id and email, are in the properties when the record has them.
- Past events aren't sent. The app sends events that happen after you check them, while Enabled is on.
- Each event is sent on its own, not in batches.
- Segment rejects events over 32 KB. A large record, such as an order with many items, can go over this limit. Rejected events aren't sent again.
- The region must match your Segment workspace. Segment rejects events sent to the other region.
- Segment's plan limits apply to the events you send.
Check that Enabled is on, that the event is checked under Events, and that the write key belongs to the source whose Debugger you're looking at. Then check Segment region. It must match your workspace, which is in the US unless EU data residency was set up for your Segment account.
To check the region, send a test event with your write key from a terminal, then look for Region Test in the source's Debugger:
curl -u '<write_key>:' https://api.segment.io/v1/track \
-H 'Content-Type: application/json' \
-d '{"userId":"region-test","event":"Region Test"}'If it doesn't arrive, send it again to https://events.eu1.segmentapis.com/v1/track. If that one arrives, set Segment region to EU.
The built-in Segment integration is probably still on. Turn it off in Integrations. If the test and live environments use the same write key, events from both arrive in the same source. Use a separate source for each.
Segment rejects events over 32 KB, such as orders with many items. These events can't be sent with the app.
Every event uses your store ID as the user ID. In destinations that let you map fields, use the customer fields in the properties, such as account_id or email.
Uninstalling the app stops sending events to Segment. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Events already sent stay in Segment and in your destinations. To send events with the built-in integration again, turn it on in Integrations.
The app adds no fields to Swell records. Each event is sent to Segment's HTTP Tracking API as a track call: a POST to /v1/track on the endpoint of your region, with the write key as the username for basic authentication. The body looks like this:
{
"userId": "<store id>",
"event": "Order Paid",
"properties": { "id": "...", "number": "100482", "grand_total": 128, "...": "the rest of the order" },
"messageId": "<swell event id>",
"timestamp": "2026-10-01T14:24:51.112Z",
"context": { "library": { "name": "swell-app-segment", "version": "1.0.0" } }
}| Field | Description |
| event | The Swell event type, split on . - and _, with each word capitalized. |
| properties | The event's record, without Swell's $event metadata. |
| userId | The store ID, or the Swell event ID if there's no store ID. |
| messageId | The Swell event ID. Segment deduplicates on it, so a retried event isn't counted twice. |
| timestamp | When the app sent the event. A retried event has the time of the retry. |
| context.library | swell-app-segment and the app version. |
Each model has its own function, track-<model>, that runs on all of the model's events. Events that aren't checked return without calling Segment. Segment errors with a 4xx status, such as an event over 32 KB, are logged and not retried. 5xx and network errors are retried.
The app logs each event it sends, and each event it can't send because the write key is missing or Segment rejected it. With the Swell CLI, swell logs --type function --app segment shows the logs.
Swell builds and maintains the Segment app. For help with the app, email support@swell.is. For questions about your Segment workspace, sources or destinations, contact Segment.