Advanced segments

An advanced segment’s membership is set by its definition. You send a definition when you create or update a segment with POST /3.0/segments or PATCH /3.0/segments/{segment_id}, and GET /3.0/segments/{segment_id} returns it. Working with advanced segments requires a Mailchimp plan that includes advanced segmentation.

A definition is a tree:

• Groups combine their children with AND or OR.
• Conditions each test one thing about a contact, such as an email address, a tag, a campaign they opened or a purchase they made.
• The root of the tree is always a group. It may also say which contacts are in scope at all (the contacts object).

{
  "contacts": { "email": { "marketing": [ { "sendable": true } ] } },
  "match": "all",
  "conditions": [
    { "field": "merge0", "op": "contains", "value": "@example.com" },
    {
      "match": "any",
      "conditions": [
        { "field": "static_segment", "op": "static_is", "value": 8662415 },
        { "field": "rating", "op": "greater", "value": 3 }
      ]
    }
  ]
}

This selects subscribed email contacts whose address contains @example.com and who either carry tag 8662415 or have a contact rating above 3.

Read-only segments

Every segment in a list or a read carries read_only:

When you create a segment, definition is required, and its root group must have match and conditions. When you read one, definition is present only if read_only is false. read_only can’t be sent in a PATCH.

Creating an advanced segment, or updating or taking a snapshot of one, requires an account whose plan includes advanced segmentation. Without it, those requests return a 403. Snapshots of read-only segments don’t need it.

The rest of this page describes definitions, so it applies to segments that aren’t read-only.

Compatibility

Within an API version, existing fields keep their names, types and meaning, and aren’t removed. Mailchimp may add new fields, both to responses and to definitions, without a new version. Ignore fields you don’t recognize rather than rejecting the response.

Groups

Groups nest up to 2 levels deep, counting the root: a root group can hold conditions and groups, and those groups hold only conditions. This is the deepest segment the segment builder can edit.

{
  "match": "all",
  "conditions": [
    { "field": "merge0", "op": "notcontain", "value": "@competitor.com" },
    { "field": "static_segment", "op": "static_not", "value": 1234 }
  ]
}

This selects contacts whose address doesn’t contain @competitor.com and who don’t carry tag 1234.

Conditions

A condition has a field naming what it tests, an op saying how, and usually a value. Which ops, values and filters a field accepts is listed per field in the condition reference.

Any other key is rejected with a 400.

{
  "field": "email_campaign_activity",
  "op": "open",
  "filters": [
    { "field": "campaign", "op": "is", "value": 17795293 }
  ]
}

This selects contacts who opened campaign 17795293 (its web_id).

Contacts in scope

The root’s contacts object limits the segment to contacts in particular subscription states, per channel, before any condition applies. Omit it to include every contact on every channel: email, SMS and WhatsApp. When present it must name at least one entry.

{
  "contacts": {
    "email": {
      "marketing": [ { "sendable": true } ],
      "transactional": [ { "sendable": true } ]
    },
    "sms": { "marketing": [ { "sendable": true } ] }
  },
  "match": "all",
  "conditions": []
}

Each channel holds lists of entries. A contact is in scope if it matches any entry on any channel.

Also accepted:

• "consent": "confirmed" may accompany any entry. It covers the same contacts as the entry without it.
• email.marketing {"sendable": false, "consent": "unknown"} is the same population as email.transactional {"sendable": true}.
• email.transactional {"sendable": false} is valid but covers no contacts.

Rejected with a 400:

• "sendable": true with any consent other than "confirmed", or with any reason.
• consent and reason in the same entry.
• "consent": "consented".
• reason on SMS or WhatsApp.
• sms.transactional and whatsapp.transactional, which are reserved.

Ids in condition values

Some conditions name another Mailchimp object.

• Campaigns: use the campaign’s web_id, the integer returned by GET /3.0/campaigns, not its id.

• Tags and static segments (static_segment): use the tag’s or segment’s numeric id from GET /3.0/lists/{list_id}/segments.

• Beta: interest groups, marketing permissions and e-commerce stores. These conditions take Mailchimp’s internal id, which other API endpoints don’t return. To find it:

  1. Build an advanced segment in Mailchimp that uses the interest, permission or store.
  2. Read that segment with GET /3.0/segments/{segment_id}.
  3. Copy the value from its definition.

  The format of these conditions may change.

Limits

A definition over either limit is rejected with a 400 that names the limit. Limits apply when you write a definition. A segment built in Mailchimp that exceeds them still reads back normally, but writing that definition back returns a 400.

Errors

Errors use the standard Marketing API error format.

Plan without advanced segmentation. Creating an advanced segment, updating one, or taking a snapshot of one returns HTTP 403 when the account’s plan doesn’t include advanced segmentation:

{ "title": "Forbidden", "status": 403, "detail": "This account's plan doesn't include advanced segmentation." }

Invalid definitions return HTTP 400.

• Structural problems put the reason in detail, for example an unknown key, a bad match, a misplaced contacts or an exceeded limit:

  { "title": "Bad Request", "status": 400, "detail": "'match' must be \"all\" or \"any\"" }

• Condition problems set detail to segment conditions failed validation, with one errors[] entry per reason, for example an op a field doesn’t support or a value out of range:

  {
    "title": "Invalid Resource",
    "status": 400,
    "detail": "segment conditions failed validation",
    "errors": [ { "field": "definition", "message": "op must be one of is | not | contains | notcontain | starts | ends | greater | less | blank | blank_not" } ]
  }

Reading a definition back

GET /3.0/segments/{segment_id} returns the definition in the same format, with a few normalizations. Each one selects the same contacts you wrote:

• contacts lists one entry per subscription state. Broad spellings come back as the states they cover. For example, email.marketing [{"sendable": false}] reads back as three entries: unsubscribed, cleaned and transactional-only. A segment created without contacts reads back with every state listed. Writing the response back unchanged stores the same scope.

• A root that mixes conditions with groups reads back with its conditions wrapped in one group of the same match. The groups stay where they were, beside that wrapper. A root that holds only conditions, or only groups, reads back unchanged.

  { "match": "all", "conditions": [
      { "field": "merge0", "op": "starts", "value": "a" },
      { "field": "rating", "op": "greater", "value": 3 },
      { "match": "any", "conditions": [ { "field": "static_segment", "op": "static_is", "value": 1234 } ] }
  ] }

  reads back as

  { "match": "all", "conditions": [
      { "match": "all", "conditions": [
          { "field": "merge0", "op": "starts", "value": "a" },
          { "field": "rating", "op": "greater", "value": 3 }
      ] },
      { "match": "any", "conditions": [ { "field": "static_segment", "op": "static_is", "value": 1234 } ] }
  ] }

• Empty extra values are omitted, and schema_version is always 2.

Condition reference

Fields are grouped by what they test. Each section lists the ops, the value format, the filters, and an example.

Availability, per field:

• Generally available: works for every audience.

• Requires …: depends on data or an integration the audience must have, for example a connected store.

• Beta: works, but its format may change.

• Contact data and audience membership

• Email, SMS and WhatsApp engagement and status

• E-commerce conditions

• Predictive insights and integrations

• Events

Contact data and audience membership

These conditions select contacts by what is stored on their profile: email address, merge fields, language, VIP status, rating, key dates, signup source, tags, groups, subscription status, marketing permissions, age gating and predicted location. None of them take filters. ipgeo is the only one that uses location.

There is no timezone condition. Date conditions are evaluated in a fixed timezone, which each section below names.

merge0 — Email address

Availability: Generally available Compares the contact’s email address with one or more strings.

Example:

{ "field": "merge0", "op": "ends", "value": "@example.com" }

{ "field": "merge0", "op": "notcontain", "value": ["@gmail.com", "@yahoo.com"], "value_op": "and" }

Notes:

• value is required for every op except blank and blank_not. Each entry is trimmed and must be at most 315 characters.
• value_op defaults to "or", so the condition matches if any value matches. With not or notcontain, "or" means “differs from at least one value”, which matches almost everyone. Use "value_op": "and" to mean “matches none of these”.
• If is or not is sent with an empty value ("", [] or [""]), it is saved as blank or blank_not.

merge<N> — Merge fields

Availability: Generally available Compares the contact’s value in one audience merge field. N is the field’s merge_id from GET /3.0/lists/{list_id}/merge-fields, an integer from 1 to 80 (for example merge3). The email address is merge0, documented above.

Mailchimp looks up the merge field’s type, and the type decides which ops and values are allowed. Don’t send a type yourself.

Example:

{ "field": "merge5", "op": "greater", "value": "100" }

{ "field": "merge4", "op": "geoin", "value": "25", "extra": "30303" }

Notes:

• value is required for is, not, contains, notcontain, starts, ends, date_within and date_notwithin. Each entry must be at most 315 characters.
• Number fields: every value must be numeric.
• Date fields: send YYYY-MM-DD, or an ISO date-time with an offset (YYYY-MM-DDThh:mm:ssZ). Day boundaries are evaluated in UTC. is and not use only the first value.
• Date date_within and date_notwithin take a whole number of days. Tokens like 7days or 1month are rejected, and decimals don’t behave as expected.
• Birthday values must be zero-padded ("06", not "6"). Only the first value is used.
• Dropdown and radio button values are the choice labels exactly as defined on the field.
• geoin is for fields that hold US ZIP codes. extra must be a 5-digit US ZIP code.
• value_op ("and" or "or", default "or") works as it does for merge0. Use "and" with not or notcontain to mean “matches none of these”.
• An op that isn’t allowed for the field’s type is rejected, with a message listing the ops that are valid.

language — Language

Availability: Generally available The contact’s language preference.

Language codes (case-insensitive): en English, ar Arabic, af Afrikaans, be Belarusian, bg Bulgarian, ca Catalan, zh Chinese (Simplified), zh_CN Chinese (Traditional), hr Croatian, cs Czech, da Danish, nl Dutch, et Estonian, fa Farsi, fi Finnish, fr French (France), fr_CA French (Canada), de German, el Greek, he Hebrew, hi Hindi, hu Hungarian, is Icelandic, id Indonesian, ga Irish, it Italian, ja Japanese, km Khmer, ko Korean, lv Latvian, lt Lithuanian, mt Maltese, ms Malay, mk Macedonian, no Norwegian, pl Polish, pt Portuguese (Brazil), pt_PT Portuguese (Portugal), ro Romanian, ru Russian, sr Serbian, sk Slovak, sl Slovenian, es Spanish (Mexico), es_ES Spanish (Spain), sw Swahili, sv Swedish, ta Tamil, th Thai, tr Turkish, uk Ukrainian, vi Vietnamese, xxxxx Custom.

Example:

{ "field": "language", "op": "is", "value": "fr_CA" }

Notes:

• value is a single string and is required for is and not. Arrays are rejected. To match several languages, use a group with "match": "any".

gmonkey — VIP status

Availability: Generally available Whether the contact is marked as a VIP.

Example:

{ "field": "gmonkey", "op": "member" }

rating — Contact rating

Availability: Generally available The contact’s star rating, from 1 to 5.

Example:

{ "field": "rating", "op": "greater", "value": 3 }

Notes:

• value is required and must be a single integer from 1 to 5, sent as a number or a numeric string.

timestamp_opt, info_changed — Subscription date and Info changed

Availability: Generally available

Both fields take the same ops and values. Dates are evaluated in the account’s timezone.

Example:

{ "field": "timestamp_opt", "op": "between", "value": ["2026-01-01", "2026-03-31"] }

{ "field": "info_changed", "op": "campaign_greater", "value": "last" }

Notes:

• value is required for every op.
• Use plain YYYY-MM-DD dates. A date-time is accepted, but its offset is ignored. is, not, greater and less use only the first value.
• date_within and date_notwithin take one whole number of days. Tokens like 7days are rejected.
• campaign_* ops take the web_id (an integer) of a sent campaign from GET /3.0/campaigns, or "last" for the audience’s most recently sent campaign. Check that the campaign exists and has been sent: a bad campaign value may not be rejected when you save, but the segment will fail when it is counted or used.

metadata_created — Contact created date

Availability: Generally available When the contact record was created in the audience, across all channels.

Example:

{ "field": "metadata_created", "op": "date_within", "value": "7" }

Notes:

• value is required for every op. Dates are YYYY-MM-DD or an ISO date-time with an offset.
• Always send two dates for between. A single value is read as “within N days”.
• date_within and date_notwithin take a whole number of days. 1month and similar tokens fail.
• campaign_* values work as they do for timestamp_opt.

original_signup_source, source — Signup source

Availability: Generally available How the contact originally joined the audience. value is the source type. The optional extra narrows the match to one specific source of that type, such as a particular import.

Source type ids:

Connected apps can also appear as sources, identified by large integer ids.

Example:

{ "field": "original_signup_source", "op": "source_is", "value": "7" }

{ "field": "original_signup_source", "op": "source_not", "value": "4", "extra": "987654" }

Notes:

• value is required. Send it as a numeric string, for example "10".
• extra is optional. Omit it, or send "any", to match any source of that type. Otherwise send the id of one specific source, for example an import id for type 4 or a landing page id for type 10. Beta: the specific-source id takes Mailchimp’s internal id, which other API endpoints don’t return. To find it, build an advanced segment in Mailchimp that uses the source, read it with GET /3.0/segments/{segment_id}, and copy the value. The format may change. With extra, source_is means “this exact source” and source_not means “not this exact source”.

static_segment — Tags

Availability: Generally available Whether the contact has particular tags. Values are tag ids: the integer id of a tag from GET /3.0/lists/{list_id}/tag-search or of a static segment from GET /3.0/lists/{list_id}/segments.

Example:

{ "field": "static_segment", "op": "static_is", "value": 8662415 }

{ "field": "static_segment", "op": "is_every", "value": [8662415, 8661935] }

Notes:

• value is required. Ids are integers, sent as numbers or numeric strings.
• static_is and static_not take exactly one id. An array is rejected; use is, is_every, not or not_every for several tags.

interests-<N> — Groups

Availability: Beta. Takes Mailchimp’s internal id, which other API endpoints don’t return. To find it, build an advanced segment in Mailchimp that uses the group, read it with GET /3.0/segments/{segment_id}, and copy the value. The format may change. Whether the contact belongs to particular groups (interests). N is the internal id of the group category, and the values are the internal ids of the groups in it. Copy both from a segment built in Mailchimp.

Example:

{ "field": "interests-1234", "op": "interestcontains", "value": ["44401", "44405"] }

Notes:

• value is required and must not be empty.
• Matching uses only the group ids in value. Keep the field and the values from the same category, as Mailchimp writes them.

list_email_status — Email subscription status

Availability: Generally available The contact’s email subscription status.

Example:

{ "field": "list_email_status", "op": "is", "value": ["Y", "T"] }

Notes:

• value is required. Codes are case-insensitive. Other values, such as "subscribed", are rejected.
• This condition is combined with the segment’s top-level contact scope. It can narrow that scope, but it can’t add back contacts the scope excludes.

marketing_preference — Marketing permissions

Availability: Beta. Takes Mailchimp’s internal id, which other API endpoints don’t return. To find it, build an advanced segment in Mailchimp that uses the marketing permission, read it with GET /3.0/segments/{segment_id}, and copy the value. The format may change. Whether the contact has granted a marketing permission (GDPR). Relevant only to audiences with GDPR fields enabled.

Example:

{ "field": "marketing_preference", "op": "is", "value": "301" }

Notes:

• value is required and must be a single numeric id, not the permission’s label.

age_gating — Age gating

Availability: Generally available The contact’s SMS age-verification outcome. Relevant only to audiences with SMS marketing.

Values: "true" means verified, "false" means excluded, and "unknown" means no record.

Example:

{ "field": "age_gating", "op": "is", "value": ["true"] }

{ "field": "age_gating", "op": "not_any" }

Notes:

• value is required for is and not. Always send an array of strings, not JSON booleans. A bare "unknown" string, not in an array, matches no one.
• "unknown" may be combined with "true" or "false": {"op": "is", "value": ["true", "unknown"]} matches contacts who are verified or have no record, and not with the same values matches everyone else.

ipgeo — Predicted location

Availability: Generally available The contact’s predicted location, estimated from data such as IP address. This is the only condition in this family that uses location.

Example:

{ "field": "ipgeo", "op": "ipgeoin", "value": "50",
  "location": { "city": "Atlanta", "region": "GA", "country_code": "US", "lat": 33.749, "lng": -84.388 } }

{ "field": "ipgeo", "op": "ipgeocountry", "value": "CA" }

Notes:

• The radius is a number of miles. The Mailchimp app offers 25, 50, 75, 100, 150 and 200, but any positive number works.
• ipgeoinzip doesn’t look up the ZIP code. Send the ZIP code’s latitude and longitude in location.lat and location.lng.
• ipgeocity and ipgeonotcity match the city name in location.city only. They are not limited by region or country.
• location.region and location.country_code are stored with the segment, but they don’t affect matching.
• The negative ops ipgeonotcountry, ipgeonotstate, ipgeonotcity and ipgeonotzip exclude contacts whose location is unknown. To include them, add an ipgeounknown condition in a group with "match": "any".

Email, SMS and WhatsApp engagement and status

These conditions select contacts by what they did with your email, SMS and WhatsApp messages (sends, opens, clicks, replies, bounces, keywords) and by their subscription status, subscription date and phone country on each channel.

Shared filters used by the activity conditions (email_campaign_activity, sms_campaign_activity, whatsapp_campaign_interaction) are described once, in Shared activity filters, at the end of this section.

email_campaign_activity — Email campaign interaction

Availability: Generally available

Selects contacts who did, or did not, receive, open, click, reply to, or bounce from your email campaigns. Filters narrow the match by campaign, time, link, click type, open type and number of events.

With a positive op (sent, open, click, reply, bounce), a contact matches when one activity record satisfies all the filters together. With a no_* op, a contact matches when no activity record satisfies all the filters together. That includes contacts with no activity at all.

Filters (filters is required and must contain at least one filter):

campaign filter

click_url filter

open_type filter (Apple Mail Privacy Protection)

Example:

Opened campaign 17795293 in the last month:

{ "field": "email_campaign_activity", "op": "open",
  "filters": [
    { "field": "campaign", "op": "is", "value": 17795293 },
    { "field": "timeframe", "op": "date_within", "value": "1month" }
  ] }

Human clicks on a link containing “/sale” in any of the last 10 campaigns, more than twice:

{ "field": "email_campaign_activity", "op": "click",
  "filters": [
    { "field": "campaign", "op": "anylast10" },
    { "field": "click_url", "op": "contains", "value": "/sale" },
    { "field": "click_type", "op": "is", "value": "contact_clicks" },
    { "field": "number_events", "op": "greater", "value": 2 }
  ] }

Notes:

• Campaign ids are the campaign’s web_id from GET /3.0/campaigns (an integer), not its id. A non-numeric value is rejected.
• Send one web_id per campaign filter. To match several specific campaigns, use a group with "match": "any".
• “Most recently sent” campaigns for anylastN / alllastN are the list’s sent, non-deleted campaigns that delivered at least one email, newest send time first. A/B test variants are expanded automatically.
• Op spellings are no_sent, no_open, no_click, no_reply. The SMS spellings (nosent, nodelivered) are rejected here.
• value, value_op and extra are not used on this condition.
• click_url: every op except any needs a non-empty string. greater and less are rejected.
• open_type is or not requires a campaign filter. If you combine open_type is with campaign any, the campaign filter is treated as anylast50. With an “all” campaign op (alllastN) every campaign must satisfy the open type; with any other campaign op, at least one must.
• open_type is / not cannot be combined with number_events is, greater or less (at_least_once is allowed).
• A filter that belongs to another channel (for example sms_campaign) is not valid here.

email_marketing_engagement — Email engagement

Availability: Generally available

Selects contacts by how often they engage with your email, based on Mailchimp’s email activity score, or by being newly opted in.

Example:

{ "field": "email_marketing_engagement", "op": "is", "value": "high" }

Notes:

• value is a single lowercase string; "HIGH" is rejected. An array is rejected; to match several levels use a group with "match": "any".
• filters, value_op and extra are not used.

sms_campaign_activity — SMS interaction

Availability: Requires SMS marketing on the audience

Selects contacts who were, or were not, sent or delivered SMS messages from your SMS campaigns or Customer Journeys, who clicked an SMS tracking link, or who texted a keyword.

With a positive op, a contact matches when one message or click satisfies all the filters together. With a negated op (nosent, nodelivered, no_click), a contact matches when no record satisfies all the filters together, including contacts with no SMS activity.

Filters (filters is required and must contain at least one filter):

Example:

Human clicks in one SMS campaign in the last 30 days:

{ "field": "sms_campaign_activity", "op": "click",
  "filters": [
    { "field": "sms_campaign", "op": "is", "value": "5e143a22-0aaf-41b1-b0b9-dac4ffa74a68" },
    { "field": "timeframe", "op": "date_within_days", "value": 30 },
    { "field": "sms_click_type", "op": "is", "value": "contact_clicks" }
  ] }

Texted the keyword “JOIN”:

{ "field": "sms_campaign_activity", "op": "used_keyword", "value": "JOIN",
  "filters": [ { "field": "sms_campaign", "op": "any" } ] }

Notes:

• Beta (sms_campaign ids): Takes Mailchimp’s internal id, which other API endpoints don’t return. To find it, build an advanced segment in Mailchimp that uses the SMS campaign, read it with GET /3.0/segments/{segment_id}, and copy the value. The format may change.
• Op spellings: nosent and nodelivered have no underscore; no_click has one. The email spelling no_sent is rejected.
• There are no open, reply or bounce ops for SMS. For bounces, use sms_bounce_reason.
• value is used only by used_keyword (a single string). value_op and extra are not used.
• Use only the filters listed above. The email filters campaign, click_url and click_type are not valid here.
• On some accounts sent, delivered and click also count WhatsApp messages. To target WhatsApp specifically, use whatsapp_campaign_interaction.

sms_bounce_reason — SMS bounce reason

Availability: Requires SMS marketing on the audience

Selects contacts with at least one SMS campaign or Customer Journey message that bounced, optionally with a specific error code. The error code, campaign and time filters all apply to the same message.

Filters (optional):

Example:

Deactivated or blocklisted number, in the last 30 days:

{ "field": "sms_bounce_reason", "op": "is", "value": ["5301", "5302"],
  "filters": [ { "field": "timeframe", "op": "date_within", "value": 30 } ] }

Notes:

• Codes are not checked against the list above; an unknown code is accepted and matches nobody.
• Every timeframe op except any needs a value. between takes [start, end], inclusive.
• campaign_is / campaign_greater / campaign_less compare with the send date of an email campaign on the same audience (web_id), or of the audience’s most recently sent email campaign ("last").
• Only sms_campaign and timeframe filters are accepted. Any other filter is rejected with Unsupported operation: <field>.

sms_contact_status — SMS subscription status

Availability: Requires SMS marketing on the audience

Selects contacts by their SMS marketing subscription status.

Example:

{ "field": "sms_contact_status", "op": "not", "value": ["N", "NON"] }

Notes:

• The op is status_is, not is.
• Codes are case-insensitive. P (pending) and any other code are rejected. An empty array is rejected.
• filters, value_op and extra are not used.

sms_timestamp_opt — SMS subscription date

Availability: Requires SMS marketing on the audience

Selects contacts by the date their SMS channel was added.

Example:

{ "field": "sms_timestamp_opt", "op": "between", "value": ["2025-02-01", "2025-02-28"] }

{ "field": "sms_timestamp_opt", "op": "date_within", "value": 30 }

Notes:

• Dates are YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS±HH:MM.
• date_within takes a number of days. "1month" and similar strings are rejected.
• "last" means the audience’s most recently sent email campaign. A campaign without a send date is rejected.
• To select dates outside a range, use a group with "match": "any" that holds a less condition on the first day and a greater condition on the last day. Contacts without an SMS subscription date match neither.
• filters, value_op and extra are not used.

sms_country_code — Mobile phone country

Availability: Requires SMS marketing on the audience

Selects contacts by the country of their SMS phone number. On some accounts it also matches the country of the contact’s WhatsApp number: then in matches if either number is in one of the countries, and not_in matches only if neither number is.

Example:

{ "field": "sms_country_code", "op": "in", "value": ["US", "CA"] }

Notes:

• Send country codes in uppercase.
• Codes are not checked against the countries Mailchimp SMS supports; an unsupported country matches nobody.
• The ops are in / not_in, not is / not.
• filters, value_op and extra are not used.

whatsapp_campaign_interaction — WhatsApp interaction

Availability: Requires WhatsApp marketing on the audience

Selects contacts who were, or were not, sent, read, or clicked WhatsApp messages from your campaigns or Customer Journeys. Filters combine the same way as for sms_campaign_activity.

Filters (filters is required and must contain at least one filter):

Example:

{ "field": "whatsapp_campaign_interaction", "op": "opened",
  "filters": [
    { "field": "whatsapp_campaign", "op": "is", "value": "8c1f2b9e-3d4a-4b5c-9e6f-1a2b3c4d5e6f" },
    { "field": "timeframe", "op": "date_within_days", "value": 14 }
  ] }

Notes:

• Beta (whatsapp_campaign ids): Takes Mailchimp’s internal id, which other API endpoints don’t return. To find it, build an advanced segment in Mailchimp that uses the WhatsApp campaign, read it with GET /3.0/segments/{segment_id}, and copy the value. The format may change.
• Op spellings: nosent and not_opened (not no_sent / no_open).
• There are no delivered or keyword ops for WhatsApp.
• value, value_op and extra are not used.

whatsapp_contact_status — WhatsApp subscription status

Availability: Requires WhatsApp marketing on the audience

Selects contacts by their WhatsApp marketing subscription status.

Example:

{ "field": "whatsapp_contact_status", "op": "is", "value": ["SUBSCRIBED"] }

Notes:

• Values differ from SMS: use SUBSCRIBED / UNSUBSCRIBED, not Y / N, and the op is is, not status_is. Other values are accepted but match nobody.
• Send values in uppercase.
• not also matches contacts with no WhatsApp channel.
• filters, value_op and extra are not used.

whatsapp_timestamp_opt — WhatsApp subscription date

Availability: Requires WhatsApp marketing on the audience

Selects contacts by the date their WhatsApp channel was added.

Example:

{ "field": "whatsapp_timestamp_opt", "op": "less", "value": "2025-06-01" }

Notes:

• Dates are YYYY-MM-DD. Every op except any needs a non-empty value.
• filters, value_op and extra are not used.

Shared activity filters

timeframe

Used by email_campaign_activity, sms_campaign_activity and whatsapp_campaign_interaction. (sms_bounce_reason has its own timeframe op list, above.)

Dates are YYYY-MM-DD, optionally followed by THH:MM[:SS] and a Z or ±HH:MM offset.

number_events

Used by email_campaign_activity (with sent, open, click), sms_campaign_activity (with sent, click) and whatsapp_campaign_interaction (with sent, click). Counts the distinct activity records that match the condition’s other filters.

At most one number_events filter per condition.

Click type filters

click_type (email), sms_click_type (SMS) and whatsapp_click_type (WhatsApp) take op is and one value:

Values must be lowercase as listed. With no_click, all_clicks means “has not clicked at all”. An empty value is treated as contact_clicks for click_type and sms_click_type; whatsapp_click_type requires a value.

E-commerce conditions

E-commerce conditions select contacts by what they did in a connected store: orders and what was in them, lifetime spend and order counts, storefront activity (page views, searches, product and collection views, carts, checkouts), reviews, back-in-stock requests, and predicted churn risk. Unless a section says otherwise, they need a connected e-commerce store. On an audience with no store data, a condition still saves; positive ops match nobody and negative ops match everybody.

Shared values and filters

These rules apply to every condition in this section.

Identifier formats

Text ops. Filters on products, variants, categories, collections, page URLs and search text use the same ops:

Money. Send amounts as a decimal JSON number or numeric string (100, "49.99"), with no currency symbol or thousands separator. Amounts must be zero or greater.

any filters. Every filter accepts "op": "any" with no value, meaning “no restriction”. Leaving the filter out does the same thing and is preferred.

How filters combine. On an activity condition (purchased, viewed, added to cart, and so on), the positive op matches contacts with at least one order or event that meets all the filters at once. The negative op (no_purchased, no_viewed, not_submitted, requested_not, …) matches contacts with no such order or event, including contacts who have no orders or events at all.

ecomm_timeframe filter

Restricts an order or event by when it happened. Dates are evaluated in the account’s timezone. Leave extra out; it is ignored.

• Dates are YYYY-MM-DD (a time and offset, YYYY-MM-DDTHH:MM:SS+00:00, is also accepted).
• On ecomm, total_spent, spent_avg and orders_count, date_within / date_notwithin also accept "7days", "1month" and "3months" (calendar months).
• date_within_days, date_within_months, blank and blank_not are not supported here.
• A campaign_* value that doesn’t match a sent campaign in the audience is rejected with HTTP 400.

number_events filter

Counts how many matching orders the contact has. Allowed only under ecomm with purchased; the store event conditions below don’t accept it. At most one per condition.

ecomm — Purchase activity

Availability: Requires a connected e-commerce store. Contacts who have, or have not, placed an order that meets every filter. With no filters, purchased means “has placed any order”.

Filters

Example:

{ "field": "ecomm", "op": "purchased",
  "filters": [
    { "field": "ecomm_timeframe", "op": "date_within", "value": "30" },
    { "field": "ecomm_product", "op": "is", "value": ["Blue T-Shirt", "Red T-Shirt"] },
    { "field": "number_events", "op": "greater", "value": 2 }
  ] }

{ "field": "ecomm", "op": "no_purchased",
  "filters": [
    { "field": "ecomm_campaign", "op": "is", "value": 1234567 },
    { "field": "ecomm_timeframe", "op": "between", "value": ["2026-01-01", "2026-03-31"] }
  ] }

Notes:

• The activity goes in op, not value. {"field": "ecomm", "op": "is", "value": "purchased"} is rejected.
• With no_purchased, text filters support only is, not, contains and notcontain, and ecomm_order_total supports only is and not. Don’t combine no_purchased with starts / ends or with order total greater / less.
• With no_purchased and a single ecomm_campaign filter, orders with no attributed campaign count as “not from that campaign”.
• ecomm_price, ecomm_quantity, ecomm_page_url, ecomm_search and review filters aren’t accepted here.

total_spent — Amount spent in total

Availability: Requires a connected e-commerce store. Scoping filters are Beta (see below). Contacts by the sum of their order totals. Without scoping filters this is the contact’s lifetime total.

Two shapes are accepted.

Simple shape: the comparison is on the condition.

Filtered shape: op is is or not (not excludes the contacts the filters describe), with no value. The comparison goes in a filter.

Filters (filtered shape only)

Example:

{ "field": "total_spent", "op": "greater", "value": "250" }

{ "field": "total_spent", "op": "is",
  "filters": [
    { "field": "ecomm_total_spent_amount", "op": "greater", "value": "100.00" },
    { "field": "ecomm_timeframe", "op": "date_within", "value": "90" }
  ] }

Notes:

• Scoping filters (ecomm_timeframe, ecomm_store, ecomm_collection) aren’t available on every account yet. Where they aren’t available, the segment saves, but requests for its count or members return an error.
• With scoping filters, is and not compare to the cent.
• Other filters (for example ecomm_product) are ignored. Don’t send them.
• "$250" is rejected; send "250".

spent_avg — Average amount spent per order

Availability: Requires a connected e-commerce store. Scoping filters are Beta. Contacts by their average order value. Same two shapes as total_spent.

Filtered shape: op is / not, no value.

Filters (filtered shape only)

Example:

{ "field": "spent_avg", "op": "less", "value": 40 }

{ "field": "spent_avg", "op": "not",
  "filters": [
    { "field": "ecomm_avg_spent", "op": "greater", "value": "75" },
    { "field": "ecomm_timeframe", "op": "date_within", "value": "180" }
  ] }

Notes:

• To match zero, send 0 (not 0.00).
• The scoping-filter rollout note on total_spent applies here too.
• Only greater, less, is and not are accepted; between is rejected.

orders_count — Total number of orders

Availability: Requires a connected e-commerce store. Scoping filters are Beta. Contacts by how many orders they’ve placed. Same two shapes as total_spent.

Filtered shape: op is / not, no value.

Filters (filtered shape only)

Example:

{ "field": "orders_count", "op": "greater", "value": 3 }

{ "field": "orders_count", "op": "is",
  "filters": [
    { "field": "ecomm_order_count", "op": "is", "value": 1 },
    { "field": "ecomm_timeframe", "op": "greater", "value": "2026-06-30" }
  ] }

Notes:

• Counts must be whole numbers: 2.5 and 5.0 are rejected.
• ecomm_collection isn’t supported on a count of orders and is rejected.
• The scoping-filter rollout note on total_spent applies here too.

ecomm_page_viewed — Page viewed

Availability: Requires a connected e-commerce store. Contacts who did, or didn’t, view a storefront page that meets every filter.

Filters

Example:

{ "field": "ecomm_page_viewed", "op": "page_viewed",
  "filters": [
    { "field": "ecomm_page_url", "op": "contains", "value": "/collections/sale" },
    { "field": "ecomm_timeframe", "op": "date_within", "value": "14" }
  ] }

Notes:

• The op is page_viewed, not viewed.

ecomm_product_viewed — Product viewed

Availability: Requires a connected e-commerce store. Contacts who did, or didn’t, view a product that meets every filter.

Filters

Example:

{ "field": "ecomm_product_viewed", "op": "viewed",
  "filters": [
    { "field": "ecomm_product", "op": "is", "value": "Trail Runner 2" },
    { "field": "ecomm_timeframe", "op": "date_within", "value": "30" }
  ] }

Notes:

• There are no price, quantity or total filters on this condition.

ecomm_collection_viewed — Collection viewed

Availability: Requires a connected e-commerce store. Contacts who did, or didn’t, view a collection page that meets every filter.

Filters

Example:

{ "field": "ecomm_collection_viewed", "op": "viewed",
  "filters": [ { "field": "ecomm_collection", "op": "contains", "value": "Summer" } ] }

Notes:

• Product, variant and category filters aren’t accepted here.

ecomm_search_submitted — Search submitted

Availability: Requires a connected e-commerce store. Contacts who did, or didn’t, run a storefront search that meets every filter.

Filters