# Segment

Source: https://developers.swell.is/app-guides/segment

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.

## How it works

| 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. |

## Before you begin

- 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.

## Set up

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.

**1. 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**.

**2. 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.

**3. 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.

**4. 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**.

**5. 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.

## Using Segment

### Event names

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**.

### Event data

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.

### Choosing events

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.

### Pausing

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

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 |

### Available events

| 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 |

## Limitations

- 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.

## Troubleshooting

### Events don't show in the Segment Debugger

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:

```sh
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.

### Events show up twice in Segment

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.

### Some large events never arrive

Segment rejects events over 32 KB, such as orders with many items. These events can't be sent with the app.

### A destination shows every event under one user

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

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**.

## For developers

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:

```json
{
  "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.

## Support

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.