Skip to content

Commit b96505f

Browse files
rahinisrinivasrahinisrinivas
authored
Rule Promotion usages (#229)
* Rule Promotion usages * add overview * update from review * added account ID on usages * add changelog * edits
1 parent 6802272 commit b96505f

File tree

9 files changed

+302
-3
lines changed

9 files changed

+302
-3
lines changed

‎changelog/2024/2024-08-2-changelog.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: 'Rule Promotion Stacking and Priority (API Only)'
2+
title: 'Stacking and Priority (API Only) for Promotions Builder'
33
date: '2024-08-2'
4-
tags: ['Rule Promotions']
4+
tags: ['Promotions Builder']
55
hide_blog_post_date: false
66
---
77

‎changelog/2024/2024-08-26-changelog.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: 'Usages for Promotions Builder'
3+
date: '2024-08-26'
4+
tags: ['Promotions Builder']
5+
hide_blog_post_date: false
6+
---
7+
8+
**MAJOR** We have added **Promotions Builder Usages** to help you track and understand how promotional offers are utilized. With this feature, you can:
9+
10+
- Retrieve the usage history of a specific promotion.
11+
- Track the history of a particular promotion code within a promotion.
12+
- Anonymize customer email addresses associated with promotion usages.
13+
14+
For more information see [Promotion Usages](/docs/promotions-builder/overview#promotion-usages).

‎docs/promotions-builder/overview.md

+8
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,14 @@ To learn more about promotion codes, see [Promotion Codes](/docs/promotions-buil
116116
- Multiple promotions can have the same code name. This means that different promotions can be identified using the same code names, allowing shoppers to apply a single coupon code that triggers multiple promotions. For more information see [Duplicate Codes](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes#duplicate-codes).
117117
:::
118118

119+
### Promotion Usages
120+
121+
Promotion usages are helpful in tracking and understanding how promotional offers are utilized. This includes details such as which promotions were used, how frequently they were used, order ID, code ID, customer email, date of the promotion's usage. To retrieve the usage history of a specific promotion, see [Get Promotion Usages](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages).
122+
123+
You can also track the history of a specific promotion code within a particular promotion. See [Get a Promotion Code Usage](/docs/promotions-builder/promotions-builder-codes/get-a-promotion-code-usage).
124+
125+
Additionally, you can also choose to anonymize customer email addresses associated with promotion usages. For more information, see [Anonymizing Promotion Code Usages](/docs/promotions-builder/promotions-builder-codes/Anonymize-promotion-code-usages).
126+
119127
## Cart-level Discount Apportioning
120128

121129
Discount apportioning involves distributing cart-level discounts among the individual items in the cart, ensuring transparency and clarity in how discounts are allocated and represented at both the cart and item levels. Each discount includes essential details such as IDs, codes, amounts, and indicates their source as `rule-promotion`. It is important to note that item-level apportioning for cart-level discounts specifically applies to Promotions Builder.

‎docs/promotions-builder/promotions-builder-codes/Anonymize-promotion-code-usages.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Anonymize Promotion Code Usages
3+
nav_label: Anonymize Promotion Code Usages
4+
sidebar_position: 8
5+
---
6+
7+
## `Post` Anonymize Promotion Code Usages
8+
9+
```http
10+
https://useast.api.elasticpath.com/v2/rule-promotions/usages/anonymize
11+
12+
```
13+
14+
Use this endpoint to anonymize promotion code usage. When anonymization is successful, Personal Identifiable Information such as the `customer_email` address is replaced with `*`.
15+
16+
## Parameters
17+
18+
### Path parameters
19+
20+
| Name | Required | Type | Description |
21+
|:-----|:---------|:---------|:---------------------------------|
22+
| `usage_ids` | Required | `array [string]` | The unique identifiers of the usages to be anonymized. You can anonymize multiple usages at the same time. |
23+
24+
### Headers
25+
26+
| Name | Required | Type | Description |
27+
|:----------------|:---------|:---------|:-------------------------------------|
28+
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |
29+
30+
## Request Example
31+
32+
```bash
33+
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/usages/anonymize \
34+
-H "Authorization: Bearer XXXX" \
35+
-H "Content-Type: application/json" \
36+
-d $ {
37+
"data": {
38+
"usage_ids": ["333ad446-8611-435a-97e4-0d1aa970e6c7"]
39+
}
40+
}
41+
```
42+
43+
## Response Example
44+
45+
`200 OK`
46+
47+
```json
48+
{
49+
"data": [
50+
{
51+
"id": "333ad446-8611-435a-97e4-0d1aa970e6c7",
52+
"order_id": "b9b21932-a021-4b84-861f-501f1c222dfc",
53+
"code_id": "31b5877e-2c19-4d9c-9418-166d7759c8e7",
54+
"code": "unlimited",
55+
"times_used": 1,
56+
"used_on": "2024-08-15T23:27:18.068Z",
57+
"customer_id": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
58+
"customer_email": "**",
59+
"meta": {
60+
"timestamps": {
61+
"updated_at": "2024-08-15T23:28:08.874Z"
62+
}
63+
},
64+
"updated_by": "Key-2439657140697170361",
65+
"anonymized": true
66+
}
67+
]
68+
}
69+
```

‎docs/promotions-builder/promotions-builder-codes/get-a-promotion-code-usage.md

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Get a Promotion Code Usage
3+
nav_label: Get a Promotion Code Usage
4+
sidebar_position: 7
5+
---
6+
7+
## `GET` Get a Promotion Code Usage
8+
9+
```http
10+
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/:code/usages
11+
```
12+
13+
This endpoint retrieves the usage history of a specific promotion code within a specific promotion, including details like `order_id`, `code`, and `times_used`.
14+
15+
## Parameters
16+
17+
### Path parameters
18+
19+
| Name | Required | Type | Description |
20+
|:-----|:---------|:---------|:---------------------------------|
21+
| `promotionID` | Required | `string` | The unique identifier for the rule promotion. |
22+
| `code` | Required | `string` | Specifies the name of the code. For example, `10OFF`. |
23+
24+
### Headers
25+
26+
| Name | Required | Type | Description |
27+
|:----------------|:---------|:---------|:-------------------------------------|
28+
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |
29+
30+
### Query parameters
31+
32+
| Name | Required | Type | Description |
33+
| ---- | -------- | -------- | -------------------------------- |
34+
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages#filtering). |
35+
| `page[limit]` | Optional | `integer` | The number of records per page. |
36+
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
37+
| `sort` | Optional | `string` | Supported attribute is `used_on`. When specified, the results are sorted in an ascending order. To sort in descending order, prefix the attribute with -, for example, `-used_on`. See [Sorting](/guides/Getting-Started/sorting). |
38+
39+
## Filtering
40+
41+
The following operators and attributes are available for filtering usages:
42+
43+
| Attribute | Type | Operators | Example |
44+
| ---------| --------- | ---------------------------| -------- |
45+
| `id` | `string` | `eq` | `eq(id,8dac76b3-9282-4730-b1dd-bdd2a95610cb)` |
46+
| `code` | `string` | `eq` | `eq(code,cart1off)` |
47+
| `used_on` | `string` | `gt`,`ge`,`le` and `lt` | `gt(used_on,2023-07-11)` |
48+
49+
## Request Example
50+
51+
```bash
52+
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/:code/usages \
53+
-H "Authorization: Bearer XXXX" \
54+
-H "Content-Type: application/json" \
55+
```
56+
57+
## Response Example
58+
59+
When a cart with a promotion is checked out using an `accountID`, the `accountID` will be included in the response.
60+
61+
`200 OK`
62+
63+
```json
64+
{
65+
"data": [
66+
{
67+
"id": "96a80700-4895-4d74-b96f-3ea39417ed29",
68+
"order_id": "5728c924-cd08-4b4a-a36a-1a926ee92ad3",
69+
"code_id": "fd23fcc6-e2cc-4900-9505-d38147c3019a",
70+
"code": "bxgy",
71+
"times_used": 1,
72+
"used_on": "2024-08-15T18:25:41.209Z",
73+
"customer_email": "[email protected]",
74+
"meta": {
75+
"timestamps": {
76+
"updated_at": "2024-08-15T18:25:41.209Z"
77+
}
78+
},
79+
"anonymized": false,
80+
"account_id": "c40ee30c-f5f9-4a40-8f3f-08f7c652b0c5"
81+
}
82+
],
83+
"links": {
84+
"current": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
85+
"first": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
86+
"last": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
87+
"prev": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
88+
"next": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10"
89+
},
90+
"meta": {
91+
"page": {
92+
"limit": 10,
93+
"offset": 0,
94+
"current": 1,
95+
"total": 1
96+
},
97+
"results": {
98+
"total": 1
99+
}
100+
}
101+
}
102+
```

‎docs/promotions-builder/promotions-builder-codes/get-promotion-usages.md

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Get Promotion Usages
3+
nav_label: Get Promotion Usages
4+
sidebar_position: 6
5+
---
6+
7+
## `GET` Get Promotion Usages
8+
9+
```http
10+
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/usages
11+
```
12+
13+
This endpoint retrieves the usage history of a specific promotion, including details such as `order_id`, `code`, and `times_used`.
14+
15+
## Parameters
16+
17+
### Path parameters
18+
19+
| Name | Required | Type | Description |
20+
|:-----|:---------|:---------|:---------------------------------|
21+
| `promotionID` | Required | `string` | The unique identifier for the rule promotion. |
22+
23+
### Headers
24+
25+
| Name | Required | Type | Description |
26+
|:----------------|:---------|:---------|:-------------------------------------|
27+
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |
28+
29+
### Query parameters
30+
31+
| Name | Required | Type | Description |
32+
| ---- | -------- | -------- | -------------------------------- |
33+
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages#filtering). |
34+
| `page[limit]` | Optional | `integer` | The number of records per page. |
35+
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
36+
| `sort` | Optional | `string` | Supported attribute is `used_on`. When specified, the results are sorted in an ascending order. To sort in descending order, prefix the attribute with -, for example, `-used_on`. See [Sorting](/guides/Getting-Started/sorting). |
37+
38+
## Filtering
39+
40+
The following operators and attributes are available for filtering usages:
41+
42+
| Attribute | Type | Operators | Example |
43+
| ---------| --------- | ---------------------------| -------- |
44+
| `id` | `string` | `eq` | `eq(id,8dac76b3-9282-4730-b1dd-bdd2a95610cb)` |
45+
| `code` | `string` | `eq` | `eq(code,cart1off)` |
46+
| `used_on` | `string` | `gt`,`ge`,`le` and `lt` | `gt(used_on,2023-07-11)` |
47+
48+
## Request Example
49+
50+
```bash
51+
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/usages \
52+
-H "Authorization: Bearer XXXX" \
53+
-H "Content-Type: application/json" \
54+
```
55+
56+
## Response Example
57+
58+
When a cart with a promotion is checked out using an `accountID`, the `accountID` will be included in the response.
59+
60+
`200 OK`
61+
62+
```json
63+
{
64+
"data": [
65+
{
66+
"id": "96a80700-4895-4d74-b96f-3ea39417ed29",
67+
"order_id": "5728c924-cd08-4b4a-a36a-1a926ee92ad3",
68+
"code_id": "fd23fcc6-e2cc-4900-9505-d38147c3019a",
69+
"code": "bxgy",
70+
"times_used": 1,
71+
"used_on": "2024-08-15T18:25:41.209Z",
72+
"customer_email": "[email protected]",
73+
"meta": {
74+
"timestamps": {
75+
"updated_at": "2024-08-15T18:25:41.209Z"
76+
}
77+
},
78+
"anonymized": false,
79+
"account_id": "c40ee30c-f5f9-4a40-8f3f-08f7c652b0c5"
80+
}
81+
],
82+
"links": {
83+
"current": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
84+
"first": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
85+
"last": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
86+
"prev": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
87+
"next": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10"
88+
},
89+
"meta": {
90+
"page": {
91+
"limit": 10,
92+
"offset": 0,
93+
"current": 1,
94+
"total": 1
95+
},
96+
"results": {
97+
"total": 1
98+
}
99+
}
100+
}
101+
```

‎guides/Getting-Started/filtering.md

+2
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ Filtering is currently supported on the following endpoints:
5858
* [Get all Custom APIs](/docs/api/commerce-extensions/get-all-custom-apis)
5959
* [Get all Custom Fields](/docs/api/commerce-extensions/get-all-custom-fields)
6060
* [Get all Custom API Entries](/docs/api/commerce-extensions/get-all-custom-entries)
61+
* [Get Usages for Promotion](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages)
62+
* [Get a Promotion Code Usage](/docs/promotions-builder/promotions-builder-codes/get-a-promotion-code-usage)
6163

6264
## Filtering Syntax
6365

‎guides/Getting-Started/pagination.md

+2
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ Even if the result is zero, pagination fields are always included in the respons
7070
* [Get all Inventory](/docs/api/pxm/inventory/get-stock-for-all-products)
7171
* [Get all Files](/docs/api/pxm/files/get-all-files)
7272
* [Get all Jobs](/docs/api/pxm/products/get-all-jobs)
73+
* [Get Usages for Promotion](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages)
74+
* [Get a Promotion Code Usage](/docs/promotions-builder/promotions-builder-codes/get-a-promotion-code-usage)
7375

7476
## Limitations
7577

‎guides/Getting-Started/sorting.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ Sorting is also supported within [JavaScript SDK](/docs/developer-tools#software
1616
|:---------------|:---------|:---------|:-------------------------------------------------------------------------|
1717
| `sort` | Optional | `string` | The attribute to sort by. Supported attributes differ based on endpoint. |
1818

19-
2019
## Supported Endpoints
2120

2221
* [Get All Accounts](/docs/api/accounts/get-v-2-accounts)
@@ -25,3 +24,5 @@ Sorting is also supported within [JavaScript SDK](/docs/developer-tools#software
2524
* [Get all User Authentication Info](/docs/authentication/single-sign-on/user-authentication-info-api/get-all-user-authentication-info)
2625
* [Get all Customers](/docs/customer-management/customer-management-api/get-all-customers)
2726
* [Get all Orders](/docs/api/carts/get-customer-orders)
27+
* [Get Usages for Promotion](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages)
28+
* [Get a Promotion Code Usage](/docs/promotions-builder/promotions-builder-codes/get-a-promotion-code-usage)

0 commit comments

Comments
 (0)