Segment API¶
These endpoints will allow you to retrieve information and manage the segments used in your instance of Open Loyalty.
Get segments list¶
To retrieve a paginated list of segments, you need to call the /api/<storeCode>/segment
endpoint with the GET
method.
Definition¶
GET /api/<storeCode>/segment
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store to get the segments of. |
page | query | (optional) Start from page, by default 1 |
perPage | query | (optional) Number of items to display per page, by default = 10 |
sort | query | (optional) Sort by column name, by default = name |
direction | query | (optional) Direction of sorting [ASC, DESC], by default = ASC |
Example¶
curl http://localhost:8181/api/DEFAULT/segment \
-X "GET" \
-H "Accept: application/json" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Example Response¶
STATUS: 200 OK
{
"segments": [
{
"segmentId": "00000000-0000-0000-0000-000000000005",
"name": "transaction amount 10-50",
"description": "desc",
"active": false,
"parts": [
{
"segmentPartId": "00000000-0000-0000-0000-000000000055",
"criteria": [
{
"criterionId": "00000000-0000-0000-0000-000000000055",
"fromAmount": 10,
"toAmount": 50,
"type": "transaction_amount"
}
]
}
],
"createdAt": "2018-02-19T09:45:06+0100",
"customersCount": 0,
"averageTransactionAmount": 0,
"averageTransactions": 0,
"averageClv": 0,
"currency": "EUR"
},
{
"segmentId": "00000000-0000-0000-0000-000000000000",
"name": "test",
"description": "desc",
"active": false,
"parts": [
{
"segmentPartId": "00000000-0000-0000-0000-000000000000",
"criteria": [
{
"criterionId": "00000000-0000-0000-0000-000000000002",
"min": 10,
"max": 20,
"type": "transaction_count"
},
{
"criterionId": "00000000-0000-0000-0000-000000000001",
"fromAmount": 1,
"toAmount": 10000,
"type": "average_transaction_amount"
},
{
"criterionId": "00000000-0000-0000-0000-000000000000",
"posIds": [
"00000000-0000-474c-1111-b0dd880c07e2"
],
"type": "bought_in_pos"
}
]
}
],
"createdAt": "2018-02-19T09:45:06+0100",
"customersCount": 0,
"averageTransactionAmount": 0,
"averageTransactions": 0,
"averageClv": 0,
"currency": "EUR"
}
],
"total": 2
}
Create new segment¶
To create a new segment, you need to call the /api/<storeCode>/segment
endpoint with the POST
method.
Definition¶
POST /api/<storeCode>/segment
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store to create the segment in. |
segment[name] | request | Segment name |
segment[active] | request | (optional) Set 1 if active, otherwise 0 |
segment[description] | request | (optional) A short description |
segment[parts][0][criteria][0][type] | request | Criterion type. It can be one of the following:
anniversary , bought_in_pos , transaction_count ,
transaction_amount , average_transaction_amount ,
last_purchase_n_days_before , purchase_period ,
transaction_percent_in_pos , bought_skus , bought_makers ,
bought_labels , customer_has_labels ,
customer_has_labels_with_values , customer_list . |
segment[parts][0][criteria][0][days] | request | Segment width in days. If set to 1, only customers with anniversary on
this exact date are in the segment.
(required) for anniversary criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][anniversaryType] | request | Anniversary type: birthday or registration .
(required) for anniversary criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][fromAmount] | request | Minimum value of transactions.
(required) for average_transaction_amount and transaction_amount
criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][toAmount] | request | Maximum value of transactions.
(required) for average_transaction_amount and transaction_amount
criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][posIds][] | request | One or more UUIDs of POS.
(required) minimum 1 in collection for bought_in_pos criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][posId] | request | Exactly one UUID of POS.
(required) for transaction_percent_in_pos criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][percent] | request | Treshold percent value.
(required) for transaction_percent_in_pos criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][makers][] | request | One of more brands.
(required) minimum 1 in collection for bought_makers criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][skuIds][] | request | One or more SKUs.
(required) minimum 1 in collection for bought_skus criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][labels][] | request | One or more Labels, which apply either to the product or the customer.
Each label is an array of key and value elements:
...[labels][0][key]=key_one&...[labels][0][value]=value_one .
For customer_has_labels criterions, there should be no value element.
(required) minimum 1 in collection for bought_labels ,
customer_has_labels and customer_has_labels_with_values
criterion types.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][days] | request | Segment includes customers who shopped at least this many days ago.
1 is yesterday.
(required) for last_purchase_n_days_before criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][fromDate] | request | Start of date range.
(required) for purchase_period criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][toDate] | request | End of time range.
(required) for purchase_period criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][min] | request | Minimum transaction count.
(required) for transaction_count criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][max] | request | Maximum transaction count.
(required) for transaction_count criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][customers][] | request | One or more Customers, identified by UUID, phone, loyalty card number,
or e-mail address. Identifiers don’t have to be of the same type.
(required) minimum 1 in collection for customer_list criterion type.
(forbidden) for other criterion types. |
Example¶
curl http://localhost:8181/api/DEFAULT/segment/00000000-0000-0000-0000-000000000002` \
-X "POST" \
-H "Accept: application/json" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
-d "segment[name]=testsm" \
-d "segment[active]=1" \
-d "segment[description]=testsmdescription" \
-d "segment[parts][0][criteria][0][type]=anniversary" \
-d "segment[parts][0][criteria][0][days]=2" \
-d "segment[parts][0][criteria][0][anniversaryType]=registration"
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Note
To create an OR condition, add another SegmentPart
element in the segment[parts]
array.
To create an AND condition, add another Criterion
element in the segment[parts][<part_element>][criteria]
array.
Delete segment¶
To delete a segment, you need to call the /api/<storeCode>/segment/<segment>
endpoint with the DELETE
method.
Definition¶
DELETE /api/<storeCode>/segment/<segment>
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store the segment belongs to. |
<segment> | query | Segment ID |
Example¶
curl http://localhost:8181/api/DEFAULT/segment/f9a64320-0e93-42b9-882c-43cd477156cf \
-X "DELETE" \
-H "Accept: application/json" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Note
The f9a64320-0e93-42b9-882c-43cd477156cf segment ID is an example value. Your value may be different. Check the list of all segments if you are not sure which id should be used.
Example Response¶
STATUS: 204 No Content
Get segment details¶
To retrieve segment details, you need to call the /api/<storeCode>/segment/<segment>
endpoint with the GET
method.
Definition¶
GET /api/<storeCode>/segment/<segment>
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store the segment belongs to. |
<segment> | query | Segment ID |
Example¶
To see the details of the customer user with segment = 00000000-0000-0000-0000-000000000002
, use the method below:
curl http://localhost:8181/api/DEFAULT/segment/00000000-0000-0000-0000-000000000002` \
-X "GET" \
-H "Accept: application/json" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Example Response¶
STATUS: 200 OK
{
"segmentId": "00000000-0000-0000-0000-000000000002",
"name": "anniversary",
"description": "desc",
"active": false,
"parts": [
{
"segmentPartId": "00000000-0000-0000-0000-000000000001",
"criteria": [
{
"criterionId": "00000000-0000-0000-0000-000000000011",
"anniversaryType": "birthday",
"days": 10,
"type": "anniversary"
}
]
}
],
"createdAt": "2018-02-19T09:45:06+0100",
"customersCount": 0,
"averageTransactionAmount": 0,
"averageTransactions": 0,
"averageClv": 0,
"currency": "EUR"
}
Update segment data¶
To fully update segment’s configuration, you need to call the /api/<storeCode>/segment/<segment>
endpoint with the PUT
method.
Definition¶
PUT /api/<storeCode>/segment/<segment>
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store the segment belongs to. |
<segment> | query | Segment ID |
segment[name] | request | Segment name |
segment[active] | request | (optional) Set 1 if active, otherwise 0 |
segment[description] | request | (optional) A short description |
segment[parts][0][criteria][0][type] | request | Criterion type. It can be one of the following:
anniversary , bought_in_pos , transaction_count ,
transaction_amount , average_transaction_amount ,
last_purchase_n_days_before , purchase_period ,
transaction_percent_in_pos , bought_skus , bought_makers ,
bought_labels , customer_has_labels ,
customer_has_labels_with_values , customer_list . |
segment[parts][0][criteria][0][days] | request | Segment width in days. If set to 1, only customers with anniversary on
this exact date are in the segment.
(required) for anniversary criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][anniversaryType] | request | Anniversary type: birthday or registration .
(required) for anniversary criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][fromAmount] | request | Minimum value of transactions.
(required) for average_transaction_amount and transaction_amount
criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][toAmount] | request | Maximum value of transactions.
(required) for average_transaction_amount and transaction_amount
criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][posIds][0] | request | One or more UUIDs of POS.
(required) minimum 1 in collection for bought_in_pos criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][posId] | request | Exactly one UUID of POS.
(required) for transaction_percent_in_pos criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][percent] | request | Treshold percent value.
(required) for transaction_percent_in_pos criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][makers][0] | request | One of more brands.
(required) minimum 1 in collection for bought_makers criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][skuIds][0] | request | One or more SKUs.
(required) minimum 1 in collection for bought_skus criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][labels][0] | request | One or more Labels, which apply either to the product or the customer.
Each label is an array of key and value elements:
...[labels][0][key]=key_one&...[labels][0][value]=value_one .
For customer_has_labels criterions, there should be no value element.
(required) minimum 1 in collection for bought_labels ,
customer_has_labels and customer_has_labels_with_values
criterion types.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][days] | request | Segment includes customers who shopped at least this many days ago.
1 is yesterday.
(required) for last_purchase_n_days_before criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][fromDate] | request | Start of date range.
(required) for purchase_period criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][toDate] | request | End of time range.
(required) for purchase_period criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][min] | request | Minimum transaction count.
(required) for transaction_count criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][max] | request | Maximum transaction count.
(required) for transaction_count criterion type.
(forbidden) for other criterion types. |
segment[parts][0][criteria][0][customers][0] | request | One or more Customer UUIDs.
(required) minimum 1 in collection for customer_list criterion type.
(forbidden) for other criterion types. |
Example¶
To update the details of a segment with id segment = 17347292-0aaf-4c25-9118-17eb2c55b58b
, use the method below:
curl http://localhost:8181/api/DEFAULT/segment/17347292-0aaf-4c25-9118-17eb2c55b58b \
-X "PUT" \
-H "Accept:\ application/json" \
-H "Content-type:\ application/x-www-form-urlencoded" \
-H "Authorization:\ Bearer\ eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
-d "segment[name]=tests" \
-d "segment[active]=0" \
-d "segment[description]=tests" \
-d "segment[parts][0][criteria][0][type]=anniversary" \
-d "segment[parts][0][criteria][0][days]=2" \
-d "segment[parts][0][criteria][0][anniversaryType]=birthday"
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Note
To create an OR condition, add another SegmentPart
element in the segment[parts]
array.
To create an AND condition, add another Criterion
element in the segment[parts][<part_element>][criteria]
array.
Activate segment¶
To activate a segment, you need to call the /api/<storeCode>/segment/<segment>/activate
endpoint with the POST
method.
Definition¶
POST /api/<storeCode>/segment/<segment>/activate
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store the segment belongs to. |
<segment> | query | Segment ID |
Example¶
curl http://localhost:8181/api/DEFAULT/segment/63afec60-5e74-43fc-a5e1-81bbc03421ca/activate \
-X "POST" \
-H "Accept:\ application/json" \
-H "Content-type:\ application/x-www-form-urlencoded" \
-H "Authorization:\ Bearer\ eyJhbGciOiJSUzI1NiIsInR5cCI6..."
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Example Response¶
STATUS: 204 No Content
Get customers assigned to specific segment¶
To retrieve a paginated list of customers assigned to a specific segment, you need to call the /api/<storeCode>/segment/<segment>/customers
endpoint with the GET
method.
Definition¶
GET /api/<storeCode>/segment/<segment>/customers
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store the segment belongs to. |
<segment> | query | Segment ID |
firstName | query | (optional) First Name |
lastName | query | (optional) Last Name |
phone | query | (optional) Phone |
query | (optional) E-mail | |
page | query | (optional) Start from page, by default 1 |
perPage | query | (optional) Number of items to display per page, by default = 10 |
sort | query | (optional) Sort by column name, by default = name |
direction | query | (optional) Direction of sorting [ASC, DESC], by default = ASC |
Example¶
curl http://localhost:8181/api/DEFAULT/segment/63afec60-5e74-43fc-a5e1-81bbc03421ca/customers \
-X "GET" \
-H "Accept: application/json" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Attention
Pagination limitation, we can only show 10,000 results. 10,000 is a limit and can be found in the .env file.
Example Response¶
STATUS: 200 OK
{
"customers": [
{
"segmentId": "63afec60-5e74-43fc-a5e1-81bbc03421ca",
"customerId": "57524216-c059-405a-b951-3ab5c49bae14",
"segmentName": "test123",
"firstName": "Tomasz",
"lastName": "Test80",
"email": "tomasztest80@wp.pl",
"active": true,
"address": [],
"createdAt": "2018-02-20T08:22:11+0100",
"levelId": "000096cf-32a3-43bd-9034-4df343e5fd94",
"manuallyAssignedLevelId": {
"levelId": "000096cf-32a3-43bd-9034-4df343e5fd94"
},
"agreement1": true,
"agreement2": false,
"agreement3": false,
"status": {
"availableTypes": [
"new",
"active",
"blocked",
"deleted"
],
"availableStates": [
"no-card",
"card-sent",
"with-card"
],
"type": "active",
"state": "no-card"
},
"updatedAt": "2018-02-20T08:22:12+0100",
"campaignPurchases": [],
"transactionsCount": 1,
"transactionsAmount": 44.97,
"transactionsAmountWithoutDeliveryCosts": 44.97,
"amountExcludedForLevel": 0,
"averageTransactionAmount": 44.97,
"lastTransactionDate": "2018-02-20T07:24:19+0100",
"currency": "eur",
"levelPercent": "20.00%"
}
],
"total": 1
}
Deactivate segment¶
To deactivate a segment, you need to call the /api/<storeCode>/segment/<segment>/deactivate
endpoint with the POST
method.
Definition¶
POST /api/<storeCode>/segment/<segment>/deactivate
Parameter | Parameter type | Description |
---|---|---|
Authorization | header | Token received during authentication |
<storeCode> | query | Code of the store the segment belongs to. |
<segment> | query | Segment ID |
Example¶
curl http://localhost:8181/api/DEFAULT/segment/63afec60-5e74-43fc-a5e1-81bbc03421ca/deactivate \
-X "POST" \
-H "Accept:\ application/json" \
-H "Content-type:\ application/x-www-form-urlencoded" \
-H "Authorization:\ Bearer\ eyJhbGciOiJSUzI1NiIsInR5cCI6..."
Note
The eyJhbGciOiJSUzI1NiIsInR5cCI6… authorization token is an example value. Your value may be different. Read more about Authorization here.
Example Response¶
STATUS: 204 No Content