Getting Started with Items

This guide walks you through creating Items on the Hii Retail platform. By the end of this guide, you will understand how to create items, associate them with Item Categories, and make them available to Business Units through assortments.

Overview

What is an Item?

An Item is the core entity for master data management in Hii Retail. It represents any product or service that may be priced, ordered, or sold in your retail operations.

Items connect to several other entities in the system:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Item Category  │────▶│      Item       │◀────│  Business Unit  │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
       ┌────────────┐     ┌────────────┐     ┌────────────┐
       │ Identifier │     │   Price    │     │  Deposit   │
       │ (barcode)  │     │            │     │ (optional) │
       └────────────┘     └────────────┘     └────────────┘

Item Types

Type	Description	Example
`STOCK`	Standard retail item tracked for sales and inventory	Bottled water, shoes, electronics
`SERVICE`	Non-stock item provided as a service	Gift wrapping, alterations
`MODEL`	Grouping for fashion/sport items; not directly sold	"Air Jordan 1" (parent of size variants)
`DEPOSIT`	Used for deposit receipts from reverse vending machines	Bottle deposit return
`SERIALIZED`	One-off items with unique codes	Gift cards, lottery tickets

Item Statuses

Status	Description
`ACTIVE`	Item is active and available for normal use
`DISCONTINUED`	Item is deprecated but may still be sold to clear stock
`DELETED`	Item is deleted and should not be used
`STOPPED`	Item is recalled and must not be sold

Assortment Types

Assortment determines where an item is available for sale:

Type	Description
`IN_ASSORTMENT`	Item is in the active assortment and propagates to all Business Units under the group
`AVAILABLE_ASSORTMENT`	Item is available to add to assortment, but not automatically propagated
`IN_LOCAL_ASSORTMENT`	Item is specific to a single Business Unit (locally managed)
`EXPIRING_ASSORTMENT`	Item will be removed from assortment after a sell-out grace period
`REMOVE_FROM_ASSORTMENT`	Item is removed from all assortments

Prerequisites

Before you begin, ensure you have:

Business Units created: At least one Business Unit or Business Unit Group (see Business Units guide)
Item Categories created: At least one Item Category to assign to your items (see Item Categories guide)
Authentication Token: A valid JWT bearer token with the pnp.item.create permission

Authentication

For details on obtaining an access token, see the OAuth2 Authentication documentation.

API Base URL

All Item Input API requests should be sent to:

https://item-input.retailsvc.com/api/v2

Step 1: Create a Simple Item

Create a basic stock item and assign it to an Item Category and Business Unit Group.

Required Fields

Field	Type	Description
`id`	string	Unique identifier (max 250 characters)
`name`	string	Display name (2-256 characters)
`status`	string	`ACTIVE`, `DISCONTINUED`, `DELETED`, or `STOPPED`
`type`	string	`STOCK`, `SERVICE`, `MODEL`, `DEPOSIT`, or `SERIALIZED`
`itemCategoryId`	string	Reference to an existing Item Category
`salesUnitOfMeasurement`	string	Unit of measure (e.g., `EA`, `KGM`, `LTR`)
`assortmentType`	string	Determines availability (see Assortment Types above)
`businessUnitGroupId`	string	The Business Unit Group where the item is available

Code Examples

cURL
Python
Node.js
Java
.NET

curl -X POST 'https://item-input.retailsvc.com/api/v2/bu-g-items' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "5449000051578",
    "name": "Fanta Orange 500ml",
    "status": "ACTIVE",
    "type": "STOCK",
    "itemCategoryId": "beverages-soft-drinks",
    "salesUnitOfMeasurement": "EA",
    "assortmentType": "IN_ASSORTMENT",
    "businessUnitGroupId": "acme-retail-group"
  }'

response = requests.post(
    "https://item-input.retailsvc.com/api/v2/bu-g-items",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "5449000051578",
        "name": "Fanta Orange 500ml",
        "status": "ACTIVE",
        "type": "STOCK",
        "itemCategoryId": "beverages-soft-drinks",
        "salesUnitOfMeasurement": "EA",
        "assortmentType": "IN_ASSORTMENT",
        "businessUnitGroupId": "acme-retail-group"
    }
)

const response = await fetch('https://item-input.retailsvc.com/api/v2/bu-g-items', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: '5449000051578',
    name: 'Fanta Orange 500ml',
    status: 'ACTIVE',
    type: 'STOCK',
    itemCategoryId: 'beverages-soft-drinks',
    salesUnitOfMeasurement: 'EA',
    assortmentType: 'IN_ASSORTMENT',
    businessUnitGroupId: 'acme-retail-group'
  })
});

var payload = """
    {
      "id": "5449000051578",
      "name": "Fanta Orange 500ml",
      "status": "ACTIVE",
      "type": "STOCK",
      "itemCategoryId": "beverages-soft-drinks",
      "salesUnitOfMeasurement": "EA",
      "assortmentType": "IN_ASSORTMENT",
      "businessUnitGroupId": "acme-retail-group"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var payload = new {
    id = "5449000051578",
    name = "Fanta Orange 500ml",
    status = "ACTIVE",
    type = "STOCK",
    itemCategoryId = "beverages-soft-drinks",
    salesUnitOfMeasurement = "EA",
    assortmentType = "IN_ASSORTMENT",
    businessUnitGroupId = "acme-retail-group"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://item-input.retailsvc.com/api/v2/bu-g-items", content);

Response

A successful request returns 202 Accepted.

Asynchronous Processing

The Item Input API processes requests asynchronously. A 202 Accepted response means your request has been queued for processing, not that the item has been created yet.

To verify your item was created successfully, query the Item API (read endpoint) after a short delay.

Step 2: Add Item Identifiers (Barcodes)

Items typically need one or more identifiers (barcodes) for scanning at POS. You can include identifiers when creating the item.

Identifier Types

Type	Description	Example
`GTIN13`	13-digit Global Trade Item Number (EAN-13)	`5449000051578`
`GTIN12`	12-digit Global Trade Item Number (UPC-A)	`049000051578`
`GTIN8`	8-digit Global Trade Item Number (EAN-8)	`96385074`
`GTIN14`	14-digit Global Trade Item Number	`15449000051575`
`PLU`	Price Look-Up code (for produce)	`4011`
`SKU`	Stock Keeping Unit	`FANTA-ORG-500`

Code Examples

cURL
Python
Node.js
Java
.NET

curl -X POST 'https://item-input.retailsvc.com/api/v2/bu-g-items' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "5449000051578",
    "name": "Fanta Orange 500ml",
    "status": "ACTIVE",
    "type": "STOCK",
    "itemCategoryId": "beverages-soft-drinks",
    "salesUnitOfMeasurement": "EA",
    "assortmentType": "IN_ASSORTMENT",
    "businessUnitGroupId": "acme-retail-group",
    "identifiers": [
      {
        "id": "5449000051578",
        "value": "5449000051578",
        "type": "GTIN13",
        "status": "ACTIVE",
        "isPrimary": true
      },
      {
        "id": "FANTA-ORG-500",
        "value": "FANTA-ORG-500",
        "type": "SKU",
        "status": "ACTIVE",
        "isPrimary": false
      }
    ]
  }'

response = requests.post(
    "https://item-input.retailsvc.com/api/v2/bu-g-items",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "5449000051578",
        "name": "Fanta Orange 500ml",
        "status": "ACTIVE",
        "type": "STOCK",
        "itemCategoryId": "beverages-soft-drinks",
        "salesUnitOfMeasurement": "EA",
        "assortmentType": "IN_ASSORTMENT",
        "businessUnitGroupId": "acme-retail-group",
        "identifiers": [
            {"id": "5449000051578", "value": "5449000051578", "type": "GTIN13", "status": "ACTIVE", "isPrimary": True},
            {"id": "FANTA-ORG-500", "value": "FANTA-ORG-500", "type": "SKU", "status": "ACTIVE", "isPrimary": False}
        ]
    }
)

const response = await fetch('https://item-input.retailsvc.com/api/v2/bu-g-items', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: '5449000051578',
    name: 'Fanta Orange 500ml',
    status: 'ACTIVE',
    type: 'STOCK',
    itemCategoryId: 'beverages-soft-drinks',
    salesUnitOfMeasurement: 'EA',
    assortmentType: 'IN_ASSORTMENT',
    businessUnitGroupId: 'acme-retail-group',
    identifiers: [
      { id: '5449000051578', value: '5449000051578', type: 'GTIN13', status: 'ACTIVE', isPrimary: true },
      { id: 'FANTA-ORG-500', value: 'FANTA-ORG-500', type: 'SKU', status: 'ACTIVE', isPrimary: false }
    ]
  })
});

var payload = """
    {
      "id": "5449000051578",
      "name": "Fanta Orange 500ml",
      "status": "ACTIVE",
      "type": "STOCK",
      "itemCategoryId": "beverages-soft-drinks",
      "salesUnitOfMeasurement": "EA",
      "assortmentType": "IN_ASSORTMENT",
      "businessUnitGroupId": "acme-retail-group",
      "identifiers": [
        {"id": "5449000051578", "value": "5449000051578", "type": "GTIN13", "status": "ACTIVE", "isPrimary": true},
        {"id": "FANTA-ORG-500", "value": "FANTA-ORG-500", "type": "SKU", "status": "ACTIVE", "isPrimary": false}
      ]
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var payload = new {
    id = "5449000051578",
    name = "Fanta Orange 500ml",
    status = "ACTIVE",
    type = "STOCK",
    itemCategoryId = "beverages-soft-drinks",
    salesUnitOfMeasurement = "EA",
    assortmentType = "IN_ASSORTMENT",
    businessUnitGroupId = "acme-retail-group",
    identifiers = new[] {
        new { id = "5449000051578", value = "5449000051578", type = "GTIN13", status = "ACTIVE", isPrimary = true },
        new { id = "FANTA-ORG-500", value = "FANTA-ORG-500", type = "SKU", status = "ACTIVE", isPrimary = false }
    }
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://item-input.retailsvc.com/api/v2/bu-g-items", content);

Step 3: Create a Weight-Based Item

For items sold by weight (like produce), use the appropriate unit of measure and configure identifiers for scales.

Common Units of Measurement

Code	Description
`EA`	Each (single unit)
`KGM`	Kilogram
`GRM`	Gram
`LTR`	Liter
`MLT`	Milliliter
`MTR`	Meter

Code Examples

cURL
Python
Node.js
Java
.NET

curl -X POST 'https://item-input.retailsvc.com/api/v2/bu-g-items' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "PLU-4011",
    "name": "Bananas",
    "status": "ACTIVE",
    "type": "STOCK",
    "itemCategoryId": "produce-fruit",
    "salesUnitOfMeasurement": "KGM",
    "referencePriceUnitOfMeasurement": "KGM",
    "referencePriceConversionFactor": 1.0,
    "netContent": 1.0,
    "assortmentType": "IN_ASSORTMENT",
    "businessUnitGroupId": "acme-retail-group",
    "identifiers": [
      {
        "id": "4011",
        "value": "4011",
        "type": "PLU",
        "status": "ACTIVE",
        "isPrimary": true,
        "description": "PLU code for cashier keyboard"
      },
      {
        "id": "2004011000002",
        "value": "2004011000002",
        "type": "GTIN13",
        "status": "ACTIVE",
        "isPrimary": false,
        "description": "Variable weight barcode for scales"
      }
    ]
  }'

response = requests.post(
    "https://item-input.retailsvc.com/api/v2/bu-g-items",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "PLU-4011",
        "name": "Bananas",
        "status": "ACTIVE",
        "type": "STOCK",
        "itemCategoryId": "produce-fruit",
        "salesUnitOfMeasurement": "KGM",
        "referencePriceUnitOfMeasurement": "KGM",
        "referencePriceConversionFactor": 1.0,
        "netContent": 1.0,
        "assortmentType": "IN_ASSORTMENT",
        "businessUnitGroupId": "acme-retail-group",
        "identifiers": [
            {"id": "4011", "value": "4011", "type": "PLU", "status": "ACTIVE", "isPrimary": True},
            {"id": "2004011000002", "value": "2004011000002", "type": "GTIN13", "status": "ACTIVE", "isPrimary": False}
        ]
    }
)

const response = await fetch('https://item-input.retailsvc.com/api/v2/bu-g-items', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 'PLU-4011',
    name: 'Bananas',
    status: 'ACTIVE',
    type: 'STOCK',
    itemCategoryId: 'produce-fruit',
    salesUnitOfMeasurement: 'KGM',
    referencePriceUnitOfMeasurement: 'KGM',
    referencePriceConversionFactor: 1.0,
    netContent: 1.0,
    assortmentType: 'IN_ASSORTMENT',
    businessUnitGroupId: 'acme-retail-group',
    identifiers: [
      { id: '4011', value: '4011', type: 'PLU', status: 'ACTIVE', isPrimary: true },
      { id: '2004011000002', value: '2004011000002', type: 'GTIN13', status: 'ACTIVE', isPrimary: false }
    ]
  })
});

var payload = """
    {
      "id": "PLU-4011",
      "name": "Bananas",
      "status": "ACTIVE",
      "type": "STOCK",
      "itemCategoryId": "produce-fruit",
      "salesUnitOfMeasurement": "KGM",
      "referencePriceUnitOfMeasurement": "KGM",
      "referencePriceConversionFactor": 1.0,
      "netContent": 1.0,
      "assortmentType": "IN_ASSORTMENT",
      "businessUnitGroupId": "acme-retail-group",
      "identifiers": [
        {"id": "4011", "value": "4011", "type": "PLU", "status": "ACTIVE", "isPrimary": true},
        {"id": "2004011000002", "value": "2004011000002", "type": "GTIN13", "status": "ACTIVE", "isPrimary": false}
      ]
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var payload = new {
    id = "PLU-4011",
    name = "Bananas",
    status = "ACTIVE",
    type = "STOCK",
    itemCategoryId = "produce-fruit",
    salesUnitOfMeasurement = "KGM",
    referencePriceUnitOfMeasurement = "KGM",
    referencePriceConversionFactor = 1.0,
    netContent = 1.0,
    assortmentType = "IN_ASSORTMENT",
    businessUnitGroupId = "acme-retail-group",
    identifiers = new[] {
        new { id = "4011", value = "4011", type = "PLU", status = "ACTIVE", isPrimary = true },
        new { id = "2004011000002", value = "2004011000002", type = "GTIN13", status = "ACTIVE", isPrimary = false }
    }
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://item-input.retailsvc.com/api/v2/bu-g-items", content);

Step 4: Create an Item for a Specific Business Unit

To create an item available only at a specific Business Unit (not inherited from a group), use the Business Unit endpoint.

cURL
Python
Node.js
Java
.NET

curl -X POST 'https://item-input.retailsvc.com/api/v2/bu-items' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "LOCAL-SPECIAL-001",
    "name": "Store Special - Fresh Baked Bread",
    "status": "ACTIVE",
    "type": "STOCK",
    "itemCategoryId": "bakery-bread",
    "salesUnitOfMeasurement": "EA",
    "assortmentType": "IN_LOCAL_ASSORTMENT",
    "businessUnitId": "store-123",
    "identifiers": [
      {
        "id": "LOCAL-SPECIAL-001",
        "value": "2099999000001",
        "type": "GTIN13",
        "status": "ACTIVE",
        "isPrimary": true
      }
    ]
  }'

response = requests.post(
    "https://item-input.retailsvc.com/api/v2/bu-items",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "LOCAL-SPECIAL-001",
        "name": "Store Special - Fresh Baked Bread",
        "status": "ACTIVE",
        "type": "STOCK",
        "itemCategoryId": "bakery-bread",
        "salesUnitOfMeasurement": "EA",
        "assortmentType": "IN_LOCAL_ASSORTMENT",
        "businessUnitId": "store-123",
        "identifiers": [
            {"id": "LOCAL-SPECIAL-001", "value": "2099999000001", "type": "GTIN13", "status": "ACTIVE", "isPrimary": True}
        ]
    }
)

const response = await fetch('https://item-input.retailsvc.com/api/v2/bu-items', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 'LOCAL-SPECIAL-001',
    name: 'Store Special - Fresh Baked Bread',
    status: 'ACTIVE',
    type: 'STOCK',
    itemCategoryId: 'bakery-bread',
    salesUnitOfMeasurement: 'EA',
    assortmentType: 'IN_LOCAL_ASSORTMENT',
    businessUnitId: 'store-123',
    identifiers: [
      { id: 'LOCAL-SPECIAL-001', value: '2099999000001', type: 'GTIN13', status: 'ACTIVE', isPrimary: true }
    ]
  })
});

var payload = """
    {
      "id": "LOCAL-SPECIAL-001",
      "name": "Store Special - Fresh Baked Bread",
      "status": "ACTIVE",
      "type": "STOCK",
      "itemCategoryId": "bakery-bread",
      "salesUnitOfMeasurement": "EA",
      "assortmentType": "IN_LOCAL_ASSORTMENT",
      "businessUnitId": "store-123",
      "identifiers": [
        {"id": "LOCAL-SPECIAL-001", "value": "2099999000001", "type": "GTIN13", "status": "ACTIVE", "isPrimary": true}
      ]
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-items"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var payload = new {
    id = "LOCAL-SPECIAL-001",
    name = "Store Special - Fresh Baked Bread",
    status = "ACTIVE",
    type = "STOCK",
    itemCategoryId = "bakery-bread",
    salesUnitOfMeasurement = "EA",
    assortmentType = "IN_LOCAL_ASSORTMENT",
    businessUnitId = "store-123",
    identifiers = new[] {
        new { id = "LOCAL-SPECIAL-001", value = "2099999000001", type = "GTIN13", status = "ACTIVE", isPrimary = true }
    }
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://item-input.retailsvc.com/api/v2/bu-items", content);

Business Unit Group vs Business Unit

Use POST /api/v2/bu-g-items with businessUnitGroupId to create items that inherit to all Business Units in the group
Use POST /api/v2/bu-items with businessUnitId to create items specific to a single Business Unit

Step 5: Update an Item

Use PUT to fully replace an item or PATCH for partial updates.

Partial Update (PATCH)

cURL
Python
Node.js
Java
.NET

curl -X PATCH 'https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '[
    {"op": "replace", "path": "/name", "value": "Fanta Orange 500ml (New Recipe)"},
    {"op": "replace", "path": "/description", "value": "Refreshed with a new recipe!"}
  ]'

response = requests.patch(
    "https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578",
    params={"businessUnitGroupId": "acme-retail-group"},
    headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json-patch+json"},
    json=[
        {"op": "replace", "path": "/name", "value": "Fanta Orange 500ml (New Recipe)"},
        {"op": "replace", "path": "/description", "value": "Refreshed with a new recipe!"}
    ]
)

const response = await fetch(
  'https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group',
  {
    method: 'PATCH',
    headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json-patch+json' },
    body: JSON.stringify([
      { op: 'replace', path: '/name', value: 'Fanta Orange 500ml (New Recipe)' },
      { op: 'replace', path: '/description', value: 'Refreshed with a new recipe!' }
    ])
  }
);

var operations = """
    [{"op": "replace", "path": "/name", "value": "Fanta Orange 500ml (New Recipe)"},
     {"op": "replace", "path": "/description", "value": "Refreshed with a new recipe!"}]
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json-patch+json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString(operations))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var operations = new[] {
    new { op = "replace", path = "/name", value = "Fanta Orange 500ml (New Recipe)" },
    new { op = "replace", path = "/description", value = "Refreshed with a new recipe!" }
};

var content = new StringContent(JsonSerializer.Serialize(operations), Encoding.UTF8, "application/json-patch+json");
var request = new HttpRequestMessage(HttpMethod.Patch,
    "https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group") { Content = content };

var response = await httpClient.SendAsync(request);

Immutable Properties

The id, businessUnitGroupId, revision, and identifiers properties cannot be updated via PATCH.

Step 6: Remove an Item from Assortment

To remove an item from sale, you can either change its assortment type or delete it.

Change Assortment Type

cURL
Python
Node.js
Java
.NET

curl -X PATCH 'https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '[
    {"op": "replace", "path": "/assortmentType", "value": "REMOVE_FROM_ASSORTMENT"}
  ]'

response = requests.patch(
    "https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578",
    params={"businessUnitGroupId": "acme-retail-group"},
    headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json-patch+json"},
    json=[{"op": "replace", "path": "/assortmentType", "value": "REMOVE_FROM_ASSORTMENT"}]
)

const response = await fetch(
  'https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group',
  {
    method: 'PATCH',
    headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json-patch+json' },
    body: JSON.stringify([{ op: 'replace', path: '/assortmentType', value: 'REMOVE_FROM_ASSORTMENT' }])
  }
);

var operations = """[{"op": "replace", "path": "/assortmentType", "value": "REMOVE_FROM_ASSORTMENT"}]""";

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json-patch+json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString(operations))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var operations = new[] { new { op = "replace", path = "/assortmentType", value = "REMOVE_FROM_ASSORTMENT" } };
var content = new StringContent(JsonSerializer.Serialize(operations), Encoding.UTF8, "application/json-patch+json");
var request = new HttpRequestMessage(HttpMethod.Patch,
    "https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group") { Content = content };

var response = await httpClient.SendAsync(request);

Delete an Item

cURL
Python
Node.js
Java
.NET

curl -X DELETE 'https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group' \
  -H 'Authorization: Bearer <your-access-token>'

response = requests.delete(
    "https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578",
    params={"businessUnitGroupId": "acme-retail-group"},
    headers={"Authorization": f"Bearer {access_token}"}
)

const response = await fetch(
  'https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group',
  { method: 'DELETE', headers: { 'Authorization': `Bearer ${accessToken}` } }
);

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group"))
    .header("Authorization", "Bearer " + accessToken)
    .DELETE()
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

var response = await httpClient.DeleteAsync(
    "https://item-input.retailsvc.com/api/v2/bu-g-items/5449000051578?businessUnitGroupId=acme-retail-group");

Understanding Inheritance

When you create an item at the Business Unit Group level with assortmentType: "IN_ASSORTMENT":

The item definition is stored at the group level
The item automatically propagates to all Business Units within that group
Each Business Unit receives its own copy that can be locally modified if needed

┌─────────────────────────────────────────────────────────┐
│              Business Unit Group                        │
│                "acme-retail-group"                      │
│                                                         │
│  Item: Fanta Orange (assortmentType: IN_ASSORTMENT)     │
└────────────────────────┬────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │ Store A │    │ Store B │    │ Store C │
    │ (BU)    │    │ (BU)    │    │ (BU)    │
    │         │    │         │    │         │
    │ ✓ Fanta │    │ ✓ Fanta │    │ ✓ Fanta │
    └─────────┘    └─────────┘    └─────────┘

Next Steps

Now that you can create items, you can:

Add prices: Configure pricing for your items using the Price Input API
Configure taxes: Set up tax rates for your items
Add deposits: Configure deposit rules for returnable items

Next: Item Identifiers - Learn how to create barcodes and other identifiers for your items.

Overview​

What is an Item?​

Item Types​

Item Statuses​

Assortment Types​

Prerequisites​

API Base URL​

Step 1: Create a Simple Item​

Required Fields​

Code Examples​

Response​

Step 2: Add Item Identifiers (Barcodes)​

Identifier Types​

Code Examples​

Step 3: Create a Weight-Based Item​

Common Units of Measurement​

Code Examples​

Step 4: Create an Item for a Specific Business Unit​

Step 5: Update an Item​

Partial Update (PATCH)​

Step 6: Remove an Item from Assortment​

Change Assortment Type​

Delete an Item​

Understanding Inheritance​

Next Steps​

Related Resources​

Overview

What is an Item?

Item Types

Item Statuses

Assortment Types

Prerequisites

API Base URL

Step 1: Create a Simple Item

Required Fields

Code Examples

Response

Step 2: Add Item Identifiers (Barcodes)

Identifier Types

Code Examples

Step 3: Create a Weight-Based Item

Common Units of Measurement

Code Examples

Step 4: Create an Item for a Specific Business Unit

Step 5: Update an Item

Partial Update (PATCH)

Step 6: Remove an Item from Assortment

Change Assortment Type

Delete an Item

Understanding Inheritance

Next Steps

Related Resources