The VTEX Policies System API manages reusable policy rules that can be applied across the VTEX platform. Policies define conditional logic for promotions, pricing, catalog visibility, and checkout behaviors, enabling merchants to create flexible rule-based configurations.
openapi: 3.0.0
info:
title: VTex Policies System API
description: "\r\n This API will create promotion alarms when selling products with undesired prices and promotions. It will create conditions that will check if the prices and the promotions are correct. If not, the system will alarm the store with information about the product sold at unexpected prices.\r\n\r\n ## Index\r\n\r\n- `GET` [Get Policy List](https://developers.vtex.com/docs/api-reference/policies-system-api#get-/api/policy-engine/policies)\r\n- `POST` [Evaluate Policies](https://developers.vtex.com/docs/api-reference/policies-system-api#post-/api/policy-engine/evaluate)\r\n- `GET` [Get Policy by ID](https://developers.vtex.com/docs/api-reference/policies-system-api#get-/api/policy-engine/policies/-id-)\r\n- `POST` [Create Policy](https://developers.vtex.com/docs/api-reference/policies-system-api#post-/api/policy-engine/policies/-id-)\r\n- `PUT` [Update Policy](https://developers.vtex.com/docs/api-reference/policies-system-api#put-/api/policy-engine/policies/-id-)\r\n- `DELETE` [Delete Policy by ID](https://developers.vtex.com/docs/api-reference/policies-system-api#delete-/api/policy-engine/policies/-id-)"
contact: {}
version: ''
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/api/policy-engine/policies:
get:
tags:
- Policy
summary: VTex Get policy list
description: "Retrieves a list of all policies in the account and general information of each policy.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Promotions Policy Engine | Policies | **List Policies** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Policy_List
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PolicyGetResponse'
description: Array of objects with policies infomation.
example:
- id: pa_test_001
name: TestAlarmBerenice
description: TesteMarcosPromotionsAlert
statements:
- effect: Allow
actions:
- id: SendSlackMessage
metadata:
channel: C01NJFF35R6
relatedUsers:
- URUNDC2NB
alertDescription: Avoid selling products from Berenice with a discount greater than 70%.
resource: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
condition:
conditions:
- conditions: []
operation: stringEquals
key: brandId
values:
- '2000001'
- conditions: []
operation: numericGreaterThan
key: discountPercentage
values:
- '70.00'
operation: and
/api/policy-engine/evaluate:
post:
tags:
- Policy
summary: VTex Evaluate policies
description: "This endpoint consults all policies and checks the ones that satisfy the request body’s conditions.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Promotions Policy Engine | Policies | **Evaluate Policy** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Policy_Evaluate
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluatePolicyRequest'
example:
resource: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
context:
brandId: '2000001'
discountPercentage: '91.00'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PolicyActionGetResponse'
description: Array of objects with policies infomation.
example:
- id: SendSlackMessage
metadata:
channel: C01NJFF35R6
relatedUsers:
- URUNDC2NB
alertDescription: Avoid selling products from Berenice with a discount greater than 70%.
deprecated: false
/api/policy-engine/policies/{id}:
get:
tags:
- Policy
summary: VTex Get policy by ID
description: "Retrieves general information of a policy by its ID.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Promotions Policy Engine | Policies | **Get Policy** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Policy_Get
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: id
in: path
required: true
description: Policy ID.
schema:
type: string
example: pa_test_001
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PolicyGetResponse'
description: Array of objects with policies infomation.
example:
- id: pa_test_001
name: TestAlarmBerenice
description: TesteMarcosPromotionsAlert
statements:
- effect: Allow
actions:
- id: SendSlackMessage
metadata:
channel: C01NJFF35R6
relatedUsers:
- URUNDC2NB
alertDescription: Avoid selling products from Berenice with a discount greater than 70%.
resource: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
condition:
conditions:
- conditions: []
operation: stringEquals
key: brandId
values:
- '2000001'
- conditions: []
operation: numericGreaterThan
key: discountPercentage
values:
- '70.00'
operation: and
post:
tags:
- Policy
summary: VTex Create policy
description: "Creates a new policy from scratch.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Promotions Policy Engine | Policies | **Create or Update Policy** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Policy_CreateOrUpdate
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: id
in: path
required: true
description: Policy ID.
schema:
type: string
example: pa_test_001
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PolicySaveRequest'
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: array
items:
$ref: '#/components/schemas/PolicyGetResponse'
description: Array of objects with policies infomation.
example:
- id: pa_test_001
name: TestAlarmBerenice
description: TesteMarcosPromotionsAlert
statements:
- effect: Allow
actions:
- id: SendSlackMessage
metadata:
channel: C01NJFF35R6
relatedUsers:
- URUNDC2NB
alertDescription: Avoid selling products from Berenice with a discount greater than 70%.
resource: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
condition:
conditions:
- conditions: []
operation: stringEquals
key: brandId
values:
- '2000001'
- conditions: []
operation: numericGreaterThan
key: discountPercentage
values:
- '70.00'
operation: and
put:
tags:
- Policy
summary: VTex Update policy
description: "Updates an existing policy at your account.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Promotions Policy Engine | Policies | **Create or Update Policy** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: id
in: path
required: true
description: Policy ID.
schema:
type: string
example: pa_test_001
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PolicySaveRequest'
required: true
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: array
items:
$ref: '#/components/schemas/PolicyGetResponse'
description: Array of objects with policies infomation.
example:
- id: pa_test_001
name: TestAlarmBerenice
description: TesteMarcosPromotionsAlert
statements:
- effect: Allow
actions:
- id: SendSlackMessage
metadata:
channel: C01NJFF35R6
relatedUsers:
- URUNDC2NB
alertDescription: Avoid selling products from Berenice with a discount greater than 40%.
resource: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
condition:
conditions:
- conditions: []
operation: stringEquals
key: brandId
values:
- '2000001'
- conditions: []
operation: numericGreaterThan
key: discountPercentage
values:
- '40.00'
operation: and
deprecated: false
delete:
tags:
- Policy
summary: VTex Delete policy by ID
description: "Deletes a specific policy of the account by its ID.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Promotions Policy Engine | Policies | **Delete Policy** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Policy_Delete
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: id
in: path
required: true
description: Policy ID.
schema:
type: string
example: pa_test_001
responses:
'200':
description: 200 OK
deprecated: false
security:
- appKey: []
appToken: []
- VtexIdclientAutCookie: []
components:
schemas:
PolicyActionGetResponse:
title: PolicyActionGetResponse
type: object
description: Object with policy conditions.
properties:
id:
type: string
description: Action ID.
title: id
metadata:
type: object
description: Metadata object from the current action.
title: metadata
additionalProperties: true
EvaluatePolicyRequest:
required:
- resource
- context
type: object
description: Object with policy conditions.
properties:
resource:
description: Scope on which this policy must be evaluated.
title: resource
type: string
example: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
context:
type: object
description: Conditions that the policy needs to satisfy.
title: context
example:
brandId: '2000001'
discountPercentage: '91.00'
additionalProperties: true
PolicySaveRequest:
required:
- name
- description
- statements
type: object
properties:
name:
type: string
description: Policy name.
title: name
example: id
description:
type: string
description: Policy description, only for internal use.
title: description
example: TesteMarcosPromotionsAlert
statements:
type: array
title: statements
items:
$ref: '#/components/schemas/StatementGetResponse'
description: Requirements for the the policy to be applied.
PolicyGetResponse:
title: PolicyGetResponse
description: Object with policy information.
type: object
properties:
id:
type: string
title: id
description: Policy ID.
name:
type: string
description: Policy name.
title: name
example: id
description:
type: string
description: Policy description, only for internal use.
title: description
statements:
type: array
title: statements
items:
$ref: '#/components/schemas/StatementGetResponse'
description: Requirements for the policy to be applied.
StatementGetResponse:
type: object
description: Object with policy conditions.
required:
- effect
properties:
effect:
type: string
title: effect
description: This field is not functional at the moment. To create a correct request, fill the field with `Allow`.
example: Allow
deprecated: true
actions:
type: array
title: actions
items:
properties:
id:
type: string
title: id
description: Action ID.
example: SendSlackMessage
enum:
- SendSlackMessage
- SendEmail
- DeactivatePromotions
metadata:
type: object
title: metadata
description: Data inside of the actions.
additionalProperties: true
type: object
description: Array with actions information.
description: Actions that the policy will execute.
resource:
type: string
description: Scope on which this policy must be evaluated.
title: resource
example: vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert
condition:
type: object
properties:
conditions:
type: array
description: List of conditions that will activate the policy.
items:
description: List of conditions that will activate the policy.
properties:
conditions:
title: conditions
type: array
description: List of conditions the actions can have. It can be an empty array `[]`.
enum:
- []
- - stringEquals
- - numericGreaterThan
items:
type: string
description: Condition value.
operation:
type: string
title: operation
description: The action of the condition.
example: None
enum:
- None
- stringEquals
- stringEqualsIgnoreCase
- numericEquals
- numericLessThan
- numericLessThanEquals
- numericGreaterThan
- numericGreaterThanEquals
- bool
- not
- or
- and
- dateTimeUtcGreaterThan
- dateTimeUtcLessThan
- between
key:
type: string
title: key
description: The element that will define what the policy will influence.
example: skuId
enum:
- skuId
- brandId
- discountPercentage
values:
type: array
title: values
items:
type: string
description: Key value.
example: '40.00'
description: Array with values of the key.
description: Condition to activate this policy. This object can have a maximum of ten recursive conditions.
title: condition
operation:
type: string
title: operation
description: This operation will determine if all the conditions need to be valid or at least one of them, if the conditions array is not empty.
example: None
enum:
- None
- stringEquals
- stringEqualsIgnoreCase
- numericEquals
- numericLessThan
- numericLessThanEquals
- numericGreaterThan
- numericGreaterThanEquals
- bool
- not
- or
- and
- dateTimeUtcGreaterThan
- dateTimeUtcLessThan
- between
securitySchemes:
appKey:
type: apiKey
in: header
name: X-VTEX-API-AppKey
description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
appToken:
type: apiKey
in: header
name: X-VTEX-API-AppToken
description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
VtexIdclientAutCookie:
type: apiKey
in: header
name: VtexIdclientAutCookie
description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'
parameters:
Content-Type:
name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
Accept:
name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
tags:
- name: Policy