Elastic Path Rule Promotion Usages API
The Rule Promotion Usages API from Elastic Path — 3 operation(s) for rule promotion usages.
OpenAPI Specification
openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Rule Promotion Usages API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
tags:
- name: Rule Promotion Usages
paths:
/v2/rule-promotions/usages/anonymize:
post:
tags:
- Rule Promotion Usages
summary: Anonymize Rule Promotion Usages
description: "Anonymizes user-related data in Rule Promotion usage records. \nThis operation is typically used for GDPR compliance or privacy-related requests.\n\n- This process replaces identifiable user data with anonymized placeholders.\n- Affects all recorded promotion usages where customer data is stored.\n- Does not impact historical transaction records or applied discounts.\n\nA successful request returns a `200 OK` response with the anonymized usage records.\n"
operationId: anonymizeRulePromotionUsages
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
usage_ids:
type: array
items:
type: string
description: 'The unique identifiers of the usages to be anonymized.
Multiple usage IDs can be provided to anonymize in bulk.
'
required:
- data
example:
data:
usage_ids:
- ca4385ec-7fb2-4a95-8690-f752c508d68a
- d4e5f6g7-h8i9-0j1k-2l3m-4n5o6p7q8r9s
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RulePromotionUsage'
- $ref: '#/components/schemas/Response.Error'
example:
data:
- id: ca4385ec-7fb2-4a95-8690-f752c508d68a
order_id: 8edd5ca8-39b7-468d-aea9-a470690ca98d
code_id: 00fc633b-9932-4e18-b122-fd5c3173caa3
code: node1off
times_used: 1
used_on: '2023-06-19T18:05:20.846Z'
customer_id: 9ef25142-d67a-41d3-99b2-4d30aeef6c9d
customer_email: '**'
meta:
timestamps:
updated_at: '2023-06-19T18:05:39.141Z'
updated_by: Key-2439657140697170361
anonymized: true
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 400
title: Invalid Request
detail: The request payload is malformed or missing required fields.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 401
title: Unauthorized
detail: Authentication credentials were missing or incorrect.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 404
title: Usages Not Found
detail: Some usage IDs could not be found.
meta:
usage_ids:
- invalid-usage-id-1
- invalid-usage-id-2
/v2/rule-promotions/{promotionID}/usages:
get:
tags:
- Rule Promotion Usages
summary: Get Rule Promotion Usages
description: 'Retrieves a list of usage records for a specific Rule Promotion.
- Provides details about when and how a promotion was used.
- Can be filtered and paginated to refine results.
- Useful for analyzing promotion effectiveness and customer engagement.
'
operationId: getRulePromotionUsages
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
- name: promotionID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion.
- name: filter
in: query
required: false
schema:
type: string
description: 'Filter attributes to refine the usage records. Supported attributes:
- `id`: Filter by usage ID.
- `code`: Filter by promotion code.
- `used_on`: Filter by usage date with operators `gt`, `ge`, `le`, `lt`.
'
example: eq(code,cart1off)
- name: page[limit]
in: query
required: false
schema:
type: integer
description: The number of records per page.
example: 10
- name: page[offset]
in: query
required: false
schema:
type: integer
description: The number of records to offset the results by.
example: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RulePromotionUsage'
links:
$ref: '#/components/schemas/PaginationLinks'
meta:
$ref: '#/components/schemas/PaginationMeta'
example:
data:
- id: a9b73e4d-637f-4f1c-9b3e-2de1f8a70351
order_id: e3d7b9fa-4a90-4e98-bac2-d7a4b4f2f63f
code_id: 8a2c3f47-9d3b-4562-8392-4e5e6cda3d2b
code: cart10off
times_used: 1
used_on: '2024-02-20T15:42:00.000Z'
customer_id: 4f3e8c5d-37e4-43fb-9276-d1b76f0c3a2a
customer_email: shopper@example.com
meta:
timestamps:
updated_at: '2024-02-20T15:45:00.000Z'
updated_by: Admin-User-123
links:
first: https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=0&page%5Blimit%5D=10
last: https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=90&page%5Blimit%5D=10
prev: null
next: https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=10&page%5Blimit%5D=10
meta:
pagination:
total: 100
limit: 10
offset: 0
current: 1
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 401
title: Unauthorized
detail: Authentication is required to access this resource.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 404
title: Promotion Not Found
detail: No usages found for the specified promotion ID.
/v2/rule-promotions/{promotionID}/codes/{code}/usages:
get:
tags:
- Rule Promotion Usages
summary: Get Rule Promotion Code Usages
description: 'Retrieves a list of usage records for a specific Rule Promotion code.
- Provides insights into how many times a specific code was used.
- Can be filtered and paginated to refine results.
- Useful for tracking the performance of individual promotion codes.
'
operationId: getRulePromotionCodeUsages
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Authorization'
- name: promotionID
in: path
required: true
schema:
type: string
description: The unique identifier of the rule promotion.
- name: code
in: path
required: true
schema:
type: string
description: The specific promotion code for which to retrieve usage records.
- name: filter
in: query
required: false
schema:
type: string
description: 'Filter attributes to refine the results. Supported attributes:
- `id`: Filter by usage ID.
- `used_on`: Filter by date with operators `gt`, `ge`, `le`, `lt`.
'
example: gt(used_on,2024-02-01T00:00:00Z)
- name: page[limit]
in: query
required: false
schema:
type: integer
description: The number of records per page.
example: 10
- name: page[offset]
in: query
required: false
schema:
type: integer
description: The number of records to offset the results by.
example: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RulePromotionUsage'
links:
$ref: '#/components/schemas/PaginationLinks'
meta:
$ref: '#/components/schemas/PaginationMeta'
example:
data:
- id: c2f45a8d-6ebf-4b6a-8b1c-d2e7c9e0f45f
order_id: 1a3b5c7d-9e2f-4a5b-8c1d-6e3f9b0d4c5f
code_id: 5d7e9f2b-3c4a-6b8d-1e9f-0a2b3c4d5e6f
code: holiday50
times_used: 2
used_on: '2024-02-18T10:30:00.000Z'
customer_id: 7e6c5d4b-3a2f-1e9d-8b0c-9f4e7d6c3b5a
customer_email: vipuser@example.com
meta:
timestamps:
updated_at: '2024-02-18T10:35:00.000Z'
updated_by: Admin-User-456
links:
first: https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=0&page%5Blimit%5D=10
last: https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=10&page%5Blimit%5D=10
prev: null
next: https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=10&page%5Blimit%5D=10
meta:
pagination:
total: 20
limit: 10
offset: 0
current: 1
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 401
title: Unauthorized
detail: Authentication is required to access this resource.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.Error'
example:
errors:
- status: 404
title: Promotion Code Not Found
detail: No usages found for the specified promotion code.
components:
parameters:
Authorization:
name: Authorization
in: header
description: The Bearer token required to get access to the API.
required: true
schema:
type: string
format: Bearer
schemas:
RulePromotionUsage:
type: object
description: Represents a single rule promotion usage record.
properties:
id:
type: string
description: The unique identifier of the usage record.
order_id:
type:
- string
- 'null'
description: The associated order ID, if applicable.
code_id:
type: string
description: The unique identifier of the promotion code.
code:
type: string
description: The promotion code used.
times_used:
type: integer
description: The number of times the promotion code has been used.
used_on:
type: string
format: date-time
description: The timestamp when the promotion was applied.
customer_id:
type:
- string
- 'null'
description: The customer identifier who used the promotion, if applicable.
account_id:
type:
- string
- 'null'
description: The account identifier associated with the promotion usage, if applicable.
customer_email:
type:
- string
- 'null'
description: The email of the customer who used the promotion, if applicable.
meta:
type: object
properties:
timestamps:
type: object
properties:
updated_at:
type: string
format: date-time
description: The timestamp when the usage record was last updated.
updated_by:
type: string
description: Identifier of the user or system that last updated the record.
anonymized:
type: boolean
description: Indicates whether the usage record has been anonymized.
PaginationMeta:
type: object
properties:
page:
type: object
properties:
current:
type: integer
description: Current page number
limit:
type: integer
description: Number of items per page
offset:
type: integer
description: Offset from the first result
total:
type: integer
description: Total number of pages
results:
type: object
properties:
total:
type: integer
description: Total number of results
total_method:
type: string
description: Method used to calculate the total (e.g., 'exact')
PaginationLinks:
type: object
properties:
current:
type: string
format: uri
description: URL for the current page of results
first:
type: string
format: uri
description: URL for the first page of results
last:
type: string
format: uri
description: URL for the last page of results
next:
type: string
format: uri
description: URL for the next page of results
prev:
type: string
format: uri
description: URL for the previous page of results
Response.Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type:
- string
- integer
description: HTTP status code.
title:
type: string
description: Error title.
detail:
type: string
description: Error details.
source:
type: string
description: Source of the error (e.g., which field or parameter caused the error)
meta:
type: object
properties:
usage_ids:
type: array
items:
type: string
securitySchemes:
BearerToken:
type: http
scheme: bearer