Catalog management and rules API

Use the Catalog management and rules GraphQL API to set up and manage catalogs and to configure settings and rules for product discovery and merchandising. For more information about the API, see the developer documentation.

API Endpoints
https://<your store>/graphql
Headers
# Your API token from the dashboard. Must be included in all API calls.
Authorization: Bearer <YOUR_TOKEN_HERE>
Version

1.0.0

Queries

channel

Description

Fetches a single channel by its identifier.

Parameters:

  • channelId: Channel identifier to filter by.

Available Channel fields to include in the query:

  • channelId: Channel identifier.
  • name: Channel name.
  • scopes: List of locale scopes identifiers.
  • policyIds: List of policy identifiers.
  • createdAt: Timestamp when the channel was created.
  • updatedAt: Timestamp when the channel data was last updated.
  • policies: List of Policy objects associated with the current channel.

Available Policy fields to query for:

  • policyId: Policy identifier.
  • name: Policy Name.
  • mandatory: Indicates if the policy is compulsory or not (true | false).
  • createdAt: Timestamp when the policy was created.
  • updatedAt: Timestamp when the policy data was last updated.
  • actions: List of actions for the policies, comprised by triggers and filters.

Available Action fields to query for:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Available Trigger fields to query for:

  • name: Name of the trigger.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Available Action Filters fields to query for:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Query Examples

  1. Using an invalid / non-existent channel identifier parameter:
query {
    channel(channelId: "NON_EXISTENT_ID") {
        channelId
        name
    }
}

Response

{
    "errors": [
        {
            "message": "Channel [NON_EXISTENT_ID] not found for Environment [ENV_ID]",
            "locations": [
                {
                    "line": 2,
                    "column": 9
                }
            ],
            "path": ["channel"],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ],
    "extensions": {
        "request-id": "b17b7816ec286028"
    }
}
  1. Querying only channel information:
query {
    channel(channelId: "3945d84e-93d7-4dc0-b304-b6f48d91226d") {
        channelId
        name
        scopes {
          locale
        }
    }
}

Response

{
    "data": {
        "channel": {
            "channelId": "3945d84e-93d7-4dc0-b304-b6f48d91226d",
            "name": "Brand A",
            "scopes": [
                { "locale": "locale1" },
                { "locale": "locale2" }
            ]
        }
    },
    "extensions": {
        "request-id": "c7b4488e0d2ba5ca"
    }
}
  1. Querying channel with policies information:
query {
    channel(channelId: "3945d84e-93d7-4dc0-b304-b6f48d91226d") {
        channelId
        name
        policies {
            policyId
            name
            mandatory
        }
    }
}

Response

{
    "data": {
        "channel": {
            "channelId": "3945d84e-93d7-4dc0-b304-b6f48d91226d",
            "name": "Brand A",
            "policies": [
                {
                    "policyId": "105de4d4-8f95-4382-bf09-bac063af068d",
                    "name": "Policy-1",
                    "mandatory": false,
                }, ...
            ]
        }
    },
    "extensions": {
        "request-id": "cdf07806c25b92aa"
    }
}
Response

Returns a ChannelResponse!

Arguments
Name Description
channelId - String!

Example

Query
query channel($channelId: String!) {
  channel(channelId: $channelId) {
    channelId
    createdAt
    name
    policies {
      ...PolicyResponseFragment
    }
    policyIds
    scopes {
      ...ChannelScopeResponseFragment
    }
    updatedAt
  }
}
Variables
{"channelId": "abc123"}
Response
{
  "data": {
    "channel": {
      "channelId": "abc123",
      "createdAt": "xyz789",
      "name": "abc123",
      "policies": [PolicyResponse],
      "policyIds": ["xyz789"],
      "scopes": [ChannelScopeResponse],
      "updatedAt": "abc123"
    }
  }
}
back to top
Queries

channels

Description

Fetches an array of all channels.

Available Channel fields to include in query:

  • channelId: Channel identifier.
  • name: Channel name.
  • scopes: List of locale scopes identifiers.
  • policyIds: List of policy identifiers.
  • createdAt: Timestamp when the channel was created.
  • updatedAt: Timestamp when the channel data was last updated.
  • policies: List of Policy objects associated with the current channel.

Available Policy fields to query for:

  • policyId: Policy identifier.
  • name: Policy Name.
  • mandatory: Indicates if the policy is compulsory or not (true | false).
  • createdAt: Timestamp when the policy was created.
  • updatedAt: Timestamp when the policy data was last updated.
  • actions: List of actions for the policies, comprised by triggers and filters.

Available Action fields to query for:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Available Trigger fields to query for:

  • name: Name of the trigger.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Available Action Filters fields to query for:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Query Examples

  1. List Channels only:
query {
    channels {
        channelId
        name
        scopes {
          locale
        }
    }
}

Response

{
    "data": {
        "channels": [
            {
                "channelId": "b3361730-03d5-4cff-a09d-a05c5f930fa7",
                "name": "Brand B",
                "scopes": [
                    { "locale": "locale3" },
                    { "locale": "locale4" }
                ]
            },
            {
                "channelId": "3945d84e-93d7-4dc0-b304-b6f48d91226d",
                "name": "Brand A",
                "scopes": [
                    { "locale": "locale1" },
                    { "locale": "locale2" }
                ]
            }, ...
        ]
    },
    "extensions": {
        "request-id": "85399873f950a5d7"
    }
}
  1. List Channels with Policies:
query {
    channels {
        channelId
        name
        policies {
            policyId
            name
            mandatory
            actions {
                filters {
                    attribute
                    value
                    enabled
                    valueSource
                }
            }
        }
    }
}

Response

{
    "data": {
        "channels": [
            {
                "channelId": "b3361730-03d5-4cff-a09d-a05c5f930fa7",
                "name": "Brand B",
                "policies": [
                    {
                        "policyId": "105de4d4-8f95-4382-bf09-bac063af068d",
                        "name": "Static Value Policy",
                        "mandatory": false,
                        "actions": [
                            {
                                "filters": [
                                    {
                                        "attribute": "my_attribute",
                                        "value": "2",
                                        "enabled": true,
                                        "valueSource": "STATIC"
                                    }
                                ]
                            }
                        ]
                    }, ...
                ]
            },
            {
                "channelId": "3945d84e-93d7-4dc0-b304-b6f48d91226d",
                "name": "Brand A",
                "policies": []
            }
        ]
    },
    "extensions": {
        "request-id": "80efd740df9e55eb"
    }
}
Response

Returns [ChannelResponse!]

Example

Query
query channels {
  channels {
    channelId
    createdAt
    name
    policies {
      ...PolicyResponseFragment
    }
    policyIds
    scopes {
      ...ChannelScopeResponseFragment
    }
    updatedAt
  }
}
Response
{
  "data": {
    "channels": [
      {
        "channelId": "abc123",
        "createdAt": "abc123",
        "name": "xyz789",
        "policies": [PolicyResponse],
        "policyIds": ["xyz789"],
        "scopes": [ChannelScopeResponse],
        "updatedAt": "abc123"
      }
    ]
  }
}
back to top
Queries

policies

Description

Fetches a list of policies.

Available Policy fields to query for:

  • policyId: Policy identifier.
  • name: Policy Name.
  • mandatory: Indicates if the policy is compulsory or not (true | false).
  • createdAt: Timestamp when the policy was created.
  • updatedAt: Timestamp when the policy data was last updated.
  • actions: List of actions for the policies, comprised by triggers and filters.

Available Action fields to query for:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Available Trigger fields to query for:

  • name: Name of the trigger.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Available Action Filters fields to query for:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Query Examples

  1. List Policies
query {
    policies {
        policyId
        name
        mandatory
        actions {
            filters {
                attribute
                value
                enabled
                valueSource
            }
        }
    }
}

Response

{
    "data": {
        "policies": [
            {
                "policyId": "105de4d4-8f95-4382-bf09-bac063af068d",
                "name": "Static Value Policy",
                "mandatory": false,
                "actions": [
                    {
                        "filters": [
                            {
                                "attribute": "my_attribute",
                                "value": "2",
                                "enabled": true,
                                "valueSource": "STATIC"
                            }
                        ]
                    }
                ]
            },
            ...
        ]
    },
    "extensions": {
        "request-id": "b9cb7fb1852ca4f0"
    }
}
Response

Returns [PolicyResponse!]

Example

Query
query policies {
  policies {
    actions {
      ...ActionResponseFragment
    }
    createdAt
    mandatory
    name
    policyId
    updatedAt
  }
}
Response
{
  "data": {
    "policies": [
      {
        "actions": [ActionResponse],
        "createdAt": "abc123",
        "mandatory": false,
        "name": "abc123",
        "policyId": "xyz789",
        "updatedAt": "xyz789"
      }
    ]
  }
}
back to top
Queries

policy

Description

Fetches a single policy by its identifier.

Parameters:

  • policyId: Policy identifier.

Available Policy fields to query for:

  • policyId: Policy identifier.
  • name: Policy Name.
  • mandatory: Indicates if the policy is compulsory or not (true | false).
  • createdAt: Timestamp when the policy was created.
  • updatedAt: Timestamp when the policy data was last updated.
  • actions: List of actions for the policies, comprised by triggers and filters.

Available Action fields to query for:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Available Trigger fields to query for:

  • name: Name of the trigger.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Available Action Filters fields to query for:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Query Examples:

  1. Querying for a non-existent policy:
query {
    policy(policyId: "NON_EXISTENT_ID") {
        policyId
        name
        mandatory
    }
}

Response

{
    "errors": [
        {
            "message": "Policy [NON_EXISTENT_ID] not found",
            "locations": [
                {
                    "line": 2,
                    "column": 5
                }
            ],
            "path": ["policy"],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ],
    "extensions": {
        "request-id": "d505090e43511f18"
    }
}
  1. Querying for an existent policy:
query {
    policy(policyId: "6f8b5a55-b97c-481a-94f3-5a813821c787") {
        policyId
        name
        mandatory
        actions {
            triggers {
                name
                transportType
            }
        }
    }
}

Response

{
    "data": {
        "policy": {
            "policyId": "6f8b5a55-b97c-481a-94f3-5a813821c787",
            "name": "Policy-1",
            "mandatory": false,
            "actions": [
                {
                    "triggers": [
                        {
                            "name": "AC-Policy-POL1",
                            "transportType": "HTTP_HEADER"
                        },
                        ...
                    ]
                },
                ...
            ]
        }
    },
    "extensions": {
        "request-id": "a2f4514b3b106663"
    }
}
Response

Returns a PolicyResponse!

Arguments
Name Description
policyId - String!

Example

Query
query policy($policyId: String!) {
  policy(policyId: $policyId) {
    actions {
      ...ActionResponseFragment
    }
    createdAt
    mandatory
    name
    policyId
    updatedAt
  }
}
Variables
{"policyId": "xyz789"}
Response
{
  "data": {
    "policy": {
      "actions": [ActionResponse],
      "createdAt": "xyz789",
      "mandatory": true,
      "name": "xyz789",
      "policyId": "xyz789",
      "updatedAt": "xyz789"
    }
  }
}
back to top
Queries

scopes

Description

Retrieves composable catalog scope information such as locales

Response

Returns [Scope]!

Example

Query
query scopes {
  scopes {
    locale
  }
}
Response
{"data": {"scopes": [{"locale": "abc123"}]}}
back to top

Mutations

batchChannel

Description

Inserts or Updates channels in a single batch operation.

Input:

  • channels (UpdateChannelRequest): a list of items to insert or update. If any item in the batch does not have a channelId field, a new channel will be created for that record; otherwise, it will be updated.
    • channelId: Channel identifier. Optional.
    • name: Name of the channel. Optional
    • scopes: List of locale scopes identifiers. If provided, it cannot be empty.
    • policyIds: List of policy identifiers. If provided, it cannot be empty.

Example

mutation {
    batchChannel(channels: [
        {
            channelId: "844ed921",
            name: "Channel Web/Online & Offline",
            scopes: [
                { locale : "en_US" },
                { locale : "en_UK" },
                { locale : "es_ES" }
            ]
        },
        {
            name: "Offline Channel",
            scopes: [
                { locale : "en_UK" },
                { locale : "fr_FR" }
            ],
            "policyIds": [
                "c1bcfed9-4096-4068-aab5-d88f6f39cfad",
                "a3f4e403-a720-4b27-a266-d69099ae2421"
            ]
        }
    ]) {
        channels {
            channelId
            name
            scopes {
              locale
            }
            policyIds
            createdAt
            updatedAt
        }
        errors
    }
}

Response

{
    "data": {
        "batchChannel": {
        "channels": [
            {
                "channelId": "e3cbe432-71a2-47cb-938f-29af8be940ab",
                "name": "Channel Web/Online & Offline",
                "scopes": [
                    { "locale": "en_US" },
                    { "locale": "en_UK" },
                    { "locale": "es_ES" }
                ],
                "policyIds": [
                    "c1bcfed9-4096-4068-aab5-d88f6f39cfad",
                    "a3f4e403-a720-4b27-a266-d69099ae2421"
                ],
                "createdAt": "2024-11-08T14:55:37.938",
                "updatedAt": "2024-11-12T11:13:22.554967"
            },
            {
                "channelId": "f485f368-3a5a-497b-a13e-4fff8c66df09",
                "name": "Offline Channel",
                "scopes": [
                    { "locale": "en_UK" },
                    { "locale": "fr_FR" }
                ],
                "policyIds": [
                    "c1bcfed9-4096-4068-aab5-d88f6f39cfad",
                    "a3f4e403-a720-4b27-a266-d69099ae2421"
                ],
                "createdAt": "2024-11-12T11:13:22.562566",
                "updatedAt": "2024-11-12T11:13:22.562566"
            }
        ],
        "errors": []
        }
    },
    "extensions": {
        "request-id": "d5863f2f668d897a"
    }
}

In the provided example, the first item, with channel identifier of '844ed921' will update the provided attributes, while the second item in the list will be created, as reflected by the 'createdAt' and 'updatedAt' attributes for the response. Please note that the response returns also an errors list, where any transaction failure will be appended to.

Response

Returns a BatchChannelResponse!

Arguments
Name Description
channels - [UpdateChannelRequest!]!

Example

Query
mutation batchChannel($channels: [UpdateChannelRequest!]!) {
  batchChannel(channels: $channels) {
    channels {
      ...ChannelResponseFragment
    }
    errors
  }
}
Variables
{"channels": [UpdateChannelRequest]}
Response
{
  "data": {
    "batchChannel": {
      "channels": [ChannelResponse],
      "errors": ["xyz789"]
    }
  }
}
back to top
Mutations

batchPolicy

Description

Updates a batch of policies.

Input

  • policies (UpdatePolicyRequest). List of items to insert or update. If any item in the batch does not have a policyId field, a new policy will be created for that record; otherwise, it will be updated.
    • policyId: Policy identifier. Optional.
    • name: Name of the policy. Optional.
    • mandatory: Indicates if the policy is compulsory or not (true | false). Optional.
    • actions: List of actions to update. Optional. If passed, it cannot be empty.

Action fields:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Trigger fields:

  • name: Name of the trigger. If it does not start with "AC-Policy-", an error is returned.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Action Filters fields:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Caveat:

Currently, appending or removing items to the list of actions, triggers, or filters, is an all-or-nothing operation, meaning that, if the fields are included, then, whatever it is provided, will replace the current values.

Example

  1. Creates a new policy "POL18:1" and updates policy with id "39c8106d":
mutation {
    batchPolicy(
        policies: [
            {
                name: "Policy-18122024"
                mandatory: false
            },
            {
                name: "Policy-1""
                mandatory: false
                actions: [{
                    filters: [{
                        attribute: "my_attribute"
                        value: "AC-Policy-POL1"
                        enabled: false
                        actionFilterOperator: EQUALS
                        valueSource: TRIGGER
                    }]
                    triggers: [{
                        transportType: HTTP_HEADER
                        name: "AC-Policy-POL1"
                    }]
                }]
            }
        ]
    ) {
        policies {
            policyId
            name
            mandatory
            createdAt
            updatedAt
        }
        errors
    }
}

Response

{
    "data": {
        "batchPolicy": {
            "policies": [
                {
                    "policyId": "d179f1b6-e2bb-4f1e-843b-c06ca828de2d",
                    "name": "Policy-1",
                    "mandatory": false,
                    "createdAt": "2024-11-12T12:00:16.146",
                    "updatedAt": "2024-11-12T18:15:50.847842"
                },
                {
                    "policyId": "887962f7-0b0c-4836-8cd3-2087d908cd91",
                    "name": "Policy-2",
                    "mandatory": false,
                    "createdAt": "2024-11-12T18:15:50.855190",
                    "updatedAt": "2024-11-12T18:15:50.855190"
                }
            ],
            "errors": []
        }
    },
    "extensions": {
        "request-id": "e22f7db098c31607"
    }
}
Response

Returns a BatchPolicyResponse!

Arguments
Name Description
policies - [UpdatePolicyRequest!]!

Example

Query
mutation batchPolicy($policies: [UpdatePolicyRequest!]!) {
  batchPolicy(policies: $policies) {
    errors
    policies {
      ...PolicyResponseFragment
    }
  }
}
Variables
{"policies": [UpdatePolicyRequest]}
Response
{
  "data": {
    "batchPolicy": {
      "errors": ["abc123"],
      "policies": [PolicyResponse]
    }
  }
}
back to top
Mutations

createChannel

Description

Creates a new channel.

Input

  • channelRequest (CreateChannelRequest): Channel creation information map.

    • name: Name of the channel. Mandatory. Needs to be unique.
    • scopes: List of locale scopes identifiers. At least one locale object should be provided.
    • policyIds: List of policy identifiers. These should be already created and available. At least one policy identifier should be provided.

Example

  1. Create a new channel:
mutation {
    createChannel(
        channelRequest: {
            name: "Channel Web/Online",
            scopes: [
                { locale: "en_US" },
                { locale: "en_UK" }
            ]
            policyIds : [
                "6f8b5a55-b97c-481a-94f3-5a813821c787",
                "63992079-52b5-49b2-a739-312a079c19b7",
            ]
        }
    ) {
        channelId
        name
        scopes {
          locale
        }
        policyIds
        createdAt
        updatedAt
    }
}

Response

{
    "data": {
        "createChannel": {
            "channelId": "1e3c0bc2-d2c8-4eff-aa7b-aa83a824825a",
            "name": "Channel Web/Online",
            "scopes": [
                { "locale" : "en_US" },
                { "locale" : "en_UK" }
            ],
            policyIds : [
                "6f8b5a55-b97c-481a-94f3-5a813821c787",
                "63992079-52b5-49b2-a739-312a079c19b7",
            ],
            "createdAt": "2024-11-08T14:57:24.541128",
            "updatedAt": "2024-11-08T14:57:24.541128"
        }
    },
    "extensions": {
        "request-id": "ea46a3e19c219068"
    }
}
  1. Create a new channel and requesting its associated policies:
mutation {
    createChannel(
        channelRequest: {
            name: "Brand A"
            scopes: [
                { locale : "en_US"}
                { locale : "en_UK"}
            ]
            policyIds : [
                "6f8b5a55-b97c-481a-94f3-5a813821c787",
                "63992079-52b5-49b2-a739-312a079c19b7",
            ]
        }
    ) {
        channelId
        name
        scopes {
            locale
        }
        policyIds
        createdAt
        updatedAt
        policies {
            policyId
            name
            actions {
                triggers {
                    transportType
                    name
                }
                filters {
                    attribute
                    actionFilterOperator
                    value
                    enabled
                    valueSource
                }
            }
            mandatory
            createdAt
            updatedAt
        }
    }
}

Response

{
    "data": {
        "createChannel": {
            "channelId": "b4ab7a72-1556-49b4-b1ac-125902f37a0b",
            "name": "Brand A",
            "scopes": [
                { "locale": "en_US" },
                { "locale": "en_UK" }
            ],
            "policyIds": [
                "6f8b5a55-b97c-481a-94f3-5a813821c787",
                "63992079-52b5-49b2-a739-312a079c19b7"
            ],
            "createdAt": "2024-11-20T17:53:53.613",
            "updatedAt": "2024-11-20T17:53:53.613",
            "policies": [
                {
                    "policyId": "6f8b5a55-b97c-481a-94f3-5a813821c787",
                    "name": "Policy-1",
                    "actions": [
                        {
                            "triggers": [
                                {
                                    "transportType": "HTTP_HEADER",
                                    "name": "AC-Policy-POL1"
                                }
                            ],
                            "filters": [
                                {
                                    "attribute": "my_attribute",
                                    "actionFilterOperator": "EQUALS",
                                    "value": "AC-Policy-POL1",
                                    "enabled": true,
                                    "valueSource": "TRIGGER"
                                }
                            ]
                        }
                    ],
                    "mandatory": false,
                    "createdAt": "2024-11-20T14:09:57",
                    "updatedAt": "2024-11-20T14:09:57"
                },
                {
                    "policyId": "63992079-52b5-49b2-a739-312a079c19b7",
                    "name": "Policy-1",
                    "actions": [
                        {
                            "triggers": [
                                {
                                    "transportType": "HTTP_HEADER",
                                    "name": "AC-Policy-POL1"
                                }
                            ],
                            "filters": [
                                {
                                    "attribute": "my_attribute",
                                    "actionFilterOperator": "EQUALS",
                                    "value": "AC-Policy-POL1",
                                    "enabled": false,
                                    "valueSource": "STATIC"
                                }
                            ]
                        }
                    ],
                    "mandatory": false,
                    "createdAt": "2024-11-20T14:09:57",
                    "updatedAt": "2024-11-20T14:09:57"
                }
            ]
        }
    },
    "extensions": {
        "request-id": "caefdeb372058548"
    }
}
Response

Returns a ChannelResponse!

Arguments
Name Description
channelRequest - CreateChannelRequest!

Example

Query
mutation createChannel($channelRequest: CreateChannelRequest!) {
  createChannel(channelRequest: $channelRequest) {
    channelId
    createdAt
    name
    policies {
      ...PolicyResponseFragment
    }
    policyIds
    scopes {
      ...ChannelScopeResponseFragment
    }
    updatedAt
  }
}
Variables
{"channelRequest": CreateChannelRequest}
Response
{
  "data": {
    "createChannel": {
      "channelId": "xyz789",
      "createdAt": "abc123",
      "name": "abc123",
      "policies": [PolicyResponse],
      "policyIds": ["xyz789"],
      "scopes": [ChannelScopeResponse],
      "updatedAt": "xyz789"
    }
  }
}
back to top
Mutations

createPolicy

Description

Creates a new policy.

Input

  • policyRequest (CreatePolicyRequest):

    • name: Name of the policy. Mandatory
    • mandatory: Indicates if the policy is compulsory or not (true | false).
    • actions: List of actions. Mandatory.

Action fields:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Trigger fields:

  • name: Name of the trigger. If it does not start with "AC-Policy-", an error is returned.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Action Filters fields:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Example

mutation {
    createPolicy(
        policyRequest: {
            name: "Policy-200212000",
            actions: [
                {
                    triggers: [
                        {
                            transportType: HTTP_HEADER,
                            name: "AC-Policy-POL1"
                        }
                    ],
                    filters: [
                        {
                            attribute: "my_attribute",
                            actionFilterOperator: EQUALS,
                            value: "AC-Policy-POL01",
                            enabled: true,
                            valueSource: TRIGGER
                        }
                    ]
                }
            ],
            mandatory: true
        }) {
            policyId
            name
            mandatory
            actions {
                triggers {
                    transportType
                    name
                }
                filters {
                    attribute
                    actionFilterOperator
                    value
                    enabled
                    valueSource
                }
            }
            createdAt
            updatedAt
        }
}

Response

{
    "data": {
        "createPolicy": {
            "policyId": "39c8106d-aab2-49b2-aac3-177608d4d058",
            "name": "Policy-1",
            "mandatory": true,
            "actions": [
                {
                    "triggers": [
                        {
                            "transportType": "HTTP_HEADER",
                            "name": "AC-Policy-POL01"
                        }
                    ],
                    "filters": [
                        {
                            "attribute": "my_attribute",
                            "actionFilterOperator": "EQUALS",
                            "value": "AC-Policy-POL01",
                            "enabled": true,
                            "valueSource": "TRIGGER"
                        }
                    ]
                }
            ],
            "createdAt": "2024-11-12T12:00:16.146157",
            "updatedAt": "2024-11-12T12:00:16.146157"
        }
    },
    "extensions": {
        "request-id": "bbcdcbc79b5d873b"
    }
}
Response

Returns a PolicyResponse!

Arguments
Name Description
policyRequest - CreatePolicyRequest!

Example

Query
mutation createPolicy($policyRequest: CreatePolicyRequest!) {
  createPolicy(policyRequest: $policyRequest) {
    actions {
      ...ActionResponseFragment
    }
    createdAt
    mandatory
    name
    policyId
    updatedAt
  }
}
Variables
{"policyRequest": CreatePolicyRequest}
Response
{
  "data": {
    "createPolicy": {
      "actions": [ActionResponse],
      "createdAt": "abc123",
      "mandatory": false,
      "name": "abc123",
      "policyId": "xyz789",
      "updatedAt": "xyz789"
    }
  }
}
back to top
Mutations

deleteChannel

Description

Deletes a channel by its identifier.

Input

  • channelId: Channel identifier. If not provided, it will return an error.

Example

  1. Delete an existing channel:
mutation {
    deleteChannel(channelId: "11730ac6-9f52-4490-a366-0c8237239a3f")
}

Response

{
    "data": {
        "deleteChannel": "11730ac6-9f52-4490-a366-0c8237239a3f"
    },
    "extensions": {
        "request-id": "819e07d8b8b80af9"
    }
}
  1. Trying to delete a non-existent channel:
mutation {
    deleteChannel(channelId: "11730ac6-9f52-4490-a366-0c8237239a3f")
}

Response

{
    "errors": [
        {
            "message": "Channel 11730ac6-9f52-4490-a366-0c8237239a3f not found",
            "locations": [
                {
                "line": 2,
                "column": 3
                }
            ],
            "path": ["deleteChannel"],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ],
    "extensions": {
        "request-id": "98e60e98e0c8a0ff"
    }
}
Response

Returns a String!

Arguments
Name Description
channelId - String!

Example

Query
mutation deleteChannel($channelId: String!) {
  deleteChannel(channelId: $channelId)
}
Variables
{"channelId": "xyz789"}
Response
{"data": {"deleteChannel": "abc123"}}
back to top
Mutations

deletePolicy

Description

Deletes a given policy by its identifier.

Input

  • policyId: Policy identifier. Mandatory. If not found, an error is returned.

Examples

  1. Deleting an existing policy:
mutation {
    deletePolicy(policyId: "8ac25122")
}

Response

{
    "data": {
        "deletePolicy": "8ac25122"
    },
    "extensions": {
        "request-id": "9b88d28bb67856bd"
    }
}
  1. Deleting a missing policy. An error is returned:
mutation {
    deletePolicy(policyId: "NON_EXISTENT_POLICY_ID")
}

Response

{
    "errors": [
        {
            "message": "Policy NON_EXISTENT_POLICY_ID not found",
            "locations": [{
                "line": 2,
                "column": 7
            }],
            "path": ["deletePolicy"],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ],
    "extensions": {
        "request-id": "87962a2e351180d7"
    }
}
Response

Returns a String!

Arguments
Name Description
policyId - String!

Example

Query
mutation deletePolicy($policyId: String!) {
  deletePolicy(policyId: $policyId)
}
Variables
{"policyId": "abc123"}
Response
{"data": {"deletePolicy": "xyz789"}}
back to top
Mutations

updateChannel

Description

Updates data in an existing channel by its identifier.

Input:

  • channelRequest (UpdateChannelRequest). Channel information to update.

    • channelId: Channel identifier. Mandatory.
    • name: Name of the channel. Optional.
    • scopes: List of locale scopes identifiers. Optional.
    • policyIds: List of policy identifiers. Optional

Caveat:

Currently, appending or removing to the list of locales or policies
is an all-or-nothing operation, meaning that, if the fields are included,
then, whatever it is provided, will replace the current values.

Example

  1. Updating the name of a given channel:
mutation {
    updateChannel(
        channelRequest: {
            channelId: "1e3c0bc2-d2c8-4eff-aa7b-aa83a824825a",
            name: "Channel Web/Online/Mortar&Bricks"
        }) {
        channelId
        name
        createdAt
        updatedAt
    }
}

Response

{
    "data": {
        "updateChannel": {
            "channelId": "1e3c0bc2-d2c8-4eff-aa7b-aa83a824825a",
            "name": "Channel Web/Online/Mortar&Bricks",
            "createdAt": "2024-11-08T14:57:24.541",
            "updatedAt": "2024-11-08T15:22:34.168738"
        }
    },
    "extensions": {
        "request-id": "d1d390da0b92d91a"
    }
}
Response

Returns a ChannelResponse!

Arguments
Name Description
channelRequest - UpdateChannelRequest!

Example

Query
mutation updateChannel($channelRequest: UpdateChannelRequest!) {
  updateChannel(channelRequest: $channelRequest) {
    channelId
    createdAt
    name
    policies {
      ...PolicyResponseFragment
    }
    policyIds
    scopes {
      ...ChannelScopeResponseFragment
    }
    updatedAt
  }
}
Variables
{"channelRequest": UpdateChannelRequest}
Response
{
  "data": {
    "updateChannel": {
      "channelId": "xyz789",
      "createdAt": "xyz789",
      "name": "xyz789",
      "policies": [PolicyResponse],
      "policyIds": ["xyz789"],
      "scopes": [ChannelScopeResponse],
      "updatedAt": "abc123"
    }
  }
}
back to top
Mutations

updatePolicy

Description

Updates an existent policy.

Input

  • policyRequest (UpdatePolicyRequest). Policy information to update.
    • policyId: Policy identifier. Mandatory. If it doesn't exist, it fails with error.
    • name: Name of the policy. Optional.
    • mandatory: Indicates if the policy is compulsory or not (true | false). Optional.
    • actions: List of actions to update. Optional.

Action fields:

  • triggers: List of triggers where the policy is activated.
  • filters: List of action filters.

Trigger fields:

  • name: Name of the trigger. If it does not start with "AC-Policy-", an error is returned.
  • transportType: Type of transport type, currently only "HTTP_HEADER" is supported.

Action Filters fields:

  • attribute: Name of the attribute to filter by.
  • value: Value to query for.
  • enabled: Indicates if the filter is enabled or not (true | false).
  • valueSource: Any of "TRIGGER" , "STATIC".
  • actionFilterOperator: Any of "EQUALS", "GREATER_THAN_EQUAL", "LESS_THAN_EQUAL".

Caveat:

Currently, appending or removing items to the list of actions, triggers, or filters, is an all-or-nothing operation, meaning that, if the fields are included, then, whatever it is provided, will replace the current values.

Examples:

  1. Updating the name of a policy:
mutation {
    updatePolicy( policyRequest: {
        policyId:"39c8106d",
        name: "Offline Channel (Disabled)",
    }) {
        policyId
        name
    }
}

Response

{
    "data": {
        "updatePolicy": {
            "policyId": "39c8106d",
            "name": "Offline Channel (Disabled)"
        }
    },
    "extensions": {
        "request-id": "a0347b3b579e1acb"
    }
}
  1. Attempting to update a missing policy. An error is returned:
mutation {
    updatePolicy( policyRequest: {
        policyId:"NON_EXISTENT_POLICY_ID",
        name: "Offline Channel (Disabled)",
    }) {
        policyId
        name
    }
}

Response

{
    "errors": [
        {
            "message": "Policy NON_EXISTENT_POLICY_ID not found",
            "locations": [
                {
                "line": 2,
                "column": 5
                }
            ],
            "path": [
                "updatePolicy"
            ],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ],
    "extensions": {
        "request-id": "82c39ad9e91b4620"
    }
}
  1. Updating a policy's actions list:
mutation {
    updatePolicy(policyRequest: {
        policyId:"d179f1b6-e2bb-4f1e-843b-c06ca828de2d",
            actions: [{
                triggers: [{
                    transportType: HTTP_HEADER,
                    name: "AC-Policy-POL1"
                }],
                filters: [{
                    attribute: "my_attribute",
                    actionFilterOperator: EQUALS,
                    value: "AC-Policy-POL1",
                    enabled: true,
                    valueSource: TRIGGER
                }]
            }]
    }) {
        policyId
        name
        actions {
            triggers {
                transportType
                name
            }
            filters {
                attribute
                actionFilterOperator
                value
                enabled
                valueSource
            }
        }
        createdAt
        updatedAt
    }
}

Response

{
    "data": {
        "updatePolicy": {
            "policyId": "d179f1b6-e2bb-4f1e-843b-c06ca828de2d",
            "name": "Offline Channel (Disabled)",
            "actions": [{
                "triggers": [{
                    "transportType": "HTTP_HEADER",
                    "name": "AC-Policy-POL1"
                }],
                "filters": [{
                    "attribute": "my_attribute",
                    "actionFilterOperator": "EQUALS",
                    "value": "AC-Policy-POL1",
                    "enabled": true,
                    "valueSource": "TRIGGER"
                }]
            }],
            "createdAt": "2024-11-12T12:00:16.146",
            "updatedAt": "2024-11-12T13:40:11.171292"
        }
    },
    "extensions": {
        "request-id": "bb8f5beda64d85cc"
    }
}
Response

Returns a PolicyResponse!

Arguments
Name Description
policyRequest - UpdatePolicyRequest!

Example

Query
mutation updatePolicy($policyRequest: UpdatePolicyRequest!) {
  updatePolicy(policyRequest: $policyRequest) {
    actions {
      ...ActionResponseFragment
    }
    createdAt
    mandatory
    name
    policyId
    updatedAt
  }
}
Variables
{"policyRequest": UpdatePolicyRequest}
Response
{
  "data": {
    "updatePolicy": {
      "actions": [ActionResponse],
      "createdAt": "xyz789",
      "mandatory": true,
      "name": "xyz789",
      "policyId": "abc123",
      "updatedAt": "abc123"
    }
  }
}
back to top

Types

ActionFilterOperator

Description

Action filter operator.

Values
Enum Value Description

EQUALS

GREATER_THAN_EQUAL

LESS_THAN_EQUAL
Example
"EQUALS"
back to top
Types

ActionFilterRequest

Description

Request input to define an action filter in a policy insert or update operation.

Fields
Input Field Description
actionFilterOperator - ActionFilterOperator! Filter comparison operator. Required.
attribute - String! Attribute name to use in the filter. Required.
enabled - Boolean! Indicates if the filter is enabled or not (true | false). Required.
value - String! Filter attribute value. Required.
valueSource - ActionFilterValueSource!

Indicates the location of action filter's value. Required.

  • If TRIGGER, then a corresponding trigger must be configured.
  • If STATIC, the value field must contain the value to apply in the action filter.
Example
{
  "actionFilterOperator": "EQUALS",
  "attribute": "abc123",
  "enabled": false,
  "value": "abc123",
  "valueSource": "STATIC"
}
back to top
Types

ActionFilterResponse

Description

Represents an action filter.

Fields
Field Name Description
actionFilterOperator - ActionFilterOperator Filter comparison operator.
attribute - String Attribute name to use in the filter.
enabled - Boolean Indicates if the filter is enabled or not (true | false).
value - String Filter attribute value.
valueSource - ActionFilterValueSource Indicates the type of action filter.
Example
{
  "actionFilterOperator": "EQUALS",
  "attribute": "xyz789",
  "enabled": true,
  "value": "xyz789",
  "valueSource": "STATIC"
}
back to top
Types

ActionFilterValueSource

Description

Action filter origin type.

Values
Enum Value Description

STATIC

TRIGGER
Example
"STATIC"
back to top
Types

ActionRequest

Description

Request input for defining policy actions in an update or insert operation.

Fields
Input Field Description
filters - [ActionFilterRequest!] List of action filters for the enclosing policy action item. Optional.
triggers - [TriggerRequest!] List of triggers for the enclosing policy action item. Optional. If not provided, then the policy will always be applied.
Example
{
  "filters": [ActionFilterRequest],
  "triggers": [TriggerRequest]
}
back to top
Types

ActionResponse

Description

Represents the associated triggers and filters for a given policy.

Fields
Field Name Description
filters - [ActionFilterResponse!] List of action filters for a given policy.
triggers - [TriggerResponse!] List of triggers for a given policy.
Example
{
  "filters": [ActionFilterResponse],
  "triggers": [TriggerResponse]
}
back to top
Types

BatchChannelResponse

Description

Response for batch operations (insert or update) over a channel objects list.

Fields
Field Name Description
channels - [ChannelResponse!] List of channels to insert or update.
errors - [String!] List of errors found during the insert or update operations, if any.
Example
{
  "channels": [ChannelResponse],
  "errors": ["xyz789"]
}
back to top
Types

BatchPolicyResponse

Description

Response object for policy batch updates/inserts.

Fields
Field Name Description
errors - [String!] List of errors found during the insert or update operations, if any.
policies - [PolicyResponse!] List of policy objects created or modified.
Example
{
  "errors": ["abc123"],
  "policies": [PolicyResponse]
}
back to top
Types

Boolean

Description

The Boolean scalar type represents true or false.

back to top
Types

ChannelResponse

Description

Represents a channel.

Fields
Field Name Description
channelId - String! Unique identifier for the channel.
createdAt - String Timestamp of when the channel was created, in ISO 8601 format (e.g., 2024-07-25T16:10:11.701669).
name - String! Name of the channel.
policies - [PolicyResponse] Policies associated to each channel (joined by policyIds).
policyIds - [String!] List of policy identifiers associated with the channel.
scopes - [ChannelScopeResponse!] List of scopes associated with the channel.
updatedAt - String Timestamp of the last update to the channel, in ISO 8601 format (e.g., 2024-07-25T16:10:11.701669).
Example
{
  "channelId": "abc123",
  "createdAt": "abc123",
  "name": "abc123",
  "policies": [PolicyResponse],
  "policyIds": ["abc123"],
  "scopes": [ChannelScopeResponse],
  "updatedAt": "abc123"
}
back to top
Types

ChannelScopeRequest

Fields
Input Field Description
locale - String!
Example
{"locale": "abc123"}
back to top
Types

ChannelScopeResponse

Fields
Field Name Description
locale - String!
Example
{"locale": "xyz789"}
back to top
Types

CreateChannelRequest

Description

Request input for creating a channel.

Fields
Input Field Description
name - String! Name of the Chanel. Mandatory.
policyIds - [String!] List of policy identifiers.
scopes - [ChannelScopeRequest!] List of locale identifiers.
Example
{
  "name": "xyz789",
  "policyIds": ["abc123"],
  "scopes": [ChannelScopeRequest]
}
back to top
Types

CreatePolicyRequest

Description

Request input for creating a policy.

Fields
Input Field Description
actions - [ActionRequest]! List of policy's actions. Required, at least one item.
mandatory - Boolean! Indicates if the policy is required or not (true | false). Required.
name - String! Name of the policy. Required.
Example
{
  "actions": [ActionRequest],
  "mandatory": false,
  "name": "abc123"
}
back to top
Types

PolicyResponse

Description

Represents a policy.

Fields
Field Name Description
actions - [ActionResponse!] List of actions associated to the policy.
createdAt - String Record creation timestamp.
mandatory - Boolean Indicates if the policy is required or not (true | false).
name - String Policy name.
policyId - String Policy identifier.
updatedAt - String Record's latest update timestamp.
Example
{
  "actions": [ActionResponse],
  "createdAt": "xyz789",
  "mandatory": false,
  "name": "xyz789",
  "policyId": "abc123",
  "updatedAt": "abc123"
}
back to top
Types

Scope

Fields
Field Name Description
locale - String
Example
{"locale": "xyz789"}
back to top
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"xyz789"
back to top
Types

TransportType

Description

Trigger's transport type.

Values
Enum Value Description

HTTP_HEADER
Example
"HTTP_HEADER"
back to top
Types

TriggerRequest

Description

Request input to define a policy trigger in a policy insert or update operation.

Fields
Input Field Description
name - String! Name of the trigger. Required.
transportType - TransportType! Type of transport. Only HTTP_HEADER supported. Required.
Example
{
  "name": "xyz789",
  "transportType": "HTTP_HEADER"
}
back to top
Types

TriggerResponse

Description

Represents a trigger action.

Fields
Field Name Description
name - String Name of the trigger. It should start with the "AC-Policy-" prefix.
transportType - TransportType Originating transport type. Currently only HTTP_HEADER is supported.
Example
{
  "name": "xyz789",
  "transportType": "HTTP_HEADER"
}
back to top
Types

UpdateChannelRequest

Description

Request input for updating a given channel. Also used for batch channel operations.

Fields
Input Field Description
channelId - String Channel identifier. Required only if used for an update operation. It can be omitted if used in a batch insert operation.
name - String Name of the channel to update.
policyIds - [String!] List of policy identifiers. Providing an empty list removes all policy links to the channel.
scopes - [ChannelScopeRequest!] List of scopes. Providing an empty list removes all scopes from the channel.
Example
{
  "channelId": "xyz789",
  "name": "xyz789",
  "policyIds": ["abc123"],
  "scopes": [ChannelScopeRequest]
}
back to top
Types

UpdatePolicyRequest

Description

Request input for updating a given policy. Also used in policy batch operations.

Fields
Input Field Description
actions - [ActionRequest!] List of policy's actions. Optional.
mandatory - Boolean Indicates if the policy is compulsory or not (true | false). Optional.
name - String Name of the policy. Optional.
policyId - String Policy identifier. Required only if used for an update operation. It can be omitted if used in a batch insert operation.
Example
{
  "actions": [ActionRequest],
  "mandatory": false,
  "name": "abc123",
  "policyId": "abc123"
}
back to top
Documentation by Anvil SpectaQL