Skip to content

Customers

21 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

CRM privacy settings: timeline retention in months

GET/v1/customer-settings

Returns retentionMonths (default 25). Timeline rows older than this are deleted by the daily crm-retention job; payments, ledger and audit are never touched.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customer-settings" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Change the timeline retention (1 to 120 months; audited)

PATCH/v1/customer-settings

Sets retentionMonths, an integer from 1 to 120. Needs customer:settings (owner and admin). Shortening it deletes history at the next daily purge. Writes an audit row and a customer.retention_updated event. The next daily purge applies it.

Authentication
API key (Bearer)
Permission
customer:settings
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • retentionMonthsintegerrequired
    min 1 · max 120

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PATCH "$GIEP_API_URL/v1/customer-settings" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-customer-settings-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "retentionMonths": 1
}'
// JSON object. The OpenAPI document does not list its fields.

List or search customers

GET/v1/customers

Search by email or name; newest first. Filters (all combined): hasActiveSubscription, hasOpenDispute, consentChannel + consentState (granted, withdrawn or none; the latest marketing record), ltvCurrency + ltvMin / ltvMax (minor units; captured minus succeeded refunds), lastOrderBefore / lastOrderAfter. Cursor pages: pass the X-Next-Cursor response header back as cursor (before, an ISO time, still works). Erased customers are left out. In a support session email and name are masked (j***@example.com) and a search matches the whole email only.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Query parameters

  • searchstring
    max 200 chars
  • beforestring · date-time
    pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
  • cursorstring
    max 200 chars
  • limitinteger
    min 1 · max 200
  • hasActiveSubscriptionstring
    One oftruefalse
  • hasOpenDisputestring
    One oftruefalse
  • consentChannelstring
    One ofemailsmswhatsapp
  • consentStatestring
    One ofgrantedwithdrawnnone
  • ltvCurrencystring
    pattern ^[A-Z]{3}$
  • ltvMininteger
    min 0
  • ltvMaxinteger
    min 0
  • lastOrderBeforestring · date-time
    pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
  • lastOrderAfterstring · date-time
    pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customers" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Customer profile: LTV per currency, orders, refunds, disputes, subscriptions, consent, terms accepted, facts

GET/v1/customers/{id}

LTV is captured payments minus succeeded refunds, per currency, never converted. openDisputes counts disputes still open or with evidence submitted (disputes is the total); lastSeenAt is the latest checkout session, payment, timeline row or first sighting; recentPayments are the 10 newest (brand and last 4 only); termsAccepted holds the subscription authorizations (terms version and hash, amount, interval) and the checkout consent answers. Facts are those segments evaluate. In a support session email and name are masked.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Record consent per channel and purpose (append-only; the latest record decides)

POST/v1/customers/{id}/consent

Marketing messages need a granted record newer than any withdrawal (AUT-002). Audited.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • channelstringrequired
    One ofemailsmswhatsapp
  • purposestringrequired
    One oftransactionalmarketing
  • statestringrequired
    One ofgrantedwithdrawn
  • wordingVersionstring
    max 40 chars

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/consent" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-consent-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "email",
  "purpose": "transactional",
  "state": "granted"
}'
// JSON object. The OpenAPI document does not list its fields.

Erase personal data (irreversible; confirm with the email or the id suffix)

POST/v1/customers/{id}/erase

Refused while a subscription is live or a dispute is open. Payments, refunds and the ledger keep their amounts; email, name, tags, session email and tracking and the timeline are removed. Audited. Confirm with confirmEmail (the customer email); a customer without an email is confirmed with confirmCustomerIdSuffix (the last 6 characters of the customer id).

Authentication
API key (Bearer)
Permission
customer:export
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • confirmEmailstring
    max 320 chars
  • confirmCustomerIdSuffixstring
    max 16 chars

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/erase" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-erase-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmEmail": "ana@example.com",
  "confirmCustomerIdSuffix": "string"
}'
// JSON object. The OpenAPI document does not list its fields.

Personal-data export (JSON, audited)

GET/v1/customers/{id}/export

Profile, orders, payments (no card data beyond brand and last 4), subscriptions and their authorizations and invoices (no stored payment-method token, no card expiry), checkout sessions, consent records, notes and timeline.

Authentication
API key (Bearer)
Permission
customer:export
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/export" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Notes on a customer

GET/v1/customers/{id}/notes

Merchant notes, newest first. In a support session the text is hidden: each note has body: null, hidden: true, the author and the time.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/notes" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Add a note (audited, on the timeline)

POST/v1/customers/{id}/notes

Plain text, at most 2,000 characters.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
201

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • bodystringrequired
    min 1 chars · max 2000 chars

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/notes" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-notes-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "string"
}'
// JSON object. The OpenAPI document does not list its fields.

Email the receipt of a captured payment of this customer again

POST/v1/customers/{id}/receipts/{paymentId}/resend

Only a captured payment of this customer; refused in a support session. Rate limited to 3 per payment per hour and 30 per merchant per minute (429 rate_limited). Audited, and a receipt.resent entry lands on the timeline. Needs customer:manage.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired
  • paymentIdstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/receipts/string/resend" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-resend-v1"
// JSON object. The OpenAPI document does not list its fields.

Record a support action taken from the customer drawer (audited, on the timeline)

POST/v1/customers/{id}/support-actions

The action itself (refund, card block, subscription cancel or pause, card-update link, receipt resend) is done by its own endpoint with its own permission; this adds the audit row and the customer.support_action timeline entry. The payment or subscription must belong to the customer. Needs customer:manage.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • actionstringrequired
    One ofrefundcard_blocksubscription_cancelsubscription_pausecard_update_linkreceipt_resend
  • targetTypestringrequired
    One ofpaymentsubscription
  • targetIdstring · uuidrequired
  • notestring
    max 500 chars

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/support-actions" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-support-actions-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "refund",
  "targetType": "payment",
  "targetId": "446adfd5-ed68-4907-a5a6-6bc34-787"
}'
// JSON object. The OpenAPI document does not list its fields.

Set the customer tags (lower-cased, de-duplicated; audited)

PUT/v1/customers/{id}/tags

Replaces the tag set; usable in segments (tags contains).

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • tagsarray<string>required
    max 30 items

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PUT "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/tags" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-tags-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "string"
  ]
}'
// JSON object. The OpenAPI document does not list its fields.

The customer timeline (read model over canonical events)

GET/v1/customers/{id}/timeline

Newest first; filter by event type prefix; cursor with before. Rebuilt from canonical events only; rows older than the merchant retention are purged daily. Email- and phone-shaped text is masked in a support session.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Query parameters

  • beforestring · date-time
    pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
  • typestring
    max 60 chars · pattern ^[a-z_.]+$
  • limitinteger
    min 1 · max 200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customers/eec27db1-d340-4cab-aacd-44c4-167/timeline" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Paid revenue by ad channel, last touch and first touch, with the assumptions

GET/v1/customers/attribution

Only backend-confirmed paid orders count. Sessions with UTM parameters (utm_source, utm_medium, utm_campaign) are grouped by source / medium / campaign; sessions without fall back to the click-id channel (gclid, fbc, ttclid); the rest are unattributed. Each row carries kind (utm, click_id or unattributed). Per currency.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Query parameters

  • fromany
  • toany
  • storeIdstring · uuid

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/customers/attribution" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Saved segments

GET/v1/segments

Segments that are not archived.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/segments" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Create a segment (condition tree over customer facts)

POST/v1/segments

Facts: orders, days_since_last_order, ltv.<ISO currency> (minor units), subscription_status, plan_ids, has_failed_renewal, in_trial, refunds, disputes, tags, store_ids, consent_<channel>_marketing.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
201

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • namestringrequired
    min 1 chars · max 80 chars
  • definitionone ofrequired
    4 variants (one of)

    Option 1

    • allarray<one of>required
      max 50 items
      4 variants (one of)

      Option 1

      • allarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 2

      • anyarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 3

      • notone ofrequired

      Option 4

      • factstringrequired
        min 1 chars · max 40 chars
      • opstringrequired
        One ofeqneqgtgteltlteinnincontainsexists
      • valueone of

    Option 2

    • anyarray<one of>required
      max 50 items
      4 variants (one of)

      Option 1

      • allarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 2

      • anyarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 3

      • notone ofrequired

      Option 4

      • factstringrequired
        min 1 chars · max 40 chars
      • opstringrequired
        One ofeqneqgtgteltlteinnincontainsexists
      • valueone of

    Option 3

    • notone ofrequired

    Option 4

    • factstringrequired
      min 1 chars · max 40 chars
    • opstringrequired
      One ofeqneqgtgteltlteinnincontainsexists
    • valueone of

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/segments" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-segments-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "definition": {
    "all": []
  }
}'
// JSON object. The OpenAPI document does not list its fields.

Rename or redefine a segment

PATCH/v1/segments/{id}

Changes the name or the condition tree (validated against the facts list). Audited.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • namestring
    min 1 chars · max 80 chars
  • definitionone of
    4 variants (one of)

    Option 1

    • allarray<one of>required
      max 50 items
      4 variants (one of)

      Option 1

      • allarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 2

      • anyarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 3

      • notone ofrequired

      Option 4

      • factstringrequired
        min 1 chars · max 40 chars
      • opstringrequired
        One ofeqneqgtgteltlteinnincontainsexists
      • valueone of

    Option 2

    • anyarray<one of>required
      max 50 items
      4 variants (one of)

      Option 1

      • allarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 2

      • anyarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 3

      • notone ofrequired

      Option 4

      • factstringrequired
        min 1 chars · max 40 chars
      • opstringrequired
        One ofeqneqgtgteltlteinnincontainsexists
      • valueone of

    Option 3

    • notone ofrequired

    Option 4

    • factstringrequired
      min 1 chars · max 40 chars
    • opstringrequired
      One ofeqneqgtgteltlteinnincontainsexists
    • valueone of

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PATCH "$GIEP_API_URL/v1/segments/eec27db1-d340-4cab-aacd-44c4-167" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-segments-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "definition": {
    "all": []
  }
}'
// JSON object. The OpenAPI document does not list its fields.

Archive a segment

POST/v1/segments/{id}/archive

The segment is no longer listed or usable by campaigns; its history stays. Audited.

Authentication
API key (Bearer)
Permission
customer:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/segments/eec27db1-d340-4cab-aacd-44c4-167/archive" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-archive-v1"
// JSON object. The OpenAPI document does not list its fields.

Segment members as CSV (formula-safe, audited)

GET/v1/segments/{id}/export

Requires customer:export.

Authentication
API key (Bearer)
Permission
customer:export
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a CSV file, streamed.

200 response fields

Body type: string.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/segments/eec27db1-d340-4cab-aacd-44c4-167/export" \
  -H "Authorization: Bearer $GIEP_API_KEY"
(streamed CSV, one row per line)

Members of a segment (first 100)

GET/v1/segments/{id}/members

Evaluated live; capped when the merchant has more customers than one scan reads.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/segments/eec27db1-d340-4cab-aacd-44c4-167/members" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Count and sample a segment definition without saving it

POST/v1/segments/preview

Same evaluator as saved segments and automation rules.

Authentication
API key (Bearer)
Permission
customer:read
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • definitionone ofrequired
    4 variants (one of)

    Option 1

    • allarray<one of>required
      max 50 items
      4 variants (one of)

      Option 1

      • allarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 2

      • anyarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 3

      • notone ofrequired

      Option 4

      • factstringrequired
        min 1 chars · max 40 chars
      • opstringrequired
        One ofeqneqgtgteltlteinnincontainsexists
      • valueone of

    Option 2

    • anyarray<one of>required
      max 50 items
      4 variants (one of)

      Option 1

      • allarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 2

      • anyarray<one of>required
        max 50 items
        4 variants (one of)

        Option 1

        • allarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 2

        • anyarray<one of>required
          max 50 items
          4 variants (one of)

          Option 1

          • allarray<one of>required
            max 50 items

          Option 2

          • anyarray<one of>required
            max 50 items

          Option 3

          • notone ofrequired

          Option 4

          • factstringrequired
            min 1 chars · max 40 chars
          • opstringrequired
            One ofeqneqgtgteltlteinnincontainsexists
          • valueone of

        Option 3

        • notone ofrequired

        Option 4

        • factstringrequired
          min 1 chars · max 40 chars
        • opstringrequired
          One ofeqneqgtgteltlteinnincontainsexists
        • valueone of

      Option 3

      • notone ofrequired

      Option 4

      • factstringrequired
        min 1 chars · max 40 chars
      • opstringrequired
        One ofeqneqgtgteltlteinnincontainsexists
      • valueone of

    Option 3

    • notone ofrequired

    Option 4

    • factstringrequired
      min 1 chars · max 40 chars
    • opstringrequired
      One ofeqneqgtgteltlteinnincontainsexists
    • valueone of

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/segments/preview" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-preview-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "definition": {
    "all": []
  }
}'
// JSON object. The OpenAPI document does not list its fields.
Customers · API reference · GIEP