# Add or update item asynchronously

- Operation ID: `addItemAsync`
- HTTP method: `POST`
- Path: `/catalogs/v1/async/bags/{catalogId}/item`
- [Human-readable API reference](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addItemAsync)

## Self-contained OpenAPI method

The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.

```yaml
openapi: 3.0.0
info:
  title: Synerise Public API
  version: 1.9.1
paths:
  /catalogs/v1/async/bags/{catalogId}/item:
    post:
      tags:
        - Catalogs
      summary: Add or update item asynchronously
      description: |
        Add a single item asynchronously to the catalog. If the item already exists, it's entirely overwritten by the item you send.

        Asynchronous requests are processed according to the time they reach the service.  
        This means that requests to synchronous endpoints (for example, [`/bags/{catalogId}/items/{itemId}`](#operation/updateItem) may overwrite asynchronous operations which were sent earlier and queued due to high traffic.  
        This behavior also applies to requests from Automation and AI feed synchronization, which use the asynchronous mechanism.

        The request body can't exceed 256KB.


        ---

        **API consumers:** <a href="/api-reference/authorization?tag=Authorization&amp;operationId=userLogin" target="_blank" rel="noopener">Synerise User</a>, <a href="/api-reference/authorization?tag=Authorization&amp;operationId=profileLogin" target="_blank" rel="noopener">Workspace (Business Profile)</a>

        **API key permissions required (at least one):** `CATALOGS_ITEM_BATCH_CREATE`, `CATALOGS_ITEM_BATCH_CATALOG_CREATE`

        **User role permission required:** `assets_catalogs: create`
      operationId: addItemAsync
      security:
        - JWT: []
      parameters:
        - in: path
          name: catalogId
          description: ID of the catalog
          required: true
          schema:
            type: integer
      requestBody:
        description: JSON object with any number of key/value pairs
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - itemKey
                - value
              properties:
                itemKey:
                  type: string
                  description: |
                    The value of the unique key of the item.

                    Slashes (`/`) are not allowed in the value.

                    In the Synerise Portal, this value is saved under **Primary key**.
                  example: sku1357
                value:
                  type: object
                  description: Properties of the item. Can be an empty object.
                  additionalProperties:
                    type: string
                    description: Key:value data
                  example:
                    itemCategory: smartphone
                    itemColor: blue
      responses:
        "204":
          description: Operation added to queue
      x-snr-doc-urls:
        - /api-reference/data-management#tag/Catalogs/operation/addItemAsync
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl --request POST \
              --url https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/item \
              --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
              --header 'content-type: application/json' \
              --data '{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}'
        - lang: Python
          label: Python
          source: |-
            import http.client

            conn = http.client.HTTPSConnection("api.synerise.com")

            payload = "{\"itemKey\":\"sku1357\",\"value\":{\"itemCategory\":\"smartphone\",\"itemColor\":\"blue\"}}"

            headers = {
                'Authorization': "Bearer REPLACE_BEARER_TOKEN",
                'content-type': "application/json"
                }

            conn.request("POST", "/catalogs/v1/async/bags/%7BcatalogId%7D/item", payload, headers)

            res = conn.getresponse()
            data = res.read()

            print(data.decode("utf-8"))
        - lang: JavaScript
          label: JavaScript
          source: |-
            const data = JSON.stringify({
              "itemKey": "sku1357",
              "value": {
                "itemCategory": "smartphone",
                "itemColor": "blue"
              }
            });

            const xhr = new XMLHttpRequest();
            xhr.withCredentials = true;

            xhr.addEventListener("readystatechange", function () {
              if (this.readyState === this.DONE) {
                console.log(this.responseText);
              }
            });

            xhr.open("POST", "https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/item");
            xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
            xhr.setRequestHeader("content-type", "application/json");

            xhr.send(data);
        - lang: Node.js
          label: Node.js
          source: |-
            const http = require("https");

            const options = {
              "method": "POST",
              "hostname": "api.synerise.com",
              "port": null,
              "path": "/catalogs/v1/async/bags/%7BcatalogId%7D/item",
              "headers": {
                "Authorization": "Bearer REPLACE_BEARER_TOKEN",
                "content-type": "application/json"
              }
            };

            const req = http.request(options, function (res) {
              const chunks = [];

              res.on("data", function (chunk) {
                chunks.push(chunk);
              });

              res.on("end", function () {
                const body = Buffer.concat(chunks);
                console.log(body.toString());
              });
            });

            req.write(JSON.stringify({itemKey: 'sku1357', value: {itemCategory: 'smartphone', itemColor: 'blue'}}));
            req.end();
        - lang: PHP
          label: PHP
          source: |-
            <?php

            $request = new HttpRequest();
            $request->setUrl('https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/item');
            $request->setMethod(HTTP_METH_POST);

            $request->setHeaders([
              'Authorization' => 'Bearer REPLACE_BEARER_TOKEN',
              'content-type' => 'application/json'
            ]);

            $request->setBody('{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}');

            try {
              $response = $request->send();

              echo $response->getBody();
            } catch (HttpException $ex) {
              echo $ex;
            }
        - lang: Java
          label: Java
          source: |-
            HttpResponse<String> response = Unirest.post("https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/item")
              .header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
              .header("content-type", "application/json")
              .body("{\"itemKey\":\"sku1357\",\"value\":{\"itemCategory\":\"smartphone\",\"itemColor\":\"blue\"}}")
              .asString();
servers:
  - description: Microsoft Azure EU
    url: https://api.synerise.com
  - description: Microsoft Azure USA
    url: https://api.azu.synerise.com
  - description: Google Cloud Platform
    url: https://api.geb.synerise.com
tags:
  - name: Catalogs
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      description: |-
        JWT Bearer token. The header looks like this: `Bearer {JWT}`

        Remember to include the space between 'Bearer' and the token.

        Generate a token via the **Authorization** endpoints.
```