> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert items and bundles
> With this endpoint, you can create or update items or bundles along with their attributes.
**Note**:
1) If the SKU already exists, then the given item or bundle is updated. Otherwise, a new item or bundle is created with that SKU.
2) You can add or update up to 50 items or bundles.
3) By specifying the attribute `value` as NULL, a reserved keyword, you can remove the existing attribute value.
## OpenAPI
````yaml pim post /api-product/v1/product/bulk/upsert
openapi: 3.0.0
info:
title: Product Catalog
description: >-
As brands and retailers grow, they often expand their item catalogs,
resulting in the need to enrich and manage more product (commonly referred
to as item in fabric) data. fabric Product Catalog alleviates the burden of
managing large amounts of item data by means of a central storage
repository. fabric Product Catalog helps you with improved data quality,
consistent customer experience, reduced time to market, easy integration
with external systems, reduced management costs and risks, faster and easier
updates, and easy scaling. You can create, import, enrich, validate,
distribute, and manage complex item information, centrally. As a result, you
deliver product experiences that drive sales through every channel.
During onboarding, you are given the necessary credentials to access
Product Catalog - Copilot UI, APIs, or both. As a prerequisite, you create
the items to be sold, identify their unique as well as common properties,
and envision their organization into categories and sub categories. A basic
workflow is:
1) **Create item attributes** using POST
/api-product/v1/product/attribute/bulk.
2) **Update attribute
mapping** using POST /api-product/v1/product/attribute/mapping
3)
**Create Primary category** using the POST /api-category/v1/category to
create the original organizational structure.
4) **Assign item
attributes** to Primary category using POST
/api-category/v1/category/item-attribute.
5) **Create items** using
POST /api-product/v1/product/bulk/insert.
6) **Create Alternate
category**, for distribution management and fulfilling various merchandising
objectives.
version: 2.0.0
contact:
email: support@fabric.inc
license:
name: fabric API License
url: https://fabric.inc/api-license
servers:
- url: https://live.copilot.fabric.inc
description: Production
security: []
tags:
- name: Category
description: >-
Categories (also called hierarchies or nodes) are hierarchical structures
to organize items and services into intuitive groups. Organizing items in
this way simplifies item discovery and lifecycle management. There are two
types of categories - **Primary** and **Alternate**. They enable you to
create, organize, and distribute item data. - Primary category is the
original catalog tree with nested levels of categories that place each
item where it belongs, within a category. For example, `Computers` is a
parent category with `Laptops` and `Desktops` as children categories, and
`MacBook Pro` is an item within `Laptops`. This organization can be
represented as Computers > Laptops > MacBook Pro. - Alternate categories
serve as alternate organizations of the Primary category. Their main
purpose is distribution management by displaying items on your website
based on separate browsing structure configurations you set to help you
achieve various merchandizing objectives, such as organizational
requirements, multi-regional assortments, multi-channel assortments, and
collections. For example, a company that sells, repairs, and supports
computers and related items and services will have a Primary category
containing a full list of their SKUs. However, this Primary category is
not granular enough to use on their storefront. Hence, multiple Alternate
hierarchies are created to target specific shopper segment experiences.
For laptop consumers they'll have one Alternate category, which lists all
the laptops and PCs. For large businesses they'll have another Alternate
category, which lists all commercial laptops, PCs, printers, and servers.
Both of the Alternate categories act as filters of the Primary category,
tailored to the purpose of that merchandising strategy. **Category**, a
subset of Product Catalog endpoints, aims to simplify catalog management
by letting you create, update, and get one or more categories, category
attributes, and item attributes. In addition, you can add and update
category sources, source exclusions, and item attribute conditions.
**Note**: The root name of primary category is PRIMARY, and it cannot be
changed.
- name: Product
description: >-
**Product**, a subset of Product Catalog endpoints, aims at making item
management more efficient. They create, update, and get items, which may
be individual items or collection of items (called bundles). Each item has
a title, item ID, description, category, and assigned attributes. Multiple
options of a given item become variants of that item. For example, a
t-shirt with three sizes may have small, medium, and large variants. Each
variant has its own item ID, attributes, and other data points. Each
variant is nested under its parent item, allowing the different options to
appear on the same product page. You can also create or update one or more
item attributes and attribute groups.
- name: Attributes
description: >-
Item attributes are the objective and factual descriptions of items that
shoppers see when they browse through your site. Attributes may be
technical specifications like size, weight, etc., design specifications
like color, material, etc., or basic specifications like name,
description, and ID. Ites attributes are crucial as they directly
influence purchasing decisions. Complete and correct item information help
shoppers narrow down their search and filter items with minimal cognitive
load.
- name: Bulk Import
description: >-
Set of endpoints to help bulk import of items, bundles, categories and
attributes through CSV files
externalDocs:
description: Find out more about Product Catalog
url: /v3/product-catalog/user-guides/product-catalog/overview
paths:
/api-product/v1/product/bulk/upsert:
post:
tags:
- Product
summary: Upsert items and bundles
description: >-
With this endpoint, you can create or update items or bundles along with
their attributes.
**Note**:
1) If the SKU already exists,
then the given item or bundle is updated. Otherwise, a new item or
bundle is created with that SKU.
2) You can add or update up to
50 items or bundles.
3) By specifying the attribute `value` as
NULL, a reserved keyword, you can remove the existing attribute value.
operationId: upsertProducts
parameters:
- $ref: '#/components/parameters/xSiteContent'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCreate'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'422':
description: Failing items
content:
application/json:
schema:
$ref: '#/components/schemas/ProductModifyError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
security:
- authorization: []
components:
parameters:
xSiteContent:
name: x-site-context
in: header
description: >-
The `x-site-context` header is a JSON object that contains information
about the source you wish to pull from. The mandatory `account` is the
24 character identifier found in Copilot. The `channel` (Sales channel
ID), `stage` (environment name), and `date` attributes can be used to
further narrow the scope of your data source.
required: true
schema:
type: string
example: >-
{"date": "2023-01-01T00:00:00.000Z", "channel": 12, "account":
"1234abcd5678efgh9ijklmno","stage":"production"}
schemas:
ProductCreate:
type: array
maxItems: 50
items:
properties:
sku:
description: Stock Keeping Unit (SKU) of item
type: string
example: sku_abc
type:
description: Item type
type: string
enum:
- ITEM
- BUNDLE
example: ITEM
nodeName:
description: >-
Category name (along with parent category names) for which item is
being created.
type: string
example: PRIMARY->electronics
parentSku:
description: >-
Stock Keeping Unit (SKU) of the parent item.
Set the value
as `detach` or `null` to disassociate the item from parent item.
type: string
nullable: true
example: sku123
attributeValues:
description: Attribute details
type: array
items:
anyOf:
- $ref: '#/components/schemas/AttributeValue'
- $ref: '#/components/schemas/AttributeValueFrenchLocale'
inheritedAttributes:
$ref: '#/components/schemas/InheritItemAttributesInsert'
description: >-
Category item attributes to be inherited from parent item to
children items
bundleItems:
description: Items to be added to a bundle. Includes SKU and item quantity.
type: array
items:
$ref: '#/components/schemas/BundleItems'
required:
- sku
- type
- nodeName
ProductResponse:
type: object
properties:
success:
type: array
items:
type: object
properties:
sku:
type: string
example: sku1
description: Stock Keeping Unit (SKU) of item
itemId:
type: string
example: 611686da50fb7e0c5df78c2e
description: Item ID
itemIdSeq:
type: number
example: 12
description: Item ID, which increments sequentially
message:
type: string
example: SKU created successfully.
description: Success message
errorAttributes:
type: array
items:
type: object
properties:
name:
type: string
example: Inactive
description: Error reason
message:
type: string
example: Attribute value is invalid.
description: Human-readable error message
errorBundles:
type: array
items:
type: object
properties:
name:
type: string
description: Error reason
message:
type: string
description: Human-readable error message
failed:
type: array
items:
type: object
properties:
sku:
type: string
example: sku1
description: Stock Keeping Unit (SKU), a unique identifier of item
message:
type: string
example: Failed because of validation
description: Failure message
itemIds:
description: Item IDs
example:
- 611686da50fb7e0c5df78c2e
- 711686da50fb7e0c5df78c22
type: array
items:
type: string
ClientError:
type: object
properties:
code:
description: Error code for machine consumption
type: string
example: 400
message:
description: Human-readable error description
type: string
example: Client error
ProductModifyError:
type: object
properties:
code:
type: string
enum:
- STATUS_ERROR
description: Error code for backend mapping
message:
type: array
description: Error details for invalid items
items:
type: object
properties:
index:
type: number
description: Index of the item update request
item:
$ref: '#/components/schemas/ProductResponse'
ServerError:
type: object
properties:
code:
description: Error code
type: string
example: 500
message:
description: Human-readable error description
type: string
example: >-
An internal error occurred. If the issue persists please contact
support@fabric.inc.
AttributeValue:
type: object
properties:
name:
type: string
example: Mobile
description: Attribute name
value:
type: string
example: AMD X570 mobo
description: Attribute value
AttributeValueFrenchLocale:
type: object
properties:
name:
type: string
example: Mobile-French
description: Attribute name in French
value:
type: string
example: Le téléphone portatif AMD X570
description: Attribute value in French
InheritItemAttributesInsert:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the attribute that can be inherited
example: color
action:
description: Action to set the inherited attribute
example: SET
type: string
enum:
- SET
required:
- name
- action
minItems: 1
BundleItems:
type: object
required:
- sku
- quantity
properties:
sku:
description: Stock Keeping Unit (SKU) of item that must be added to bundle
type: string
example: sku123
quantity:
description: Item quantity to be added to bundle
type: number
example: 6
securitySchemes:
authorization:
type: http
scheme: bearer
bearerFormat: JWT
description: S2S access token (JWT) from fabric Identity service (during Login)
````