Modification

Schema, including its fields, nested structure, and relationships

Definition

A Modification represents the individual content changes or scripts applied to a webpage as part of a variation. For example, a modification could be a JavaScript snippet that changes the text of a button, or a CSS rule that hides an element. Modifications are always associated with a parent variation.

Parent Relationship

• Parent Resource Type: Variation

• Parent Identifier Field: $_parent_id

• Rule: The parent variation must already exist. When creating a new modification, you reference the parent Variation by its ID using the special field $_parent_id. (In other words, include $_parent_id: <variation_id> in the modification payload to nest it under the given variation.) The modification can also be created in a “standalone” mode by specifying a campaign_id if needed (see below).

Payload Properties

When creating or updating a Modification, the payload accepts the following fields:

• id (Integer, optional) – The modification’s unique ID. This is required only when updating an existing modification (not needed for creation). Example: 100000 (an existing modification ID).

• campaign_id (Integer, optional) – The ID of a campaign to apply this modification to, required only if the modification is standalone (i.e. not nested under a variation). In most cases modifications are created under a specific variation, so this field is not used. If used, the campaign with this ID must exist, and the modification will be applied to all visitors of that campaign (this is an advanced scenario). Example: 200000.

• name (String, required) – A human-readable name for the modification. This is typically just an internal label (e.g. "NewBanner"). Example: "NewBanner".

• type (String, required) – The type of modification, indicating what kind of code is provided. Allowed values are "js" for JavaScript or "css" for CSS. This lets the API know how to execute the code. Example: "js".

• selector (String, required) – A CSS selector that targets the element(s) on the page that the modification will affect. For example, if the modification is meant to change a specific button, the selector should point to that button element in the DOM. Example: "#main" (targets an element with id="main").

• code (String, required) – The actual code to run or the CSS styles to apply for this modification. If the type is "js", this field contains a JavaScript snippet as a string. If the type is "css", this contains CSS rules. Example: "console.log('Hello world!');" for a JS modification (which simply logs a message to the console).

Example Modification Payload: Creating a new JS modification named "modification_name" that logs a message to the console, targeting an element with id "main":

{
  "name": "modification_name",
  "type": "js",
  "campaign_id": 100000,
  "selector": "#main",
  "code": "console.log('hello world!')"
}

(In the above example, the modification is created in a standalone way for campaign ID 100000. Typically, you would provide $_parent_id instead to nest it under a specific variation.)

Response Fields

When a Modification resource is returned (for example, after creation or when fetching it), it includes the following fields:

• id (Integer) – The unique ID of the modification.

• name (String) – The modification name.

• code (String) – The code content of the modification (the same code that was provided in the payload).

• selector (String) – The CSS selector identifying where the modification applies on the page.

• type (String) – The modification type ("js" or "css").

• updated_at (Object) – An object containing the timestamp of the last update to this modification. It typically includes:

  • readable_date – A timestamp in ISO8601 format (e.g. "2025-06-18T09:50:20+0000").

  • timestamp – The same time as a Unix timestamp (seconds since epoch).

  • pattern – The date format pattern used (for reference, e.g. "Y-m-d\\\\TH:i:sO").

• updated_by (Object) – Details of the user who last updated the modification. This includes:

  • id – The user’s ID.

  • email – The user’s email address who made the change.

• variation_id (Integer) – The ID of the parent variation that this modification belongs to. (This links the modification back to its variation.)

Example Modification Response:

{
  "id": 5819981,
  "name": "name",
  "code": "value",
  "selector": "#main",
  "type": "js",
  "updated_at": {
    "readable_date": "2025-06-18T09:50:20+0000",
    "timestamp": 1750240220,
    "pattern": "Y-m-d\\\\TH:i:sO"
  },
  "updated_by": {
    "id": 84689,
    "email": "[email protected]"
  },
  "variation_id": 1440570
}

(The above is an example of a modification object returned by the API, showing the structure with metadata like updated_at and updated_by. In this example, the modification id is 5819981 and it belongs to variation 1440570.)

Error Codes

The following error codes may be returned related to modifications (for example, if something goes wrong during creation or update):

• InvalidPayload – A required field is missing or has an invalid value/type. For instance, this occurs if a required property like name or code is not provided.

• ParentNotFound – The referenced parent ID does not exist. This error happens if the given $_parent_id (variation) or campaign_id does not match an existing resource.

• PermissionDenied – The user does not have permission to perform this action. The user’s role or scope may not allow creating or editing modifications.

• DuplicateRef – A duplicate reference was found. This can occur if another modification with the same identifier or name exists when uniqueness is required.

• InvalidDependency – A dependent resource is missing. For example, this could occur if you attempt to create a modification with a campaign_id for a campaign that doesn’t exist (the relationship between modification and