Rules and Rewrites API

​

When to use this API

• Automate rule deployment: Create and update rules and rewrites through CI/CD (continuous integration/continuous deployment) pipelines or automated workflows.
• Synchronize across environments: Maintain consistent rules and rewrites across development, QA (quality assurance), and production environments.
• Manage rules at scale: Efficiently handle large rule sets that are impractical to manage through the UI (user interface) alone.
• Fallback with version control: Fetch rules and rewrites, then commit them to your source control repository at intervals so you can easily revert to earlier versions if needed.
• Integrate with AI agents: Use AI to automate creation and updates of rules and rewrites.

​

Key concepts

​

Rule and rewrite identifiers

• id: Automatically generated UUID (Universally Unique Identifier) assigned by the platform when you create a rule or rewrite. This identifier is unique within the Commerce Studio instance.
• externalId: Optional user-defined identifier that you can assign when creating a rule or rewrite. This field enables you to maintain your own naming conventions and synchronize rules across multiple environments.

​

Authentication scopes

• commercestudio.rules: Required for rule operations (create, read, update, delete rules)
• commercestudio.rewrites: Required for query rewrite operations (create, read, update, delete rewrites)
• commercestudio.bulkoperations: Required for bulk operations (publish, unpublish, edit, delete, and migrate operations on multiple rules)

​

Rate limiting

​

Use the Rules and Rewrites API

curl --request POST \
  --url 'https://identity.lucidworks.com/oauth2/ausao8uveaPmyhv0v357/v1/token?scope=API_SCOPE&grant_type=client_credentials' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic [CLIENT_ID:CLIENT_SECRET_BASE64]' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/x-www-form-urlencoded'

echo -n "CLIENT_ID:CLIENT_SECRET" | base64

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR_ACCESS_TOKEN",
  "scope": "commercestudio.rules"
}

curl --request GET \
  --url 'https://{COMMERCE_STUDIO_ID}.experiencemanager.lucidworks.com/em-rules' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​

Bulk operations

• Publishing or unpublishing large sets of rules at once
• Applying consistent edits across multiple rules
• Deleting obsolete rules in batches
• Migrating rule sets between Commerce Studio instances

​

Supported bulk operations

• publishRule: Make multiple rules active simultaneously.
• unpublishRule: Deactivate multiple rules at once.
• editRule: Apply the same updates to multiple rules.
• deleteRule: Remove multiple rules in one operation.
• migrateRule: Copy rules to another Commerce Studio instance.

​

Example requests

{
  "type": "publishRule",
  "specification": {
    "tags": ["holiday-2026"],
    "publishState": "DRAFT"
  }
}

{
  "type": "unpublishRule",
  "ruleIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ]
}

{
  "type": "editRule",
  "specification": {
    "tags": ["holiday-2026"]
  },
  "patch": {
    "precedence": 5
  },
  "stageChanges": false
}

{
  "type": "deleteRule",
  "specification": {
    "publishState": "DRAFT",
    "lastModifiedEnd": "2026-01-01T00:00:00Z"
  },
  "excludeRuleIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

{
  "type": "migrateRule",
  "ruleExternalIds": [
    "promo-summer-2026"
  ],
  "targetExperienceManagerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "published": true
}

​

How bulk operations work

​

Best practices

• Start with small batches: Test bulk operations on a small set of rules before scaling up.
• Monitor operation status: Don’t assume success—always check the final status and handle partial failures.
• Handle errors gracefully: When operations complete with errors, review which rules failed and retry them individually if needed.
• Avoid modifying locked rules: Check the pendingInBulkOperation flag before attempting to update rules.
• Use external IDs for stability: External IDs make it easier to retry operations and maintain consistency across environments.