Elastic Path Rules API

openapi: 3.2.0
info:
  title: Catalogs Introduction Rules API
  description: 'Use the catalog-view Service API to create your catalogs.


    You also have the flexibility to create catalogs for different scenarios by combining hierarchies of products with a price book. Scenarios might include:


    - Multiple geographical regions. Display different catalogs in different regions with suitable pricing or combine product hierarchies from two different regions to display in a third region.

    - Multiple channels. Display different catalogs based on how a shopper accesses your store, such as through a mobile app or a web storefront.

    - Direct to business versus direct to customers. Offer different products and prices for business customers versus retail customers.

    - Preferred customers. Offer special pricing to preferred customers while displaying a standard price catalog to all other shoppers.

    - Reward programs. Enable reward programs where catalog prices drop after a certain spending level is reached.

    - Product sales. Offer sale items for a limited time.


    Scenarios are created by defining the context within which a catalog is displays. Contexts can be a customer ID, a channel, or any other user-defined tag that can be passed to the APIs from the front-end shopper experiences.

    '
  version: 26.0508.7574130
  x-version-timestamp: 2026-05-08 11:06:53+00:00
servers:
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
- url: https://useast.api.elasticpath.com
  description: US East Production Server
security:
- bearerAuth: []
tags:
- name: Rules
  description: 'If your store requires multiple catalogs, add catalog rules to control when a catalog is displayed. A catalog rule contains a catalog plus the criteria under which to display the catalog.


    :::caution


    You cannot create catalog rules for organization catalogs.


    :::


    You can use catalog rules to schedule a catalog to appear during a particular period, such as on a specific date or during summer. The catalog might offer different pricing during this period. The pricing depends on the associated price book.


    The following scenarios provides a few examples for using catalog rules.


    - **Multiple geographical regions**. Display different catalogs in different regions with suitable pricing or combine product hierarchies from two different regions to display in a third region.

    - **Multiple channels**. Display different catalogs based on how a shopper accesses your store, such as through a mobile app or a web storefront.

    - **Direct to business versus direct to customers**. Offer different products and prices for business customers versus retail customers.

    - **Preferred accounts**. Offer special pricing to a group of users while displaying a standard price catalog to other users.

    - **Preferred customers**. Offer special pricing to preferred customers while displaying a standard price catalog to all other shoppers.

    - **Reward programs**. Enable reward programs where catalog prices drop after a certain spending level is reached.

    - **Product sales**. Offer sale items for a limited time.

    - **Standard pricing**. Display a default catalog to the shoppers who do not meet the criteria of the other catalog rules.


    You can define a catalog rule with any of the following criteria.


    - **Accounts**. List the accounts that should see a catalog. When a user has logged in with the account, they see the configured catalog.

    - **Customers**. List the customers that should see a catalog. When the customer is logged in, they see the configured catalog.

    - **Channel**. Specify a shopper experience, such as web storefront or mobile app. Set up the channel to retrieve the catalog from the catalog rule that matches that channel.

    - **Other tags**. Create your own user-defined tags. For example, you might want to tag by regions or you might want to distinguish between business and consumer customers.


    If a catalog rule has no criteria defined, it is the default catalog rule.


    ### Resolving catalog rules


    When there is a request for a catalog, the store displays the catalog with the rule that matches the most attributes of the shoppers context.


    The request triggers the following steps:


    1. Compares the shoppers context against the defined catalog rules.

    1. Determines the best match.

    1. Retrieves the catalog associated with the matching catalog rule.


    The follow examples show how the best match might be resolved:


    - A shopper matches one of the `customer_ids` in one catalog rule only. The catalog for that catalog rule is displayed.

    - A shopper matches one of the `customer_ids` in one catalog rule only, but doesnʼt match any of the `tags` specified in that catalog rule. Because there are no other catalog rules for this `customer_id`, the catalog for the catalog rule is displayed because it is the best match.

    - A shopper is browsing a store using the stores mobile app, which matches `channel=mobile` in two catalog rules. The catalog displayed depends on matches with the `tags` or `customer_ids` attributes. If there is no other matching attribute, the first catalog rule found by the store is used. The best practice is to create catalog rules that cover all cases so that you avoid this situation.

    - An unknown shopper is browsing the only channel offered by the seller. The store displays the base catalog.

    '
paths:
  /catalogs/rules:
    post:
      tags:
      - Rules
      summary: Creates a new catalog rule
      description: 'If you have multiple catalogs, create catalog rule resources. With catalog rules, you can display different catalogs to different shoppers. For example, you can display a preferred pricing catalog to a few special customers. Or you can display one catalog to shoppers using your website and a different catalog to shoppers using your mobile app. Finally, you can define custom criteria by creating tags.


        :::note


        - If you have one catalog for all customers and channels, you can omit creating this resource.

        - Due to the way catalogs are cached in Commerce, using catalog rules to display catalogs sometimes causes a 5-minute time delay before the catalogs are displayed.

        - You cannot create catalog rules for organization catalogs.


        :::


        For ideas about the kinds of business scenarios you can achieve with catalog rules, see [Catalog Rules](/docs/api/pxm/catalog/rules). To understand how catalogs are matched to shoppers by using rules, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

        '
      operationId: createRule
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rule-create-data'
        description: Creates a catalog rule with the following attributes.
        required: true
      responses:
        '201':
          description: The created catalog rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
    get:
      tags:
      - Rules
      summary: Gets all authorized catalog rules
      description: "Retrieves all authorized catalog rules.\n\n### Filtering\n\nThis endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are supported.\n\n| Operator | Description | Supported Attributes | Example |\n|:--- |:--- |:--- |:--- |\n| `eq` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | `id`,`catalog_id`,`account_ids`,`customer_ids`,`channels`,`tags`,`pricebook_ids` | `filter=eq(id,some-id)` | \n| `in` | Checks if the values are included in the specified string. If they are, the condition is true. | `id`,`account_ids`,`customer_ids`,`channels`,`tags`,`pricebook_ids` | `filter=in(account_ids,some-id,another-id)` | \n"
      operationId: getRules
      parameters:
      - $ref: '#/components/parameters/filter-rule'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: The list of catalog rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule-list-data'
        default:
          description: An unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
  /catalogs/rules/{catalog_rule_id}:
    get:
      tags:
      - Rules
      summary: Get a catalog rule by ID
      operationId: getRuleByID
      parameters:
      - description: The catalog rule ID.
        name: catalog_rule_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The catalog rile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule-data'
        default:
          description: An unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
    put:
      tags:
      - Rules
      summary: Updates a catalog rule
      description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the catalog rule is not updated.
      operationId: updateRule
      parameters:
      - description: The catalog rule ID.
        name: catalog_rule_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rule-update-data'
        description: An updated catalog rule with the following attributes.
        required: true
      responses:
        '200':
          description: An Updated catalog rule with the following attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
    delete:
      tags:
      - Rules
      summary: Deletes a catalog rule
      operationId: deleteRuleByID
      parameters:
      - description: The catalog rule ID.
        name: catalog_rule_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: A 204 response indicates that the catalog rule has been deleted.
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
  /catalogs/rules/validate:
    post:
      tags:
      - Rules
      summary: Validate catalog rules for a given context
      description: 'Validates catalog rules for a given context and returns a list of matching catalog rules.

        '
      operationId: validateCatalogRules
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/catalog-rule-validator-request'
        required: true
      responses:
        '200':
          description: List of matching catalog rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule-list-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
components:
  schemas:
    page-meta:
      type: object
      description: Contains the results for the entire collection.
      title: PageMeta
      properties:
        results:
          description: Total number of results for the entire collection.
          type: object
          properties:
            total:
              description: Total number of results for the entire collection.
              type: integer
              format: int64
        page:
          type: object
          properties:
            limit:
              description: The maximum number of records for all pages.
              type: integer
              format: int64
            offset:
              description: The current offset by number of pages.
              type: integer
              format: int64
            current:
              description: The current number of pages.
              type: integer
              format: int64
            total:
              description: The total number of records for the entire collection.
              type: integer
              format: int64
    error-response:
      type: object
      title: ErrorResponse
      description: ErrorResponse is a json-api style Error response.
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          x-go-name: Errors
      x-go-name: ErrorResponse
    rule-create-data:
      type: object
      title: CatalogRuleCreateData
      description: A catalog rule specifies which catalog to use for a given shopper context.
      properties:
        data:
          type: object
          properties:
            attributes:
              type: object
              properties:
                name:
                  description: The name of a catalog rule. The name must not contain spaces.
                  type: string
                  minLength: 1
                  example: rule-123
                description:
                  description: A brief description of the purpose of a catalog rule.
                  type:
                  - string
                  - 'null'
                  example: Catalog Rule for most favored customers
                  default: ''
                account_ids:
                  description: The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                account_tag_ids:
                  description: The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                customer_ids:
                  description: The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                channels:
                  description: The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                tags:
                  description: A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                schedules:
                  description: "Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n"
                  type:
                  - array
                  - 'null'
                  items:
                    $ref: '#/components/schemas/rule-schedule'
                catalog_id:
                  type: string
                  description: The unique identifier of a catalog.
                  example: d09b4e16-08a5-4f42-817c-6e0d98acbb63
                pricebook_ids:
                  $ref: '#/components/schemas/prioritized-pricebooks'
              required:
              - name
              - catalog_id
            type:
              description: This represents the type of object being returned. Always `catalog_rule`.
              type: string
              example: catalog_rule
              enum:
              - catalog_rule
          required:
          - type
          - attributes
      required:
      - data
    rule:
      type: object
      title: Catalog Rule
      description: A catalog rule specifies which catalog to use for a given shopper context.
      properties:
        id:
          type: string
          description: The catalog rule ID. Use this to get, modify, or delete the catalog rule.
          example: 8dbb35b2-ef04-477e-974d-e5f3abe6faae
        attributes:
          type: object
          properties:
            name:
              description: The name of a catalog rule. The name must not contain any spaces.
              type: string
              example: rule-123
            description:
              description: A brief description of the purpose of a catalog rule.
              type: string
              example: Catalog Rule for most favored customers
              default: ''
              x-omitempty: true
            account_ids:
              description: The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.
              type: array
              items:
                type: string
              x-omitempty: true
            account_tag_ids:
              description: The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.
              type: array
              items:
                type: string
              x-omitempty: true
            customer_ids:
              description: The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.
              type: array
              items:
                type: string
              x-omitempty: true
            channels:
              description: The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.
              type: array
              items:
                type: string
              x-omitempty: true
            tags:
              description: A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.
              type: array
              items:
                type: string
              x-omitempty: true
            schedules:
              description: "Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n"
              type: array
              items:
                $ref: '#/components/schemas/rule-schedule'
              x-omitempty: true
            catalog_id:
              type: string
              description: The unique identifier of a catalog.
              example: d09b4e16-08a5-4f42-817c-6e0d98acbb63
            created_at:
              description: The date and time a catalog rule was created.
              type: string
              example: '2020-09-22T09:00:00'
              format: date-time
            updated_at:
              description: The date and time a catalog release is updated.
              type: string
              example: '2020-09-22T09:00:00'
              format: date-time
            pricebook_ids:
              $ref: '#/components/schemas/prioritized-pricebooks'
          required:
          - name
          - catalog_id
          - created_at
          - updated_at
        type:
          description: This represents the type of object being returned. Always `catalog_rule`.
          type: string
          example: catalog_rule
          enum:
          - catalog_rule
        meta:
          $ref: '#/components/schemas/rule-meta'
      required:
      - id
      - type
      - attributes
    rule-meta:
      type: object
      title: ruleMeta
      description: A rule's metadata.
      properties:
        similarity_score:
          description: "Indicates the similarity score of the rule to the supplied validation request. \nThe score is calculated based on matching criteria:\n- **Name match**: 100 points (exact match)\n- **Account IDs**: 5 points per matching account\n- **Customer IDs**: 5 points per matching customer  \n- **Channels**: 5 points per matching channel\n- **Tags**: 5 points per matching tag\n- **Catalog ID**: 3 points (exact match)\n- **Pricebook IDs**: 2 points per matching pricebook\n- **Schedules**: 2 points per overlapping schedule\n\nHigher scores indicate greater similarity. Rules are sorted by similarity score in descending order.\n"
          type:
          - integer
          - 'null'
          example: 100
          x-go-name: SimilarityScore
          x-omitempty: true
        active:
          description: will the rule be active at the supplied match date/time?
          type: boolean
          example: false
          default: false
          x-go-name: Active
        resolved_for_shopper:
          description: Indicates whether this rule will be the one resolved for a shopper viewing the catalog at the supplied match date/time
          type: boolean
          example: true
          default: false
        release_id:
          type:
          - string
          - 'null'
          description: The unique identifier of the published release of the catalog for the rule
          x-omitempty: true
      x-go-name: ruleMeta
      x-omitempty: true
    rule-data:
      type: object
      title: CatalogRuleData
      description: Container for a single catalog rule.
      properties:
        data:
          $ref: '#/components/schemas/rule'
        links:
          $ref: '#/components/schemas/links'
      required:
      - data
    rule-schedule:
      type: object
      title: Catalog Schedule
      description: A period of time during which a catalog is valid
      properties:
        valid_from:
          description: Matches the date and time that the catalog is displayed from.
          type:
          - string
          - 'null'
          example: '2020-09-22T09:00:00'
          format: date-time
          x-go-name: ValidFrom
        valid_to:
          description: Matches the date and time the catalog is displayed to.
          type:
          - string
          - 'null'
          example: '2020-09-22T09:00:00'
          format: date-time
          x-go-name: ValidTo
      x-go-name: RuleSchedule
    rule-list-data:
      type: object
      title: CatalogRuleListData
      description: Container for a list of catalog rules.
      properties:
        meta:
          $ref: '#/components/schemas/page-meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/rule'
        links:
          $ref: '#/components/schemas/links'
      required:
      - data
    prioritized-pricebooks:
      description: If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.
      type: array
      maxItems: 5
      items:
        type: object
        properties:
          id:
            description: A unique identifier of a price book.
            type: string
            format: uuid
          priority:
            description: Priority is a number and the price book with the highest number has the highest priority.
            type: integer
        required:
        - priority
        - id
        x-go-name: PrioritizedPricebook
    catalog-rule-validator-request:
      type: object
      properties:
        data:
          type: object
          required:
          - match_type
          properties:
            match_type:
              type: string
              enum:
              - filter
              - similarity
              - conflict
              - resolve_for_shopper
              description: "The type of matching operation to perform on catalog rules:\n\n- **filter**: Advanced rule filtering with AND logic. Returns rules that match ALL specified criteria.\n\n- **similarity**: Finds rules similar to the supplied rule using OR logic. Returns rules sorted by similarity score (highest first) with metadata indicating:\n  - Similarity score based on matching criteria (name: 100pts, account/customer/channel/tags: 5pts each, catalog: 3pts, pricebooks: 2pts, schedules: 2pts)  \n  - Whether the rule is active at the supplied match_date\n  - Whether the rule would be resolved for a shopper context\n\n- **conflict**: Checks for conflicts between the supplied rule and existing rules. Returns rules that would conflict if the new rule were created.\n\n- **resolve_for_shopper**: Determines the exact catalog rule that would be applied for a given shopper context. Returns the single most specific matching rule or defaults to \"Default Catalog Resolution\".\n"
            channels:
              description: The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.
              type:
              - array
              - 'null'
              items:
                type: string
            tags:
              description: A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.
              type:
              - array
              - 'null'
              items:
                type: string
            account_ids:
              type:
              - array
              - 'null'
              items:
                type: string
              description: List of account IDs.
            account_tag_ids:
              type:
              - array
              - 'null'
              items:
                type: string
              description: List of account tag UUIDs.
            customer_ids:
              type:
              - array
              - 'null'
              items:
                type: string
              description: List of customer IDs.
            pricebook_ids:
              type:
              - array
              - 'null'
              items:
                type: string
              description: List of pricebook IDs.
            schedules:
              type:
              - array
              - 'null'
              items:
                type: object
                properties:
                  valid_from:
                    type: string
                    format: date-time
                  valid_to:
                    type: string
                    format: date-time
            name:
              type:
              - string
              - 'null'
              description: The name of the catalog rule.
            catalog_id:
              type:
              - string
              - 'null'
              description: The id of the catalog to match against.
            match_date:
              type:
              - string
              - 'null'
              format: date-time
              description: The date to match against the schedules.
    links:
      description: Links allow you to move between requests.
      type: object
      properties:
        self:
          description: Single entities use a `self` parameter with a link the specific resource.
          type:
          - string
          - 'null'
          format: uri
        first:
          description: Always the first page.
          type:
          - string
          - 'null'
          format: uri
        last:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
        prev:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
        next:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
    error:
      type: object
      title: APIError
      description: APIError is a json-api style part of an error response.
      properties:
        detail:
          type: string
          example: not processable
          x-go-name: Detail
        status:
          type: string
          example: '422'
          x-go-name: Status
        title:
          type: string
          example: There was a problem processing your request.
          x-go-name: Title
      x-go-name: APIError
    rule-update-data:
      type: object
      title: CatalogRuleUpdateData
      description: A catalog rule specifies which catalog to use for a given shopper context.
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: The catalog rule ID. Use this to get, modify, or delete the catalog rule.
              example: 8dbb35b2-ef04-477e-974d-e5f3abe6faae
            attributes:
              type: object
              properties:
                name:
                  description: The name of a catalog rule. The name must not contain spaces.
                  type:
                  - string
                  - 'null'
       

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-rules-api-openapi.yml