---
title: "Create or replace variations"
method: PUT
path: "/v2/variations"
tags: ["Variations"]
---

# Create or replace variations

`PUT /v2/variations`

## Request

- Base URL: `https://ac.cnstrc.com`
- URL: `https://ac.cnstrc.com/v2/variations`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `catalog(w)`, `search_suggestions(w)`.

Create item variations or replace the data of existing item variations. Returns an identifier for a background [task](/reference/v1-tasks-retrieve-task).

## Query parameters

- `key` string, required: The key of the index to use.
- `section` string: The section of the index to use. Defaults to `Products`.
- `c` string: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
- `force` boolean: A flag to process the catalog even if it will invalidate a large part of existing data. Defaults to `False`.
- `notification_email` string[]: The email address(es) to send a notification to if the task fails. Multiple addresses may be specified for multiple recipients.

## Request body

- VariationListPutRequestBody
  - `variations` Variation[], required: Array of variations you want to create or replace.
    - `id` string, required: The ID of the variation, must be unique.
    - `item_id` string, required: The ID of the item this variation is attached to.
    - `name` string: The name of the variation, as it will appear in the results. Must contain at least one alphanumeric character.
    - `suggested_score` integer: A number that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
    - `data` VariationMetadata: Additional data about item. In addition to the listed properties you can also provide any other information you want to associate with that item. No special validation is made for that data.
      - `keywords` string[]: An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself.
      - `url` string: A URL to directly send the user after selecting the item. Might be required in some cases. Please contact support@constructor.io if you have questions around that.
      - `image_url` string: A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied).
      - `facets` Facets
      - `group_ids` string[]: You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io group_ids can be used as filters in search, autosuggest, and browse requests.
      - `description` string: A description for this item. The maximum length of this field is 4000 characters.
      - `active` boolean
      - `is_default` boolean: Whether this variation should always be returned as the best matching variation.
      - `__cnstrc_release_time` union: Date and time of item's release, useful to hide items from search results until its official release.
        - string, date-time
        - integer
        - number
      - `__cnstrc_expiration_time` union: Date and time of item's expiration, useful to hide items from search results at and after a scheduled time.
        - string, date-time
        - integer
        - number

## Response `200`

OK

- VariationListPutResponse
  - `task_id` integer, required
  - `task_status_path` string, required

## Other responses

- `202`: Accepted
- `400`: Validation Error
- `401`: Credentials are not passed or action is forbidden.
- `403`: The supplied token does not have the required permissions.
- `409`: Conflict
- `429`: Rate limit breached

---

[API](https://skmtc.dev/constructor/apis/catalog-management.md) - [All operations](https://skmtc.dev/constructor/apis/catalog-management/llms.txt) - [OpenAPI document](https://skmtc.dev/constructor/apis/catalog-management/revisions/3a9833796fc6?raw)