Skip to content

Товары

API бэк-офиса создаёт и меняет товары магазина. Запрос идёт на https://SHOP/admin/...json, авторизация — HTTP Basic, логин и пароль приложения. Правила лимита и Content-Type — в общем описании. Сверка списков по updated_since и from_id — в изменившихся данных.

В запросе логин и пароль — API_KEY и API_PASSWORD. Путь без адреса магазина: его подставляют перед /admin.

Список

GET /admin/products.json отдаёт массив товаров. GET /admin/products/count.json отдаёт число записей в том же отборе.

per_page меньше 10 поднимается до 10. Вторая страница читается параметром page.

GET/admin/products/count.json
Параметр Описание
per_page необязательный
число		 Размер страницы того же отбора. Значение меньше 10 поднимается до 10.
page необязательный
число		 Номер страницы того же отбора.
filter[title] необязательный
строка		 Поиск по названию в том же отборе.
deleted необязательный
строка		 true — только архив.
with_deleted необязательный
строка		 true — текущие и архивные. 
GET /admin/products/count.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

{"count": 37}

Поиск по названию — filter[title]. Ниже первый товар из такой выборки.

GET/admin/products.json?per_page=10&filter[title]=iPhone
Параметр Описание
per_page необязательный
число		 Размер страницы. Значение меньше 10 поднимается до 10.
page необязательный
число		 Номер страницы.
filter[title] необязательный
строка		 Часть названия. 
GET /admin/products.json?per_page=10&filter[title]=iPhone
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 673,
    "title": "Apple iPhone 16 Pro Max 1 ТБ",
    "permalink": "apple-iphone-16-pro-max-1-tb"
  }
]

Несколько товаров по id читаются через product_ids. В одном запросе метод принимает до 100 id.

GET/admin/products/by_ids.json?product_ids=561,569
Параметр Описание
product_ids обязательный
строка		 id товаров через запятую, не больше 100. 
GET /admin/products/by_ids.json?product_ids=561,569
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {"id": 561, "title": "товар 1"},
  {"id": 569, "title": "товар 2"}
]

GET /admin/products/999999999.json отвечает 404. Тело при заголовке Accept: application/json остаётся HTML-страницей.

Скрытый товар (is_hidden: true) в этот список входит. Удалённый в архив — нет, пока не передан deleted или with_deleted, см. ниже.

Создание

Минимальное тело — название и один вариант с ценой. Адрес товара (permalink) строится из названия. Описание сохраняется как переданный HTML.

POST/admin/products.json
Параметр Описание
product[title] обязательный
строка		 Название. Из него строится permalink.
product[description] необязательный
строка		 Описание, сохраняется как переданный HTML.
product[short_description] необязательный
строка		 Короткое описание.
product[variants_attributes][][price] обязательный
число		 Цена первого варианта.
product[variants_attributes][][sku] необязательный
строка		 Артикул варианта.
product[variants_attributes][][barcode] необязательный
строка		 Штрихкод варианта.
product[variants_attributes][][quantity] необязательный
число		 Остаток варианта. 
POST /admin/products.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "title": "docs-api-простой",
    "description": "<p>Короткое описание для примера</p>",
    "short_description": "Коротко",
    "variants_attributes": [
      {
        "price": 1500,
        "sku": "DOCS-SIMPLE",
        "barcode": "4600000000017",
        "quantity": 3
      }
    ]
  }
}

Ответ · 201

{
  "id": 913,
  "title": "docs-api-простой",
  "permalink": "docs-api-prostoy",
  "is_hidden": false,
  "archived": false,
  "category_id": 1,
  "collections_ids": [],
  "description": "<p>Короткое описание для примера</p>",
  "short_description": "Коротко",
  "variants": [
    {
      "id": 2176487279,
      "sku": "DOCS-SIMPLE",
      "barcode": "4600000000017",
      "price": "1500.0",
      "quantity": 3,
      "quantity_at_warehouse0": "3.0"
    }
  ]
}

category_id в ответе — категория учёта. Если её не передать, магазин подставляет категорию сам. Идентификатор коллекции витрины в это поле не встаёт: такой запрос отвечает 422 и {"category_id":["Категория удалена или отсутствует."]}. Коллекция назначается отдельным запросом ниже.

Запись без Content-Type: application/json отвечает 422:

{"message": "incorrect Content-Type, should be application/json"}

Коллекция

Запись в коллекцию — POST /admin/collects.json. В collections_ids карточки попадает и родительская коллекция: привязка к дочерней добавляет её id и id родителя.

Позиция этой записи — ручной порядок товара в коллекции.

POST/admin/collects.json
Параметр Описание
collect[product_id] обязательный
число		 id товара.
collect[collection_id] обязательный
число		 id коллекции.
collect[position] необязательный
число		 Порядок товара в коллекции. 
POST /admin/collects.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collect": {
    "product_id": 913,
    "collection_id": 53486014,
    "position": 1
  }
}

Ответ · 201

{
  "id": 11029225261,
  "collection_id": 53486014,
  "product_id": 913,
  "position": 1
}
PUT/admin/collects/11029225261.json
Параметр Описание
collect[position] обязательный
число		 Новый порядок товара в коллекции. 
PUT /admin/collects/11029225261.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "collect": {
    "position": 5
  }
}

Ответ · 200

{
  "id": 11029225261,
  "collection_id": 53486014,
  "product_id": 913,
  "position": 5
}

Скрытие

is_hidden: true убирает товар с витрины и оставляет его в GET /admin/products.json.

PUT/admin/products/913.json
Параметр Описание
product[is_hidden] обязательный
логический		 true убирает товар с витрины и оставляет его в списке. false возвращает на витрину. 
PUT /admin/products/913.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "is_hidden": true
  }
}

Ответ · 200

{
  "id": 913,
  "title": "docs-api-простой",
  "is_hidden": true,
  "archived": false
}

Обратное включение — тот же запрос с "is_hidden": false.

Удаление и архив

DELETE /admin/products/:id.json переносит товар в архив. Тело ответа — {"status":"ok"}. После этого GET этой карточки отвечает 404 с HTML-страницей. Тот же DELETE для id, которого нет, тоже отвечает 200 и {"status":"ok"}: по коду удаления нельзя понять, был ли товар.

Обычный список архивный товар не содержит. deleted=true отдаёт только архив, у записи archived: true. with_deleted=true отдаёт и текущие, и архивные. Ниже одна запись из списка deleted=true.

GET/admin/products.json?deleted=true&per_page=250
Параметр Описание
deleted необязательный
строка		 true отдаёт только архив, у записи archived true.
with_deleted необязательный
строка		 true отдаёт текущие и архивные.
per_page необязательный
число		 Размер страницы. 
GET /admin/products.json?deleted=true&per_page=250
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[
  {
    "id": 977,
    "title": "docs-api-архив",
    "archived": true
  }
]

Вернуть товар из архива — POST /admin/products/:id/recover.json. У этого POST обязателен Content-Type: application/json, даже если тело пустое: без заголовка ответ 422 с тем же incorrect Content-Type. В теле ответа восстановления поле archived может остаться true. Актуальное значение читается следующим GET /admin/products/:id.json.

POST/admin/products/993/recover.json
Параметр Описание
id обязательный
число		 id архивного товара в пути. 
POST /admin/products/993/recover.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{}

Ответ · 200

{
  "id": 993,
  "title": "docs-api-recover",
  "archived": true
}

Дополнительное поле товара

Пустой product_field_values в карточке значит, что значений нет. Поле создаётся отдельно: в type передаётся ProductField::TextField.

Значение пишется в товар через product_field_values_attributes и возвращается в GET карточки.

POST/admin/product_fields.json
Параметр Описание
product_field[title] обязательный
строка		 Название поля.
product_field[handle] необязательный
строка		 Системное имя.
product_field[type] обязательный
строка		 Тип поля. Для текста — ProductField::TextField. 
POST /admin/product_fields.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product_field": {
    "title": "docs-api Комментарий",
    "handle": "docs_api_comment",
    "type": "ProductField::TextField"
  }
}

Ответ · 201

{
  "id": 4586434,
  "handle": "docs_api_comment",
  "type": "ProductField::TextField",
  "title": "docs-api Комментарий"
}
PUT/admin/products/985.json
Параметр Описание
product[product_field_values_attributes][][product_field_id] обязательный
число		 id дополнительного поля.
product[product_field_values_attributes][][value] обязательный
строка		 Значение поля. Пустой product_field_values в карточке значит, что значений нет. 
PUT /admin/products/985.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "product_field_values_attributes": [
      {
        "product_field_id": 4586434,
        "value": "пример"
      }
    ]
  }
}

Ответ · 200

{
  "id": 985,
  "product_field_values": [
    {"id": 895989818, "product_field_id": 4586434, "value": "пример"}
  ]
}

Параметры

Параметр карточки описывает товар целиком: материал, состав, длина. В API это свойство property и значение characteristic. При создании и обновлении товара пара передаётся названием в properties_attributes.

Размер и цвет задаются свойствами варианта, раздел «Варианты». Гравировка и подарочная упаковка — опция покупки, раздел «Опция покупки»: у значения своя цена.

Параметры товара читаются из GET /admin/products/:id.json. Названия свойств лежат в properties, значения — в characteristics. Пара связывается по property_id: у значения тот же property_id, что id у свойства. Название значения — поле title.

Запись по названиям

Свойство и значение создаются, если таких названий в магазине ещё нет. Одинаковый title в нескольких элементах properties_attributes — одно свойство с несколькими значениями. В примере ниже «Состав» передан дважды, с разными value. В ответе свойство одно, значения два, у обоих один и тот же property_id.

POST/admin/products.json
Параметр Описание
product[title] обязательный
строка		 Название товара.
product[variants_attributes][][price] обязательный
число		 Цена варианта.
product[properties_attributes][][title] обязательный
строка		 Название параметра. Повтор названия добавляет ещё одно значение.
product[properties_attributes][][value] обязательный
строка		 Значение параметра. 
POST /admin/products.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "title": "docs-api-параметры",
    "variants_attributes": [
      {
        "price": 500,
        "sku": "DOCS-PROP"
      }
    ],
    "properties_attributes": [
      {
        "title": "docs-api Материал",
        "value": "Хлопок"
      },
      {
        "title": "docs-api Состав",
        "value": "90% хлопок"
      },
      {
        "title": "docs-api Состав",
        "value": "10% эластан"
      }
    ]
  }
}

Ответ · 201

{
  "id": 929,
  "title": "docs-api-параметры",
  "properties": [
    {"id": 61541236, "title": "docs-api Материал", "permalink": "docs-api-material"},
    {"id": 61541237, "title": "docs-api Состав", "permalink": "docs-api-sostav"}
  ],
  "characteristics": [
    {"id": 785, "property_id": 61541236, "title": "Хлопок", "permalink": "hlopok"},
    {"id": 793, "property_id": 61541237, "title": "90% хлопок", "permalink": "90-hlopok"},
    {"id": 801, "property_id": 61541237, "title": "10% эластан", "permalink": "10-elastan"}
  ]
}

Полный список при обновлении

properties_attributes заменяет весь набор пар товара. Пары, которых нет в теле, отвязываются. В примере ниже в теле одна пара «Материал / Лён»: состав из карточки уходит, у материала записывается новое значение.

Чтобы добавить параметр и сохранить старые, в тело нужно положить и старые пары, и новую.

PUT/admin/products/929.json
Параметр Описание
product[properties_attributes][][title] обязательный
строка		 Название параметра. В товар уходит полный список, а не одна добавленная пара.
product[properties_attributes][][value] обязательный
строка		 Значение параметра. 
PUT /admin/products/929.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "properties_attributes": [
      {
        "title": "docs-api Материал",
        "value": "Лён"
      }
    ]
  }
}

Ответ · 200

{
  "id": 929,
  "properties": [
    {"id": 61541236, "title": "docs-api Материал"}
  ],
  "characteristics": [
    {"id": 809, "property_id": 61541236, "title": "Лён", "permalink": "lyon"}
  ]
}

Поля запроса без properties_attributes список пар не меняют. Его заменяет только само поле properties_attributes.

Одна пара по id

product_characteristics_attributes добавляет одну пару по property_id и characteristic_id. Уже привязанные пары остаются.

PUT/admin/products/929.json
Параметр Описание
product[product_characteristics_attributes][][property_id] обязательный
число		 id параметра.
product[product_characteristics_attributes][][characteristic_id] обязательный
число		 id значения. 
PUT /admin/products/929.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "product_characteristics_attributes": [
      {
        "property_id": 61541238,
        "characteristic_id": 817
      }
    ]
  }
}

Ответ · 200

{
  "characteristics": [
    {"id": 785, "property_id": 61541236, "title": "Хлопок"},
    {"id": 793, "property_id": 61541237, "title": "90% хлопок"},
    {"id": 817, "property_id": 61541238, "title": "12.5"}
  ]
}

В characteristics приходит id значения, а не id связи. Убрать пару — записать полный properties_attributes без неё.

Числовой параметр

Свойство с "is_numeric": true создаётся отдельным запросом. В ответе создания и в GET /admin/properties/:id.json поля is_numeric нет. Числовой режим виден по значениям.

Значение числового параметра хранится числом: 12.5 см сохраняется как 12.5. Текст, который не является числом, например 40 см, отвечает 422 и {"title":["Указано не число"]}. Число 40 принимается.

POST/admin/properties.json
Параметр Описание
property[title] обязательный
строка		 Название параметра.
property[is_numeric] необязательный
логический		 true делает параметр числовым. 
POST /admin/properties.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "property": {
    "title": "docs-api Ширина",
    "is_numeric": true
  }
}

Ответ · 201

{
  "id": 61541239,
  "title": "docs-api Ширина",
  "permalink": "docs-api-shirina",
  "position": 34,
  "is_hidden": false,
  "is_navigational": true
}
POST/admin/properties/61541239/characteristics.json
Параметр Описание
characteristic[title] обязательный
строка		 Название значения. 
POST /admin/properties/61541239/characteristics.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "characteristic": {
    "title": "40 см"
  }
}

Ответ · 422

{"title": ["Указано не число"]}

Список значений — GET /admin/properties/:id/characteristics.json. У значения есть id, property_id, title, permalink, position.

Варианты

Вариант — это сочетание значений свойств вроде размера и цвета, со своей ценой, остатком, артикулом и штрихкодом. Свойство варианта (option_name) и параметр карточки (property) из раздела «Параметры» — разные справочники. Цена и остаток меняются у варианта, отдельного поля цены у товара в этих запросах нет.

У товара всегда остаётся хотя бы один вариант.

Товар с одним свойством

При создании options задаёт свойство и значение первого варианта. У варианта в ответе появляется option_values.

POST/admin/products.json
Параметр Описание
product[title] обязательный
строка		 Название товара.
product[options][][title] обязательный
строка		 Название свойства, например размера.
product[options][][value] обязательный
строка		 Значение свойства первого варианта.
product[variants_attributes][][price] обязательный
число		 Цена варианта.
product[variants_attributes][][sku] необязательный
строка		 Артикул.
product[variants_attributes][][barcode] необязательный
строка		 Штрихкод. 
POST /admin/products.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "title": "docs-api-размер",
    "options": [
      {
        "title": "docs-api Размер",
        "value": "M"
      }
    ],
    "variants_attributes": [
      {
        "sku": "DOCS-M",
        "price": 1000,
        "barcode": "4600000000109"
      }
    ]
  }
}

Ответ · 201

{
  "id": 945,
  "title": "docs-api-размер",
  "option_names": [
    {"id": 2517858, "title": "docs-api Размер", "permalink": "docs-api-razmer"}
  ],
  "variants": [
    {
      "id": 2176487283,
      "title": "M",
      "sku": "DOCS-M",
      "barcode": "4600000000109",
      "price": "1000.0",
      "option_values": [
        {"id": 21063206, "option_name_id": 2517858, "title": "M"}
      ]
    }
  ]
}

Новое значение того же свойства создаётся отдельным вариантом. option_name_id берётся из option_names товара.

POST/admin/products/945/variants.json
Параметр Описание
variant[price] обязательный
число		 Цена нового варианта.
variant[sku] необязательный
строка		 Артикул.
variant[barcode] необязательный
строка		 Штрихкод.
variant[options][][option_name_id] обязательный
число		 id уже существующего свойства.
variant[options][][value] обязательный
строка		 Новое значение этого свойства. 
POST /admin/products/945/variants.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant": {
    "sku": "DOCS-L",
    "price": 1200,
    "barcode": "4600000000116",
    "options": [
      {
        "option_name_id": 2517858,
        "title": "docs-api Размер",
        "value": "L"
      }
    ]
  }
}

Ответ · 201

{
  "id": 2176487284,
  "title": "L",
  "sku": "DOCS-L",
  "price": "1200.0",
  "option_values": [
    {"id": 21063207, "option_name_id": 2517858, "title": "L"}
  ]
}

Повтор того же значения отвечает 422. У создания варианта ошибки обёрнуты в status и errors:

{"status": "error", "errors": {"options": ["Вариант с такими значениями свойств уже существует"]}}

Новое свойство

Вариант не создаётся, если в options передано свойство, которого у товара ещё нет. В примере у товара есть только «Размер», а в теле — только «Цвет». Ответ 422: список свойств изменился.

POST/admin/products/945/variants.json
Параметр Описание
variant[price] обязательный
число		 Цена варианта.
variant[sku] необязательный
строка		 Артикул.
variant[options][][title] обязательный
строка		 Название свойства, которого у товара ещё нет.
variant[options][][value] обязательный
строка		 Значение этого свойства. 
POST /admin/products/945/variants.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant": {
    "sku": "DOCS-COLOR",
    "price": 1100,
    "options": [
      {
        "title": "docs-api Цвет",
        "value": "Чёрный"
      }
    ]
  }
}

Ответ · 422

{
  "status": "error",
  "errors": {
    "options": ["Список свойств у товара изменился, перезагрузите страницу"]
  }
}

Свойство добавляется обновлением товара. Уже существующее передаётся как option_name_id. Новое — как title и value: value становится значением этого свойства у текущих вариантов. Тело со списком values и без value по умолчанию отвечает 422.

PUT/admin/products/985.json
Параметр Описание
product[options][][option_name_id] необязательный
число		 id уже существующего свойства, которое нужно оставить.
product[options][][title] необязательный
строка		 Название добавляемого свойства.
product[options][][value] необязательный
строка		 Значение добавляемого свойства. Оно проставляется текущим вариантам. 
PUT /admin/products/985.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "options": [
      {
        "option_name_id": 2517859
      },
      {
        "title": "docs-api Цвет",
        "value": "Чёрный"
      }
    ]
  }
}

Ответ · 200

{
  "id": 985,
  "option_names": [
    {"id": 2517859, "title": "docs-api Размер"},
    {"id": 2517860, "title": "docs-api Цвет"}
  ],
  "variants": [
    {
      "id": 2176487289,
      "title": "Чёрный / M",
      "sku": "DOCS-M2",
      "option_values": [
        {"option_name_id": 2517860, "title": "Чёрный"},
        {"option_name_id": 2517859, "title": "M"}
      ]
    }
  ]
}

Дальше новый вариант передаёт все свойства товара. Одно свойство из двух даёт ту же ошибку про список свойств. У обновления варианта ошибки приходят без обёртки status: {"options":["Список свойств у товара изменился, перезагрузите страницу"]}.

POST/admin/products/985/variants.json
Параметр Описание
variant[price] обязательный
число		 Цена варианта.
variant[sku] необязательный
строка		 Артикул.
variant[options][][option_name_id] обязательный
число		 id свойства.
variant[options][][value] обязательный
строка		 Значение этого свойства. 
POST /admin/products/985/variants.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant": {
    "sku": "DOCS-WHITE",
    "price": 1300,
    "options": [
      {
        "option_name_id": 2517859,
        "value": "M"
      },
      {
        "option_name_id": 2517860,
        "value": "Белый"
      }
    ]
  }
}

Ответ · 201

{
  "id": 2176487290,
  "title": "M / Белый",
  "sku": "DOCS-WHITE",
  "price": "1300.0",
  "option_values": [
    {"option_name_id": 2517859, "title": "M"},
    {"option_name_id": 2517860, "title": "Белый"}
  ]
}

Цена, артикул, вес, габариты

PUT /admin/products/:product_id/variants/:id.json меняет цену, старую цену, артикул, штрихкод, вес и габариты одного варианта. Свойства варианта в этом запросе передавать не нужно.

Одна цена на все варианты товара задаётся тем же запросом по каждому id из variants.

PUT/admin/products/913/variants/2176487279.json
Параметр Описание
variant[price] необязательный
число		 Цена.
variant[old_price] необязательный
число		 Старая цена.
variant[sku] необязательный
строка		 Артикул.
variant[barcode] необязательный
строка		 Штрихкод.
variant[weight] необязательный
число		 Вес.
variant[dimensions] необязательный
строка		 Габариты. 
PUT /admin/products/913/variants/2176487279.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant": {
    "price": 1800,
    "old_price": 2100,
    "sku": "DOCS-SIMPLE-2",
    "barcode": "4600000000018",
    "weight": 0.35,
    "dimensions": "10х20х5"
  }
}

Ответ · 200

{
  "id": 2176487279,
  "sku": "DOCS-SIMPLE-2",
  "barcode": "4600000000018",
  "price": "1800.0",
  "old_price": "2100.0",
  "weight": "0.35",
  "dimensions": "10x20x5",
  "quantity": 3,
  "quantity_at_warehouse0": "3.0"
}

Вес в ответе — строка, например "0.35". Русская буква «х» в габаритах сохраняется как латинская x: 10х20х5 становится 10x20x5.

Внешний идентификатор

external_id — идентификатор варианта во внешней системе. Его пишут в уже созданный вариант запросом PUT /admin/products/:product_id/variants/:id.json.

При создании товара варианты лежат во вложенном объекте variants_attributes. Там можно передать цену, артикул, остаток, вес и габариты. Поля external_id в этом объекте нет. Создание товара с таким ключом отвечает 422, ключ назван недопустимым:

{"variants_attributes": ["undefined keys [\"external_id\"]"]}

PUT варианта с "external_id": "1c-200" отвечает 200. В JSON варианта этого поля нет, значение хранится у варианта.

Остаток

quantity — остаток варианта. Остаток на складе передаётся полем quantity_at_warehouseN. Число N — это array_index склада из GET /admin/warehouses.json. У единственного склада индекс 0, поле называется quantity_at_warehouse0.

На магазине с одним складом это один и тот же остаток: запись в любое из двух полей меняет оба. В ответе остаток склада приходит строкой, например "7.0".

Групповое обновление

PUT /admin/products/variants_group_update.json меняет цены и остатки сразу у нескольких вариантов. В теле — массив variants, у каждого элемента обязателен id:

{"variants": [{"id": 2176487279, "price": 1900}]}

Запрос ставит обновление в очередь и сразу отвечает 200 и пустым массивом []. Новые цены и остатки читают запросом варианта после обработки очереди.

Удаление варианта

Последний вариант удалить нельзя.

DELETE/admin/products/953/variants/2176487285.json
Параметр Описание
id обязательный
число		 id варианта в пути. Последний вариант товара удалить нельзя. 
DELETE /admin/products/953/variants/2176487285.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 422

{"base": ["Нельзя удалить последний вариант"]}

Если вариантов больше одного, DELETE /admin/products/945/variants/2176487284.json отвечает 200 и {"status":"ok"}.

Дополнительное поле варианта

Поле создаётся с типом VariantField::TextField. Значение пишется в вариант и возвращается в variant_field_values.

POST/admin/variant_fields.json
Параметр Описание
variant_field[title] обязательный
строка		 Название поля.
variant_field[handle] необязательный
строка		 Системное имя.
variant_field[type] обязательный
строка		 Тип поля. VariantField::TextField — текст. 
POST /admin/variant_fields.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant_field": {
    "title": "docs-api Примечание",
    "handle": "docs_api_note",
    "type": "VariantField::TextField"
  }
}

Ответ · 201

{
  "id": 1,
  "handle": "docs_api_note",
  "type": "VariantField::TextField",
  "title": "docs-api Примечание"
}
PUT/admin/products/945/variants/2176487283.json
Параметр Описание
variant[variant_field_values_attributes][][variant_field_id] обязательный
число		 id дополнительного поля варианта.
variant[variant_field_values_attributes][][value] обязательный
строка		 Значение поля. 
PUT /admin/products/945/variants/2176487283.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant": {
    "variant_field_values_attributes": [
      {
        "variant_field_id": 1,
        "value": "метка"
      }
    ]
  }
}

Ответ · 200

{
  "id": 2176487283,
  "variant_field_values": [
    {"id": 1, "variant_field_id": 1, "value": "метка"}
  ]
}

Изображения

Изображение создаётся у конкретного товара: POST /admin/products/:product_id/images.json. Пока файл обрабатывается, в ответе image_processing: true, а адреса указывают на /images/loading.gif. Имя файла при этом уже настоящее.

Адрес изображения

src — публичный адрес файла. Магазин скачивает изображение по этому адресу, поэтому адрес должен открываться из интернета. Если файл по адресу скачать нельзя, ответ 422:

{"image": ["Не заполнены обязательные поля"], "src": ["Недопустимый URL"]}
POST/admin/products/985/images.json
Параметр Описание
image[src] обязательный
строка		 Адрес изображения в интернете. 
POST /admin/products/985/images.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "image": {
    "src": "https://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png"
  }
}

Ответ · 201

{
  "id": 377,
  "product_id": 985,
  "position": 1,
  "image_processing": true,
  "filename": "1x1.png",
  "url": "/images/loading.gif",
  "original_url": "/images/loading.gif"
}

Файл в теле

Файл передаётся в теле того же запроса POST /admin/products/:product_id/images.json: содержимое — в attachment кодировкой base64, имя файла — в filename. Пока файл обрабатывается, в ответе image_processing: true, адреса указывают на /images/loading.gif.

POST/admin/products/913/images.json
Параметр Описание
image[filename] обязательный
строка		 Имя файла.
image[attachment] обязательный
строка		 Содержимое файла в кодировке base64. 
POST /admin/products/913/images.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "image": {
    "filename": "docs-api.png",
    "attachment": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
  }
}

Ответ · 201

{
  "id": 369,
  "product_id": 913,
  "position": 1,
  "image_processing": true,
  "filename": "docs-api.png",
  "original_url": "/images/loading.gif"
}

Привязка к варианту и порядок

image_id в PUT варианта записывает изображение и в image_id, и в image_ids. Подпись и позиция меняются запросом к самому изображению.

PUT/admin/products/913/variants/2176487279.json
Параметр Описание
variant[image_id] обязательный
число		 id изображения, которую нужно привязать к варианту. 
PUT /admin/products/913/variants/2176487279.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "variant": {
    "image_id": 369
  }
}

Ответ · 200

{
  "id": 2176487279,
  "image_id": 369,
  "image_ids": [369]
}
PUT/admin/products/913/images/369.json
Параметр Описание
image[position] необязательный
число		 Порядок изображения.
image[title] необязательный
строка		 Подпись. 
PUT /admin/products/913/images/369.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "image": {
    "position": 1,
    "title": "docs-api"
  }
}

Ответ · 200

{
  "id": 369,
  "product_id": 913,
  "position": 1,
  "title": "docs-api",
  "filename": "docs-api.png",
  "image_processing": true
}

Аналоги

Запрос принимает массив id других товаров. Ответ создания — {"status":"ok"}. Список возвращает эти id.

POST/admin/products/913/similars.json
Параметр Описание
similar_ids обязательный
массив		 id аналогичных товаров. 
POST /admin/products/913/similars.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "similar_ids": [
    961
  ]
}

Ответ · 200

{"status": "ok"}
GET/admin/products/913/similars.json
GET /admin/products/913/similars.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 200

[{"id": 961}]

Сопутствующие

Сопутствующие товары назначаются тем же запросом на /admin/products/:id/supplementaries.json с полем supplementary_ids. Ответ создания — {"status":"ok"}. Список — массив объектов с id.

Опция покупки

Опция покупки (аксессуар) — отдельный объект магазина со своими значениями и ценой. К товару она крепится ссылкой product_accessory_link. У значения своя цена, покупатель выбирает его при покупке. Размер задаётся в разделе «Варианты», параметр карточки — в разделе «Параметры».

POST/admin/accessories.json
Параметр Описание
accessory[name] обязательный
строка		 Название опции покупки.
accessory[permalink] необязательный
строка		 Адрес опции.
accessory[min_count] необязательный
число		 Минимум выбранных значений.
accessory[max_count] необязательный
число		 Максимум выбранных значений. 
POST /admin/accessories.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "accessory": {
    "name": "docs-api Гравировка",
    "permalink": "docs-api-gravirovka",
    "min_count": 0,
    "max_count": 1
  }
}

Ответ · 201

{
  "id": 2,
  "name": "docs-api Гравировка",
  "permalink": "docs-api-gravirovka",
  "min_count": 0,
  "max_count": 1
}
POST/admin/accessories/2/values.json
Параметр Описание
accessory_value[name] обязательный
строка		 Название значения.
accessory_value[price] необязательный
число		 Добавка к цене. 
POST /admin/accessories/2/values.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "accessory_value": {
    "name": "Имя",
    "price": 300
  }
}

Ответ · 201

{
  "id": 3,
  "accessory_id": 2,
  "name": "Имя",
  "price": "300.0"
}
POST/admin/products/913/product_accessory_links.json
Параметр Описание
product_accessory_link[accessory_id] обязательный
число		 id опции, которую нужно привязать к товару. 
POST /admin/products/913/product_accessory_links.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product_accessory_link": {
    "accessory_id": 2
  }
}

Ответ · 201

{
  "id": 2,
  "accessory_id": 2,
  "product_id": 913
}

В карточке товара ссылка приходит так: "product_accessory_links": [{"id": 2, "accessory_id": 2}].

Комплект

Комплект создаётся вместе с товаром: в теле "bundle": true и состав product_bundle_components_attributes. В составе — variant_id других товаров и количество. Цена комплекта задаётся его собственным вариантом в variants_attributes.

POST/admin/products.json
Параметр Описание
product[title] обязательный
строка		 Название комплекта.
product[bundle] обязательный
логический		 true помечает товар как комплект.
product[variants_attributes][][price] обязательный
число		 Цена комплекта.
product[product_bundle_components_attributes][][variant_id] обязательный
число		 id варианта в составе.
product[product_bundle_components_attributes][][quantity] обязательный
число		 Сколько штук этого варианта входит в комплект. 
POST /admin/products.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "product": {
    "title": "docs-api-комплект",
    "bundle": true,
    "variants_attributes": [
      {
        "price": 40
      }
    ],
    "product_bundle_components_attributes": [
      {
        "variant_id": 2176487279,
        "quantity": 1
      },
      {
        "variant_id": 2176487286,
        "quantity": 1
      }
    ]
  }
}

Ответ · 201

{
  "id": 969,
  "title": "docs-api-комплект",
  "bundle": true,
  "product_bundle_components": [
    {"id": 2, "variant_id": 2176487279, "quantity": "1.0", "product_id": 913, "free": false},
    {"id": 3, "variant_id": 2176487286, "quantity": "1.0", "product_id": 961, "free": false}
  ],
  "variants": [
    {"id": 2176487287, "price": "40.0"}
  ]
}

bundle задаётся только при создании. Обновление обычного товара с "bundle": true и составом отвечает 200 и товар комплектом не делает: в ответе bundle — null, product_bundle_components — пустой массив.