Class: CustomerSegmentsService

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:46

Extends

• BaseService

Constructors

Constructor

new CustomerSegmentsService(client): CustomerSegmentsService

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/base.ts:12

Parameters

client

TanqoryClient

Returns

CustomerSegmentsService

Inherited from

BaseService.constructor

Properties

client

protected client: TanqoryClient

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/base.ts:10

Inherited from

BaseService.client

Methods

addCustomersToSegment()

addCustomersToSegment(storeId, segmentId, data): Promise<{ addedCount?: number; newCustomerCount: number; removedCount?: number; segmentId: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:269

Add customers to a static segment

Parameters

storeId

string

segmentId

string

data

customerIds

string[]

Returns

Promise<{ addedCount?: number; newCustomerCount: number; removedCount?: number; segmentId: string; success: boolean; }>

---

archiveSegment()

archiveSegment(storeId, segmentId): Promise<{ segmentId: string; status: "active" | "paused" | "archived" | "calculating"; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:307

Archive a segment

Parameters

storeId

string

segmentId

string

Returns

Promise<{ segmentId: string; status: "active" | "paused" | "archived" | "calculating"; success: boolean; }>

---

buildQuery()

protected buildQuery(options?): Record<string, any>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/base.ts:26

Build query parameters

Parameters

options?

ListOptions

Returns

Record<string, any>

Inherited from

BaseService.buildQuery

---

bulkAddTagToSegment()

bulkAddTagToSegment(storeId, segmentId, data): Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:361

Add tags to all customers in a segment

Parameters

storeId

string

segmentId

string

data

tags

string[]

Returns

Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

---

bulkApplyDiscountToSegment()

bulkApplyDiscountToSegment(storeId, segmentId, data): Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:391

Apply discount to all customers in a segment

Parameters

storeId

string

segmentId

string

data

discountId

string

Returns

Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

---

bulkEmailSegment()

bulkEmailSegment(storeId, segmentId, data): Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:331

Send bulk email to segment customers

Parameters

storeId

string

segmentId

string

data

scheduledAt?

Date

subject?

string

templateId

string

Returns

Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

---

bulkRemoveTagFromSegment()

bulkRemoveTagFromSegment(storeId, segmentId, data): Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:376

Remove tags from all customers in a segment

Parameters

storeId

string

segmentId

string

data

tags

string[]

Returns

Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

---

bulkSmsSegment()

bulkSmsSegment(storeId, segmentId, data): Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:346

Send bulk SMS to segment customers

Parameters

storeId

string

segmentId

string

data

message?

string

scheduledAt?

Date

templateId

string

Returns

Promise<{ affectedCount: number; jobId?: string; message: string; success: boolean; }>

---

createSegment()

createSegment(storeId, data): Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:77

Create a customer segment (static with customer list or dynamic with filters)

Parameters

storeId

string

data

autoRefresh

boolean

category?

"value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"

color?

string

customerIds?

string[]

description?

string

filterGroups?

FilterGroup

filters?

object[]

icon?

string

name

string

priority?

number

query?

string

refreshIntervalHrs?

number

type

"static" | "dynamic"

Returns

Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

---

deleteSegment()

deleteSegment(storeId, segmentId): Promise<{ deleted: true; id: string; object: "customer_segment"; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:107

Delete a customer segment (does not affect customers, only the definition)

Parameters

storeId

string

segmentId

string

Returns

Promise<{ deleted: true; id: string; object: "customer_segment"; }>

---

duplicateSegment()

duplicateSegment(storeId, segmentId, name?): Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:174

Duplicate a segment with an optional new name

Parameters

storeId

string

segmentId

string

name?

string

Returns

Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

---

evaluateSegment()

evaluateSegment(storeId, data): Promise<{ count: number; customers?: object[]; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:137

Validate segment filters and return matching customer count

Parameters

storeId

string

data

filterGroups?

FilterGroup

filters?

object[]

limit

number

page?

number

pageSize?

number

query?

string

Returns

Promise<{ count: number; customers?: object[]; }>

---

exportSegment()

exportSegment(storeId, segmentId, options?): Promise<{ downloadUrl: string; expiresAt: Date; fileName: string; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:190

Export segment to CSV (returns job ID for async completion)

Parameters

storeId

string

segmentId

string

options?

customersSelected?

"all" | "matching"

fileFormat?

"csv_excel" | "csv_plain"

includeCustomerTags?

boolean

includeMetafields?

boolean

Returns

Promise<{ downloadUrl: string; expiresAt: Date; fileName: string; }>

---

generateIdempotencyKey()

protected generateIdempotencyKey(prefix): string

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/base.ts:19

Generate idempotency key

Parameters

prefix

string

Returns

string

Inherited from

BaseService.generateIdempotencyKey

---

generateSegmentWithAI()

generateSegmentWithAI(storeId, data): Promise<{ confidence: number; description: string; explanation: string; filterGroups?: FilterGroup; filters: object[]; query: string; suggestedName: string; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:422

Generate segment using AI (supports Thai and English)

Parameters

storeId

string

data

context?

{ currentQuery?: string; }

context.currentQuery?

string

language

"en" | "th"

prompt

string

Returns

Promise<{ confidence: number; description: string; explanation: string; filterGroups?: FilterGroup; filters: object[]; query: string; suggestedName: string; }>

---

getExportMimeType()

protected getExportMimeType(format): string

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/base.ts:45

Get MIME type for export format

Parameters

format

string

Returns

string

Inherited from

BaseService.getExportMimeType

---

getSegmentAISuggestions()

getSegmentAISuggestions(storeId, segmentId): Promise<{ suggestions: object[]; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:436

Get AI suggestions to improve a segment

Parameters

storeId

string

segmentId

string

Returns

Promise<{ suggestions: object[]; }>

---

getSegmentAnalytics()

getSegmentAnalytics(storeId, segmentId, params?): Promise<{ addedToday: number; averageOrdersPerMember: number; averageOrderValue: number; currentCount: number; netChange: number; percentageOfTotal: number; removedToday: number; segmentId: string; topMembers?: object[]; totalSpent: number; trend: object[]; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:215

Get segment analytics (member trends, metrics, top members)

Parameters

storeId

string

segmentId

string

params?

endDate?

string

period?

"day" | "week" | "month"

startDate?

string

Returns

Promise<{ addedToday: number; averageOrdersPerMember: number; averageOrderValue: number; currentCount: number; netChange: number; percentageOfTotal: number; removedToday: number; segmentId: string; topMembers?: object[]; totalSpent: number; trend: object[]; }>

---

getSegmentCustomers()

getSegmentCustomers(storeId, segmentId, params?): Promise<{ data: object[]; limit: number; page: number; total: number; total_pages: number; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:151

Get customers in a segment with pagination

Parameters

storeId

string

segmentId

string

params?

limit?

number

page?

number

sortBy?

string

sortOrder?

"asc" | "desc"

Returns

Promise<{ data: object[]; limit: number; page: number; total: number; total_pages: number; }>

---

getSegmentMembershipChanges()

getSegmentMembershipChanges(storeId, segmentId, params?): Promise<{ data: object[]; limit: number; page: number; total: number; total_pages: number; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:254

Get recent additions and removals from a segment

Parameters

storeId

string

segmentId

string

params?

action?

"all" | "added" | "removed"

endDate?

string

limit?

number

page?

number

startDate?

string

Returns

Promise<{ data: object[]; limit: number; page: number; total: number; total_pages: number; }>

---

getSegmentTemplates()

getSegmentTemplates(storeId): Promise<{ templates: object[]; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:115

Get pre-configured segment templates for common use cases

Parameters

storeId

string

Returns

Promise<{ templates: object[]; }>

---

getSegmentTopMembers()

getSegmentTopMembers(storeId, segmentId, limit?): Promise<{ members: object[]; total: number; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:241

Get highest-value customers in a segment

Parameters

storeId

string

segmentId

string

limit?

number = 10

Returns

Promise<{ members: object[]; total: number; }>

---

getSegmentTrend()

getSegmentTrend(storeId, segmentId, params?): Promise<{ trend: object[]; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:228

Get segment trend (historical membership data over time)

Parameters

storeId

string

segmentId

string

params?

endDate?

string

period?

"day" | "week" | "month"

startDate?

string

Returns

Promise<{ trend: object[]; }>

---

listSegments()

listSegments(storeId, params?): Promise<{ data: object[]; limit: number; page: number; total: number; total_pages: number; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:52

List customer segments (static and dynamic) with pagination

Parameters

storeId

string

params?

category?

"value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"

limit?

number

page?

number

search?

string

sortBy?

string

sortOrder?

"asc" | "desc"

status?

"active" | "paused" | "archived" | "calculating"

Returns

Promise<{ data: object[]; limit: number; page: number; total: number; total_pages: number; }>

---

previewSegment()

previewSegment(storeId, data): Promise<{ count: number; customers: object[]; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:123

Preview segment results without creating the segment

Parameters

storeId

string

data

filterGroups?

FilterGroup

filters?

object[]

limit

number

page?

number

pageSize?

number

query?

string

Returns

Promise<{ count: number; customers: object[]; }>

---

refreshSegment()

refreshSegment(storeId, segmentId): Promise<{ calculationTimeMs: number; customerCount: number; lastCalculatedAt: Date; segmentId: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:297

Recalculate segment membership for a dynamic segment

Parameters

storeId

string

segmentId

string

Returns

Promise<{ calculationTimeMs: number; customerCount: number; lastCalculatedAt: Date; segmentId: string; success: boolean; }>

---

removeCustomersFromSegment()

removeCustomersFromSegment(storeId, segmentId, data): Promise<{ addedCount?: number; newCustomerCount: number; removedCount?: number; segmentId: string; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:284

Remove customers from a static segment

Parameters

storeId

string

segmentId

string

data

customerIds

string[]

Returns

Promise<{ addedCount?: number; newCustomerCount: number; removedCount?: number; segmentId: string; success: boolean; }>

---

restoreSegment()

restoreSegment(storeId, segmentId): Promise<{ segmentId: string; status: "active" | "paused" | "archived" | "calculating"; success: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:317

Restore an archived segment

Parameters

storeId

string

segmentId

string

Returns

Promise<{ segmentId: string; status: "active" | "paused" | "archived" | "calculating"; success: boolean; }>

---

retrieveSegment()

retrieveSegment(storeId, segmentId): Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:66

Get a single customer segment with filters, count, and metadata

Parameters

storeId

string

segmentId

string

Returns

Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

---

updateSegment()

updateSegment(storeId, segmentId, data): Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:92

Update a customer segment (name, description, filters)

Parameters

storeId

string

segmentId

string

data

autoRefresh?

boolean

category?

"value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"

color?

string

customerIds?

string[]

description?

string

filterGroups?

FilterGroup

filters?

object[]

icon?

string

name?

string

priority?

number

query?

string

refreshIntervalHrs?

number

status?

"active" | "paused" | "archived" | "calculating"

type?

"static" | "dynamic"

Returns

Promise<{ autoRefresh: boolean; category?: "value" | "custom" | "rfm" | "engagement" | "lifecycle" | "geographic" | "seasonal" | "behavioral" | "predictive"; color?: string; createdAt: Date; createdBy?: { id: string; name: string; }; customerCount: number; description?: string; filterGroups?: FilterGroup; filters?: object[]; icon?: string; id: string; lastCalculatedAt?: Date; lastRefreshAt?: Date; memberCount?: number; name: string; percentageOfTotal?: number; priority: number; query?: string; refreshIntervalHrs?: number; status: "active" | "paused" | "archived" | "calculating"; trend?: object[]; type: "static" | "dynamic"; updatedAt: Date; updatedBy?: { id: string; name: string; }; }>

---

validateSegmentQuery()

validateSegmentQuery(storeId, query): Promise<{ errors?: object[]; parsedFilters?: object[]; valid: boolean; }>

Defined in: tanqory-platform-packages/packages/api/sdk/src/services/customer-segments.ts:410

Validate segment query syntax

Parameters

storeId

string

query

string

Returns

Promise<{ errors?: object[]; parsedFilters?: object[]; valid: boolean; }>