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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
retentionMonthsintegerrequiredmin 1 · max 120
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
searchstringmax 200 charsbeforestring · date-timepattern ^(?:(?:\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))$cursorstringmax 200 charslimitintegermin 1 · max 200hasActiveSubscriptionstringOne oftruefalsehasOpenDisputestringOne oftruefalseconsentChannelstringOne ofemailsmswhatsappconsentStatestringOne ofgrantedwithdrawnnoneltvCurrencystringpattern ^[A-Z]{3}$ltvMinintegermin 0ltvMaxintegermin 0lastOrderBeforestring · date-timepattern ^(?:(?:\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-timepattern ^(?:(?:\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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/customers" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
channelstringrequiredOne ofemailsmswhatsapppurposestringrequiredOne oftransactionalmarketingstatestringrequiredOne ofgrantedwithdrawnwordingVersionstringmax 40 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
confirmEmailstringmax 320 charsconfirmCustomerIdSuffixstringmax 16 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
bodystringrequiredmin 1 chars · max 2000 chars
Responses
- 201Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 201 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
idstringrequiredpaymentIdstringrequired
Headers
Idempotency-KeystringrequiredRequired 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 409request_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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
actionstringrequiredOne ofrefundcard_blocksubscription_cancelsubscription_pausecard_update_linkreceipt_resendtargetTypestringrequiredOne ofpaymentsubscriptiontargetIdstring · uuidrequirednotestringmax 500 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-timepattern ^(?:(?:\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))$typestringmax 60 chars · pattern ^[a-z_.]+$limitintegermin 1 · max 200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
fromanytoanystoreIdstring · uuid
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/segments" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
namestringrequiredmin 1 chars · max 80 charsdefinitionone ofrequired4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Responses
- 201Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 201 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
namestringmin 1 chars · max 80 charsdefinitionone of4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a CSV file, streamed.
200 response fields
Body type: string.
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){
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}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-KeystringrequiredRequired 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 409request_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 ofrequired4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 2
anyarray<one of>requiredmax 50 items4 variants (one of)
Option 1
allarray<one of>requiredmax 50 items
Option 2
anyarray<one of>requiredmax 50 items
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Option 3
notone ofrequired
Option 4
factstringrequiredmin 1 chars · max 40 charsopstringrequiredOne ofeqneqgtgteltlteinnincontainsexistsvalueone of
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
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.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}