Segments

Rule based groups of contacts of one e-shop: an AND / OR tree of conditions, evaluated live (daily) or as a snapshot (static).

Technická reference je anglicky (stejně jako strojově čitelný dokument OpenAPI). Celou skupinu pro AI agenta načtete z /api/openapi.json?tag=Segments.

Přihlášení: Authorization: Bearer pst_... nebo HTTP Basic (e-mail člena firmy a API klíč).

Operace#

List segments#

GET /api/v1/tenants/{tenant}/segments

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: list_segments

Segments with matched and mailable counts.

Filtry of the grid (routes_grid.py): ?tag= (repeatable), ?idFrom=&idTo=, ?createdFrom=&createdTo=, ?updatedFrom=&updatedTo= (calendar days), ?refresh=static|daily.

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Create a segment#

POST /api/v1/tenants/{tenant}/segments

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: create_segment

Creates a segment of one shop from a condition tree {type: group, match: all|any, rules: [...]} (rule types: get_api_reference Segmenty).

Parametry

Tělo požadavku (application/json)

Odpovědi

• 201 Created: application/json SegmentDetail

Chyby

Count the contacts of a segment definition (no save)#

POST /api/v1/tenants/{tenant}/segments/preview

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: preview_segment

Counts a condition tree without saving: matched, mailable and total contacts of the shop.

Live count for the editor: {matched, mailable, total}; the root may be empty (all contacts of the shop).

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json SegmentPreview

Chyby

Change labels of segments#

POST /api/v1/tenants/{tenant}/segments/tags

Oprávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

Tělo požadavku (application/json): Required by the server: ids.

Odpovědi

• 200 OK: application/json object

Chyby

Get a segment#

GET /api/v1/tenants/{tenant}/segments/{segment}

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: get_segment

One segment with its definition tree.

Parametry

Odpovědi

• 200 OK: application/json SegmentDetail

Chyby

Update a segment#

PATCH /api/v1/tenants/{tenant}/segments/{segment}

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: update_segment

Changes a segment (the shop never changes).

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json SegmentDetail

Chyby

Delete a segment no campaign, segment or automation names#

DELETE /api/v1/tenants/{tenant}/segments/{segment}

Oprávnění: modul contacts, úroveň full; klíč s přístupem full

SE's Smazat segment: 204; 409 'conflict' with the message campaign, segment or automation while something names it.

Parametry

Odpovědi

• 204 No content

Chyby

List the members of a segment#

GET /api/v1/tenants/{tenant}/segments/{segment}/members

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

SE's detail of a segment (SG-07): its members as the contacts grid (?q=, ?state=, ?engagement=, ?sort=, paging; rows as GET /contacts): the stored snapshot of a static segment, the live definition otherwise.

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Recompute a segment now#

POST /api/v1/tenants/{tenant}/segments/{segment}/recompute

Oprávnění: modul contacts, úroveň full; klíč s přístupem full

SE's Přepočítat segment: a static segment takes a new snapshot of its members now, a daily one is live anyway (computedAt moves); the detail.

Parametry

Tělo požadavku (application/json)

object

Odpovědi

• 200 OK: application/json SegmentDetail

Chyby

Convert a segment into a manual list of its mailable contacts#

POST /api/v1/tenants/{tenant}/segments/{segment}/to-list

Oprávnění: modul contacts, úroveň full; klíč s přístupem full

SE's Převést na seznam: body {name}; 201 {listId, name, members} with a new manual list of the segment's mailable contacts now (bulk: no automation starts); 409 'conflict' / 'name' for a taken list name.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 201 Created: application/json SegmentToListResult

Chyby

Schémata#

ContactListItem#

Error#

{
  "error": {
    "code": "validation",
    "message": "email"
  }
}

GridTagsInput#

Bulk label change: add and remove, or tags = the new labels of every row.

SegmentDetail#

SegmentGroup#

A segment definition: AND (all) / OR (any) groups nested at most 8 levels, at most 50 rules. An empty root matches every contact of the shop (a saved segment needs at least one rule); an empty subgroup is an error. Errors: 400 validation "definition.<path>.<field>" (path = indices from the root).

{
  "type": "group",
  "match": "any",
  "rules": [
    {
      "type": "order_value",
      "operator": "gte",
      "amount": "2000",
      "currency": "CZK",
      "shopId": "1",
      "days": "365"
    },
    {
      "type": "group",
      "match": "all",
      "rules": [
        {
          "type": "list",
          "operator": "in",
          "listId": "101"
        },
        {
          "type": "field",
          "field": "lastOpenAt",
          "operator": "in_last_days",
          "value": "60"
        }
      ]
    }
  ]
}

SegmentInput#

SegmentPreview#

SegmentRule_campaign#

Delivered / opened / clicked a campaign (not_* also matches contacts that never got it); linkUrl narrows clicks to one link.

{
  "type": "campaign",
  "operator": "opened",
  "campaignId": "121",
  "days": null
}

SegmentRule_custom_field#

A custom field. kind must match the field type: text and textarea -> text, number -> number, date -> date, checkbox -> bool, select and radio -> choice, multi_checkbox -> multi_choice (400 definition.<path>.kind otherwise). Operators: text like the text fields, number gte/lte/eq/is_empty/is_not_empty, date like the date fields, bool is_true/is_false, choice is/is_not, multi_choice contains_any/contains_all/not_contains_any.

{
  "type": "custom_field",
  "fieldId": "62",
  "kind": "text",
  "operator": "equals",
  "value": "VIP"
}

SegmentRule_engagement#

Engagement level A (best) to E, N = new.

{
  "type": "engagement",
  "operator": "in",
  "values": [
    "A",
    "B"
  ]
}

SegmentRule_field#

A contact field compared with a value. Text operators ignore case and diacritics; date operators count calendar days of the company. Text fields: email, firstName, lastName, city, company, companyId, phone, mobile, street, postalCode, note, country. Enum fields: status (pending/subscribed/unsubscribed/bounced/complained/customer), gender (f/m), language (cs/sk), source (erp_order/signup_form/import/api/manual/shoptet/smartemailing), consentBasis (soft_opt_in_customer/double_opt_in/imported/none). Date fields: createdAt, lastOpenAt, lastClickAt, lastSentAt, statusAt, consentAt.

{
  "type": "field",
  "field": "lastOpenAt",
  "operator": "in_last_days",
  "value": "60"
}

SegmentRule_last_order#

The last completed order: within / older than N days, or before / after a date.

{
  "type": "last_order",
  "operator": "older_than_days",
  "value": "180"
}

SegmentRule_list#

Membership in a list. in / not_in = confirmed or unconfirmed member; status_is compares the exact state; added_before / added_after compare the day the contact was added; longer_than_days / shorter_than_days: in the list longer / shorter than N days.

{
  "type": "list",
  "operator": "in",
  "listId": "101"
}

SegmentRule_list_label#

Confirmed or unconfirmed member of any list with this label.

{
  "type": "list_label",
  "operator": "in",
  "label": "vip"
}

SegmentRule_opens#

Number of the contact's e-mails (campaigns and automations) with an open.

{
  "type": "opens",
  "operator": "gte",
  "value": "3",
  "days": "90"
}

SegmentRule_order_attribute#

A completed order has an item whose product code, category, brand or another item attribute (as stored on the order item) equals the value; with scope order an attribute of the order itself.

{
  "type": "order_attribute",
  "operator": "is",
  "attribute": "brand",
  "value": "Example"
}

SegmentRule_order_count#

Number of completed orders.

{
  "type": "order_count",
  "operator": "gte",
  "value": "2",
  "shopId": null,
  "currency": null,
  "days": "365"
}

SegmentRule_order_value#

Sum of completed orders with VAT in one currency (CZK and EUR are never added up).

{
  "type": "order_value",
  "operator": "gte",
  "amount": "2000",
  "currency": "CZK",
  "shopId": "1",
  "days": "365"
}

SegmentRule_product_bought#

A completed order has an item whose name contains the text or whose product code equals it (case and diacritics ignored).

{
  "type": "product_bought",
  "operator": "is",
  "value": "Espresso",
  "days": "30"
}

SegmentRule_purpose#

A valid (not withdrawn, within its validity) consent with a purpose of processing.

{
  "type": "purpose",
  "operator": "has",
  "purposeId": "51"
}

SegmentRule_segment#

Member of another segment of the same shop (never itself; chains at most 5 deep, no cycles).

{
  "type": "segment",
  "operator": "not_in",
  "segmentId": "91"
}

SegmentRule_web_attribute#

A page visit whose attribute matches: visitType = the page type, other names = the visit's own attributes; gt to lte compare numbers.

{
  "type": "web_attribute",
  "attribute": "visitType",
  "operator": "is",
  "value": "product"
}

SegmentRule_web_visit#

A page visit recorded by the shop's script or the API; any = any page.

{
  "type": "web_visit",
  "operator": "contains",
  "url": "/kava/",
  "days": "30"
}

SegmentSummary#

SegmentToListResult#

POST /segments/{id}/to-list: the new list and how many contacts it got.