Segment Integration

What this is

Pass Studio records one event for each thing that happens to a pass: a share page viewed, a card installed, a code redeemed, a loyalty balance changed, an order processed. Each event is written to Pass Studio's own analytics first, then forwarded to your Segment source as one track call to https://api.segment.io/v1/track, authenticated with your write key, with a 3-second timeout. Forwarding is best-effort: a failed call is recorded as the connection's last error, is not retried, and never affects a pass, a redemption, or the data inside Pass Studio. There is no Segment catalog app to install and no approval step; the source is a self-serve HTTP API source in your own workspace.

Setup, step by step

1. In Segment, open Connections → Sources → Add source, choose HTTP API, name it (for example "Pass Studio"), and create it. The HTTP API source is on every Segment plan, including the free one.
2. On the new source, open Settings → API Keys and copy the Write Key.
3. In Pass Studio, open Settings → Integrations → Segment. If you work in teams, first pick the workspace in the team switcher: the connection belongs to the workspace that is active when you save it.
4. Paste the write key and click Connect. Pass Studio stores the key and shows it masked.
5. Set the Customer profiles privacy sheet (see below): pick a preset or check the boxes yourself. The default is Anonymous personas.
6. Optionally list Link parameters (for example gclid, fbclid, a promo code key). Each one is forwarded under its own name on views and installs; a parameter you do not list is never sent.
7. Click Send test event. Within a few seconds the Debugger tab of your Segment source shows a track call named Pass Studio Test Event with anonymousId test:<your workspace id> and one property, source: "settings-test-button".

From that moment every new event is forwarded. Events from before the connection are not replayed. Destinations you have wired in Segment (analytics, marketing automation, a warehouse) receive the events through your own Segment routing and consent settings; Pass Studio sends to the source only.

The card in Settings shows the connection's last successful send and its most recent error. Settings changes (mode, write key, disconnect) take effect within 60 seconds.

Events

Fourteen event names. The table gives, for each, the exact trigger, the complete list of properties it can carry, and the identity it is sent under. A property is present only when its value is known; absent properties are omitted, never sent as null. The same events, with their warehouse, webhook and Zapier names, are in the Event Reference.

Not forwarded, on purpose: the wallet plumbing events register, unregister and fetch (devices subscribing to updates and pulling new versions), the daily health_check, and the membership counter events visited and member_updated. They would be noise in a marketing workspace. The install signal is Pass Installed.

Properties reference

Every property that can appear on any event, with its type, the events that carry it, where the value comes from, and an example. Property names are camelCase except the five Order Completed fields, which follow Segment's e-commerce spec (order_id, total, currency, products, coupon) so revenue-aware destinations recognize them without mapping.

Two kinds of campaign fields

The utm* fields describe the event's own touch: the link that was opened for a view or an install, the channel for an order or a redemption. The acquisition* fields describe the first touch: the link that created the card, stamped once at creation and carried unchanged onto every later event of that card, through journey steps and loyalty loops. On Pass Installed the two coincide, so the install carries the campaign in the utm* fields and acquisitionPartner / acquisitionClickId only. A Pass Redeemed three weeks later carries utmSource = pass-studio_shopify (how the redemption reached us) and acquisitionSource = meta (what acquired the holder). Attribution reports group by the acquisition* fields.

Who the event is about

Every track call names the person it is about, in one of three ways, in this order of preference:

1. userId = the Pass Studio holder ID, when the event comes from one holder's own card: an install that identified the holder, a redemption or a scan of their own code, an order that reached their card, every loyalty event. The call also carries the card's serial as anonymousId, so Segment merges the card's earlier anonymous events onto the same profile.
2. anonymousId = the card's serial, when the card exists but no holder has been identified yet. Once the holder is identified, later calls carry both ids and Segment stitches the history onto the profile.
3. anonymousId = pass:<passId>, when no single card can be tied to the event: an order that issued nothing, an order paid with a code that every holder of a simple-mode pass shares, a journey step recorded before 2026-10-24. Pass Viewed uses the share token instead, which is the link and never a person. None of these ever lands on a person's profile.

With Holder ID off on the privacy sheet (the Events only preset), rule 1 never applies: no track call carries userId, every event rides on the card's serial, the share token or pass:<passId> as anonymousId, and no identify or alias is sent. Attribution still works per event, because the acquisition fields are on the event, not on a profile.

The holder ID is an opaque six-character identifier Pass Studio mints when a card is created (for example JZNJLI). It is the same across all of a holder's cards in your workspace, it is not derived from an email or a name, and it is the key the identify calls below use, so track events and profile traits meet on one profile.

The shared-code rule

A simple-mode pass has one barcode for every holder, so the code on an order cannot say which holder bought. Since 2026-10-24 Pass Studio finds the buyer's own card by the order's email: exactly one active card of that pass with that contact email is the buyer's, and Order Completed and Pass Redeemed then carry that holder as userId, the card's serial, and the card's own first touch in the acquisition* fields. When no card matches, or more than one does (a shared household address, two installs), both events are sent on anonymousId = pass:<passId> with no userId and no acquisition* fields at all. Another holder's card is never used. A buyer who added the pass from a link without giving an email cannot be matched and stays unattributed. From 2026-10-23 to 2026-10-24 these events carried no holder but did carry an arbitrary card's first touch; before 2026-10-23 they carried that card's holder as well. A unique-mode or pool-mode pass gives every holder their own code, and those orders always name the holder.

Every call's envelope

• timestamp: the moment the event happened, ISO 8601, UTC.
• context.library: { "name": "pass-studio", "version": "1" }.
• messageId: on Order Completed, order.processed: followed by Pass Studio's order reference. Segment drops a second call with the same messageId, so a store webhook delivered twice yields one Order Completed. Other events carry no messageId.

Customer profiles: the privacy sheet

Since 2026-10-24 Settings → Integrations → Segment carries one privacy sheet per workspace. It decides what may leave for Segment: the profile identifier, the identify traits, and which field values travel on Member Updated. Attribution fields (utm*, acquisitionSource, acquisitionMedium, acquisitionCampaign, acquisitionPartner), the pass, the platform, order amounts, points, tier, member since and visit counts are sent in every state and are not on the sheet. The sheet governs Segment only; webhooks, Zapier and Shopify Flow are unaffected.

• Core — kinds of data. Holder ID is the profile identifier: on, track calls carry the holder ID as userId with the card's serial as anonymousId, and identify and alias are sent; off, every track call carries the card's serial (or the share token, or pass:<passId>) as anonymousId and nothing else, and no identify or alias is sent. Click ID governs acquisitionClickId on track calls; partner postbacks are unaffected. Six contact classes — name, email, phone, address, birthday, member ID — each govern the identify trait of that class and the before and after values on Member Updated of any field in that class, whatever the field is called (memberName, shippingAddress, birthDate, member_id). The contact classes need Holder ID.
• General — your own field keys, the union across every pass of the workspace (draft, active and archived), each with a checkbox. Checked: the value travels on Member Updated. Unchecked, the default: the key travels, the value does not. A Staff notes row governs the note. A value shaped like an email address or an international phone number follows the Core email or phone box whatever its field.
• Presets — the three modes are named states of the sheet. Events only: nothing in Core checked. Anonymous personas, the default: Holder ID and Click ID only. Full identity: all of Core and the staff note. Any other state shows as Custom. Your General choices hold across presets. A connection made before the sheet keeps its mode as the matching preset; one that was on Full identity keeps sending every field's values, and shows every General box checked, until you save the sheet.

An identify is sent when a holder is created or identified, at install or at wallet registration. An identical identify is not sent twice for the same holder; it is sent again when a trait changes.

When Pass Studio's identity engine decides that two holder records are the same person (for example an anonymous install later matched to an order by email), it sends an alias call with previousId = the record that was merged away and userId = the surviving holder ID, so the complete history stitches onto one profile in destinations that support aliasing. With Holder ID off no alias is sent.

Complete example payloads

One holder, two events. On 2026-10-02 a customer taps a Meta ad, lands on the share page with the ad's parameters, and installs the card. The install identified the holder (an email on the form), so the call carries userId.

{
  "event": "Pass Installed",
  "userId": "JZNJLI",
  "anonymousId": "8b00f894-cda3-5355-9e78-c5c925a32efa",
  "timestamp": "2026-10-02T14:03:11.482Z",
  "properties": {
    "passId": "dqSZHxwuVVGjAtEY6P7o",
    "platform": "apple",
    "shareToken": "JSB11lYjQiAgGlD_j9GU9w",
    "utmSource": "meta",
    "utmMedium": "cpc",
    "utmCampaign": "spring_sale",
    "utmContent": "video_b",
    "utmTerm": "k1"
  },
  "context": { "library": { "name": "pass-studio", "version": "1" } }
}

Three weeks later the same person pays an order in the Shopify store with the card's own code, 1005. The order's channel is in the utm* fields, the acquiring campaign in the acquisition* fields, and the call names the same holder.

{
  "event": "Order Completed",
  "userId": "JZNJLI",
  "anonymousId": "8b00f894-cda3-5355-9e78-c5c925a32efa",
  "timestamp": "2026-10-23T09:41:07.019Z",
  "messageId": "order.processed:<our order reference>",
  "properties": {
    "passId": "dqSZHxwuVVGjAtEY6P7o",
    "platform": "web",
    "utmSource": "pass-studio_shopify",
    "utmMedium": "order",
    "utmCampaign": "order_1042",
    "acquisitionSource": "meta",
    "acquisitionMedium": "cpc",
    "acquisitionCampaign": "spring_sale",
    "order_id": "1042",
    "total": 64.9,
    "currency": "EUR",
    "products": [
      { "name": "Hydra serum 30 ml", "sku": "HS-30", "quantity": 1, "price": 64.9 }
    ],
    "coupon": "1005"
  },
  "context": { "library": { "name": "pass-studio", "version": "1" } }
}

An order paid with a shared code on a simple-mode pass, where the order email matched no card of the pass or more than one, names no one and carries no acquisition fields:

{
  "event": "Order Completed",
  "anonymousId": "pass:k2Pq7RtVwXyZ01234567",
  "timestamp": "2026-10-23T10:02:44.310Z",
  "properties": {
    "passId": "k2Pq7RtVwXyZ01234567",
    "platform": "web",
    "utmSource": "pass-studio_shopify",
    "utmMedium": "order",
    "utmCampaign": "order_1043",
    "order_id": "1043",
    "total": 19,
    "currency": "EUR",
    "products": [{ "name": "Lip balm", "quantity": 1, "price": 19 }],
    "coupon": "WELCOME10"
  },
  "context": { "library": { "name": "pass-studio", "version": "1" } }
}

Staff at the front desk award the first holder 12 points and correct the spelling of their name, with a note, in a workspace on Anonymous personas mode. The points travel as numbers, the name correction as its key alone, and the note is not sent. In Full identity mode the second entry would read { "key": "memberName", "from": "Dana Lev", "to": "Dana Levi" } and a note property would follow.

{
  "event": "Member Updated",
  "userId": "JZNJLI",
  "anonymousId": "8b00f894-cda3-5355-9e78-c5c925a32efa",
  "timestamp": "2026-10-24T16:12:40.118Z",
  "properties": {
    "passId": "dqSZHxwuVVGjAtEY6P7o",
    "platform": "web",
    "acquisitionSource": "meta",
    "acquisitionMedium": "cpc",
    "acquisitionCampaign": "spring_sale",
    "changedFields": ["points", "memberName"],
    "changes": [
      { "key": "points", "from": "35", "to": "47" },
      { "key": "memberName" }
    ],
    "pointsFrom": 35,
    "pointsTo": 47,
    "pointsDelta": 12,
    "source": "register",
    "registerId": "r_7Hq2Lk",
    "registerName": "Front desk"
  },
  "context": { "library": { "name": "pass-studio", "version": "1" } }
}

Where else the data lives

Every event is first written to Pass Studio's own analytics store (BigQuery), with more than Segment receives: the full landing query string of a view or an install, the referrer, the country, region and city derived from the request at the time, the device identifiers, and the per-event metadata listed in the Event Reference. The Analytics and Reports pages in the Studio read from it, and each report widget exports CSV. Signed webhooks and Zapier triggers come from the same stream; their payloads add the holder's contact where known and are documented on their own pages. Nothing on this page changes what BigQuery, webhooks or Zapier receive.

What Pass Studio never sends to Segment

• Email, phone number and name on any track call while their Core boxes on the privacy sheet are off (the Events only and Anonymous personas presets). With a box on, that class travels as an identify trait (email, phone, memberId) and as the before and after values of a field in that class on Member Updated; no other track call carries them in any state.
• Any URL parameter you have not allowed. Pass Studio reads utm_source, utm_medium, utm_campaign, utm_content, utm_term, pid and cid on its own; every other parameter (gclid, fbclid, msclkid, ttclid, utm_id, a promo code key, anything custom) is forwarded only when you list it under Settings → Integrations → Segment → Link parameters, under its own name, on Pass Viewed, Pass Installed and Pass Reinstalled. The full landing query string stays in Pass Studio's own analytics (BigQuery) and is never sent as a whole.
• The referrer of the share page (stored in Pass Studio's analytics only).
• Device identifiers: the Apple device library identifier, push tokens, the Google object id.
• Wallet plumbing: register, unregister and fetch events, the daily health check.
• On Member Updated: the before and after values of a field whose Core class box or General box is off, any value shaped like an email or a phone while the Core email or phone box is off, and the staff note while Staff notes is off. The field key is always sent.
• On Loyalty Tier Changed: the tier period's unit and length, and the tier's since timestamp. They are in the holder.tier_changed webhook only.
• The holder on Pass Viewed (keyed on the share link, never a person).
• Historical events from before the connection was made. Nothing is replayed.

Questions and answers

Changelog

• 2026-07-21 — Segment source launched: track calls for every pass event, Order Completed in the e-commerce spec, three profile modes, identify at install, alias on holder merge.
• 2026-10-23 — Order Completed carries the holder as userId, the card's serial as anonymousId, and the first-touch acquisition fields when the order reached one holder's own card. Loyalty Points Earned, Loyalty Reward Unlocked and Loyalty Tier Changed are keyed on the holder id instead of the program's member record id. Pass Redeemed from an online order carries the holder. utmContent and utmTerm are forwarded on views and installs. A code shared by every holder of a simple-mode pass never names a person.
• 2026-10-24 — Loyalty Tier Changed carries direction, tierIndex, tierTitle, previousTierIndex, block and blockEarned. Pass Journey Advanced carries the holder as userId, the card's serial as anonymousId, and the first-touch acquisition fields when the card that moved is one holder's own; its source values are documented as sent: scan, order, time, heal, api. Two new events: Member Visited (a counted staff-app scan of a membership card: registerId, registerName, visitCount) and Member Updated (the staff ledger entry: changedFields, changes, pointsFrom, pointsTo, pointsDelta, tier, previousTier, source, registerId, registerName; the before and after values of person-level fields and the note in Full identity mode only); both carry the holder as userId, the serial as anonymousId and the card's first-touch acquisition. Fourteen event names. Older events were not rewritten. On a code shared by every holder of a simple-mode pass, the buyer's own card is found by the order email: exactly one match names the holder and carries their first touch; none or several leaves the order and the redemption with no holder and no acquisition fields, never another holder's.
• 2026-10-24 — Link parameters: a per-workspace allowlist under Settings → Integrations → Segment. Each listed landing-URL parameter (gclid, fbclid, msclkid, a promo code key, anything) is forwarded under its own name with its value on Pass Viewed, Pass Installed and Pass Reinstalled. A parameter not listed is never sent; the full query string stays in Pass Studio's analytics. On every later event of a card the value is the acquiring link's, kept from the card's creation.
• 2026-10-24 — The privacy sheet replaces the three radio buttons under Settings → Integrations → Segment. Core: Holder ID (the profile identifier — off means no userId, no identify, no alias), Click ID, and six contact classes (name, email, phone, address, birthday, member ID) that govern identify traits and Member Updated values of any field in the class. General: every field key your passes define, value on or off, plus Staff notes. The three modes are presets of the sheet; anything else is Custom. New identify trait phone with the Phone box. A connection from before the sheet keeps its mode as the matching preset.
• 2026-10-24 — Pass Redeemed from a staff-app counter scan, a Square register sale or an API redemption (POST /v1/redeem, POST /v1/loyalty/redeem) carries the holder as userId and the card's serial as anonymousId when the scanned code is one holder's own (unique or pool mode, a membership card, a loyalty card). Before, those channels carried the first touch but no holder and sat on anonymousId pass:<passId>.

Questions?

Email support@thepassstudio.com or use the assistant in the bottom-right corner of the dashboard.