Items API Reference

Overview

Manage your item catalog with our comprehensive Items API. Create, update, delete, and retrieve item information with full support for single or bundling items, images, and inventory tracking.

Authentication

All API requests require authentication using token and tenant identification:

Authorization: YOUR_API_KEY
X-Tenant-Id: YOUR_TENANT_ID

Endpoints

Method	Endpoint	Description
GET	`/api/partner/v1/items/categories`	List item categories
GET	`/api/partner/v1/items`	List items
GET	`/api/partner/v1/items/:id`	Item detail
GET	`/api/partner/v1/items/:id/stocks`	Item stocks
POST	`/api/partner/v1/items`	Create Item
PUT	`/api/partner/v1/items`	Update Item

Retrieve a paginated list of categories.

Endpoint: GET /api/partner/v1/items/categories

Headers:

Authorization: {token} (required)
X-Tenant-Id: {tenant_id} (required)

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Items per page (default: 20, max: 100)

Example Request:

bash

curl -X GET "{{url}}/api/partner/v1/items/categories?page=1&per_page=10" \
  -H "Authorization: {token}" \
  -H "X-Tenant-Id: {tenant_id}"

Example Response:

json

{
  "status": 200,
  "message": "Ok",
  "data": {
    "categories": [
      {
        "category_id": 12,
        "name": "Laptop & Komputer",
        "description": "Laptop, desktop, dan komponen komputer",
        "parent_id": 1,
        "sort_order": 2,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 13,
        "name": "Elektronik Rumah Tangga",
        "description": "Peralatan elektronik untuk rumah tangga",
        "parent_id": 1,
        "sort_order": 3,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 11,
        "name": "Smartphone & Tablet",
        "description": "Handphone, tablet, dan aksesorisnya",
        "parent_id": 1,
        "sort_order": 1,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 5,
        "name": "Olahraga & Outdoor",
        "description": "Peralatan olahraga dan aktivitas outdoor",
        "parent_id": null,
        "sort_order": 5,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 6,
        "name": "Otomotif",
        "description": "Suku cadang dan aksesoris kendaraan",
        "parent_id": null,
        "sort_order": 6,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 7,
        "name": "Buku & Media",
        "description": "Buku, majalah, dan media pembelajaran",
        "parent_id": null,
        "sort_order": 7,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 8,
        "name": "Mainan & Hobi",
        "description": "Mainan anak dan koleksi hobi",
        "parent_id": null,
        "sort_order": 8,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 9,
        "name": "Makanan & Minuman",
        "description": "Produk makanan dan minuman",
        "parent_id": null,
        "sort_order": 9,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 10,
        "name": "Ibu & Bayi",
        "description": "Perlengkapan ibu hamil dan bayi",
        "parent_id": null,
        "sort_order": 10,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      },
      {
        "category_id": 14,
        "name": "Audio & Video",
        "description": "Speaker, headphone, kamera, dan peralatan audio video",
        "parent_id": 1,
        "sort_order": 4,
        "created_at": "2025-08-25T03:26:56.000000Z",
        "updated_at": "2025-08-25T03:26:56.000000Z"
      }
    ],
    "pagination": {
      "total": 45,
      "per_page": 10,
      "current_page": 1,
      "last_page": 5,
      "from": 1,
      "to": 10
    }
  },
  "errors": null,
  "request_id": "7eb25b1c-be67-4522-9c5b-55ee5bf9e76a"
}

2. Create Item

Create a new item with type single or bundling and images.

Endpoint: POST /api/partner/v1/items

Headers:

Authorization: {token} (required)
X-Tenant-Id: {tenant_id} (required)

Request Parameters:

Parameter	Type	Required	Description
name	string	Yes	Product name (max 255 characters)
sku	string	Yes	Unique product SKU (max 100 characters, unique per tenant)
barcode	string	No	Product barcode (max 100 characters)
description	string	Yes	Product description
category_id	integer	Yes	Category ID (must exist in tenant categories)
brand	string	No	Product brand (max 100 characters)
supplier	string	No	Supplier name (max 100 characters)
product_type	string	Yes	Product type (`physical`, `digital`)
status	string	Yes	Product status (`published`, `draft`, `archived`)
is_bundle	boolean	Conditional	Required if `product_type` = `physical`
weight	number	Conditional	Required if `product_type` = `physical` (min 0)
width	number	Conditional	Required if `product_type` = `physical` (min 0)
height	number	Conditional	Required if `product_type` = `physical` (min 0)
length	number	Conditional	Required if `product_type` = `physical` (min 0)
published_price	number	Yes	Selling price (min 0)
cost_price	number	Yes	Cost price (min 0)
is_managed_by_fulfillment	boolean	Conditional	Required if `product_type` = `physical`
fulfillment_manage_by	string	Conditional	Required if `is_managed_by_fulfillment` = `true` (`fifo`, `fefo`)
outbound_expired	integer	No	Outbound expiration threshold (min 0)
inbound_expired	integer	No	Inbound expiration threshold (min 0)
outer_barcode	string	No	Outer packaging barcode (max 100 characters)
advance_qc	boolean	No	Enable advance quality control
production_batch	boolean	No	Enable production batch tracking
cold_storage	boolean	No	Requires cold storage
is_fake	boolean	No	Mark as fake/dummy product
is_pre_order	boolean	No	Enable pre-order
pre_order_rules	string	No	Pre-order rules description
featured_image_uuid	string	No	Featured image UUID (UUID format)
additional_images	array	No	Array of additional image UUIDs (max 5 items)
additional_images[]	string	No	Additional image UUID (UUID format)
product_video_uuid	string	No	Product video UUID (UUID format)
bundle_items	array	Conditional	Required if `is_bundle` = `true` (minimum 1 item)
bundle_items[].sku_id	integer	Yes	Product ID included in bundle (must exist in tenant)
bundle_items[].quantity	integer	Yes	Quantity per bundle (min 1)

Request Body:

json

{
  "category_id": 2,
  "name": "Off Mercy Sample 3",
  "sku": "MASKIV-SAMPLE 3",
  "barcode": "MASKIV-SAMPLE 3",
  "brand": "Maternal",
  "description": "White 16s cotton long sleeve T-shirts, open-end yarn, 100% cotton, tubular fit, seamless double needle 2cm collar, taped neck and shoulders, satin & cotton label, rib cuffs, double needle bottom hem, multi color plastisol ink screen printing.",
  "product_type": "physical",
  "published_price": 200000.00,
  "cost_price": 199000.00,
  "weight": 10.00,
  "width": 10.00,
  "height": 10.00,
  "length": 10.00,
  "status": "published",
  "is_bundle": false,
  "is_managed_by_fulfillment": false,
  "fulfillment_manage_by": null,
  "outbound_expired": 0,
  "inbound_expired": 0,
  "outer_barcode": null,
  "advance_qc": false,
  "production_batch": false,
  "cold_storage": false,
  "created_by": "maternal",
  "updated_by": "maternal",
  "deleted_by": null,
  "deleted_at": null,
  "created_at": "2025-10-10 06:42:04",
  "updated_at": "2025-10-10 06:43:11",
  "is_fake": false,
  "is_pre_order": null,
  "pre_order_rules": null
}

Response:

json

{
  "status": 200,
  "message": "Ok",
  "data": {
      "product_id": 12,
      "sku": "MASKIV-SAMPLE 3",
      "name": "Off Mercy Sample 3",
      "description": "White 16s cotton long sleeve T-shirts, open-end yarn, 100% cotton, tubular fit, seamless double needle 2cm collar, taped neckand shoulders, satin & cotton label, rib cuffs, double needle bottom hem, multi color plastisol ink screen printing.",
      "published_price": "200000.00",
      "cost_price": "199000.00",
      "weight": "10.00",
      "width": "10.00",
      "height": "10.00",
      "length": "10.00",
      "status": "published",
      "is_bundle": false,
      "category_id": 2,
      "category_name": "Fashion",
      "volume": 1000,
      "media": []
  },
  "errors": null,
  "request_id": "70603908-05fd-4601-b5db-0105a369bdd3"
}

3. Update Item

Update an existing item's information.

Endpoint: PUT /api/partner/v1/items/{item}

Headers:

Authorization: {token} (required)
X-Tenant-Id: {tenant_id} (required)
Content-Type: multipart/form-data (required)

Request Body:

Parameter	Type	Required	Description
name	string	Yes	Product name (max 255 characters)
sku	string	Yes	Unique product SKU (max 100 characters, unique per tenant, excluding current product)
barcode	string	No	Unique product barcode (max 100 characters, unique per tenant, excluding current product, cannot duplicate non-null barcode)
description	string	Yes	Product description
category_id	integer	Yes	Category ID (must exist in tenant categories)
brand	string	No	Product brand (max 100 characters)
supplier	string	No	Supplier name (max 100 characters)
product_type	string	Yes	Product type (`physical`, `digital`)
status	string	Yes	Product status (`published`, `draft`, `archived`)
is_bundle	boolean	Yes	Define whether product is a bundle
weight	number	Conditional	Required if `product_type` = `physical` (min 0)
width	number	Conditional	Required if `product_type` = `physical` (min 0)
height	number	Conditional	Required if `product_type` = `physical` (min 0)
length	number	Conditional	Required if `product_type` = `physical` (min 0)
published_price	number	Yes	Selling price (min 0)
cost_price	number	Yes	Cost price (min 0)
is_managed_by_fulfillment	boolean	Yes	Whether product is managed by fulfillment
fulfillment_manage_by	string	Conditional	Required if `is_managed_by_fulfillment` = `true` (`fifo`, `fefo`)
outbound_expired	integer	No	Outbound expiration threshold (min 0)
inbound_expired	integer	No	Inbound expiration threshold (min 0)
outer_barcode	string	No	Outer packaging barcode (max 100 characters)
advance_qc	boolean	Yes	Enable advance quality control
production_batch	boolean	Yes	Enable production batch tracking
cold_storage	boolean	Yes	Requires cold storage
is_fake	boolean	No	Mark as fake/dummy product
is_pre_order	boolean	No	Enable pre-order
pre_order_rules	string	No	Pre-order rules description
featured_image_uuid	string	No	Featured image UUID (UUID format)
additional_images	array	No	Array of additional image UUIDs
additional_images[].uuid	string	No	Additional image UUID (UUID format)
product_video_uuid	string	No	Product video UUID (UUID format)
remove_featured_image	boolean	No	Remove current featured image if `true`
remove_additional_images	boolean	No	Remove all additional images if `true`
remove_product_video	boolean	No	Remove current product video if `true`
bundle_items	array	Conditional	Required if `is_bundle` = `true`
bundle_items[].sku_id	integer	Yes	Product ID included in bundle (must exist in tenant)
bundle_items[].quantity	integer	Yes	Quantity per bundle (min 1)

Example Request:

json

{
  "category_id": 2,
  "name": "Off Mercy Sample 3",
  "sku": "MASKIV-SAMPLE 3",
  "barcode": "MASKIV-SAMPLE 3",
  "brand": "Maternal",
  "description": "White 16s cotton long sleeve T-shirts, open-end yarn, 100% cotton, tubular fit, seamless double needle 2cm collar, taped neck and shoulders, satin & cotton label, rib cuffs, double needle bottom hem, multi color plastisol ink screen printing.",
  "product_type": "physical",
  "published_price": 200000.00,
  "cost_price": 199000.00,
  "weight": 10.00,
  "width": 10.00,
  "height": 10.00,
  "length": 10.00,
  "status": "published",
  "is_bundle": false,
  "is_managed_by_fulfillment": false,
  "fulfillment_manage_by": null,
  "outbound_expired": 0,
  "inbound_expired": 0,
  "outer_barcode": null,
  "advance_qc": false,
  "production_batch": false,
  "cold_storage": false,
  "created_by": "maternal",
  "updated_by": "maternal",
  "deleted_by": null,
  "deleted_at": null,
  "created_at": "2025-10-10 06:42:04",
  "updated_at": "2025-10-10 06:43:11",
  "is_fake": false,
  "is_pre_order": null,
  "pre_order_rules": null
}

Example Response:

json

{
  "status": 200,
  "message": "Ok",
  "data": {
      "product_id": 12,
      "sku": "MASKIV-SAMPLE 3",
      "name": "Off Mercy Sample 3",
      "description": "White 16s cotton long sleeve T-shirts, open-end yarn, 100% cotton, tubular fit, seamless double needle 2cm collar, taped neckand shoulders, satin & cotton label, rib cuffs, double needle bottom hem, multi color plastisol ink screen printing.",
      "published_price": "200000.00",
      "cost_price": "199000.00",
      "weight": "10.00",
      "width": "10.00",
      "height": "10.00",
      "length": "10.00",
      "status": "published",
      "is_bundle": false,
      "category_id": 2,
      "category_name": "Fashion",
      "volume": 1000,
      "media": []
  },
  "errors": null,
  "request_id": "70603908-05fd-4601-b5db-0105a369bdd3"
}

4. Get List of Items

Retrieve a paginated list of your items.

Endpoint: GET /api/partner/v1/items

Headers:

Authorization: {token} (required)
X-Tenant-Id: {tenant_id} (required)

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Items per page (default: 10, max: 100)
search	string	No	Search by item name or SKU
category	string	No	Filter by category
status	string	No	Filter by status (published, draft)
sort_by	string	No	Sort by (name, price, created_at, updated_at)
sort_order	string	No	Sort order (asc, desc)

Example Request:

bash

curl -X GET "{{url}}/api/partner/v1/items?page=1&per_page=10" \
  -H "Authorization: {token}" \
  -H "X-Tenant-Id: {tenant_id}"

Example Response:

json

{
  "status": 200,
  "message": "Ok",
  "data": {
    "items": [
      {
        "product_id": 1,
        "sku": "ABC001",
        "name": "Produk Pertama",
        "description": "Lorem Ipsum",
        "published_price": "10000.00",
        "cost_price": "1000.00",
        "weight": "200.00",
        "width": "10.00",
        "height": "10.00",
        "length": "10.00",
        "status": "published",
        "is_bundle": false,
        "category_id": 4,
        "media_count": 1,
        "primary_image": "http://localhost:7000/minio/medio/tenantca539d2f-bc3f-4786-9362-6b1f7d0e8372/products/assets/fc95a4bf-3d31-4a7d-831f-2514fa40d002.jpeg",
        "category_name": "Kecantikan & Kesehatan",
        "media": [
          {
            "id": 1,
            "product_id": 1,
            "media_type": "image",
            "media_url": "http://localhost:7000/minio/medio/tenantca539d2f-bc3f-4786-9362-6b1f7d0e8372/products/assets/fc95a4bf-3d31-4a7d-831f-2514fa40d002.jpeg",
            "media_name": "bronze.jpeg",
            "media_description": null,
            "sort_order": 0,
            "is_primary": true,
            "metadata": "\"{\\\"uuid\\\":\\\"fc95a4bf-3d31-4a7d-831f-2514fa40d002\\\",\\\"file_size\\\":9676,\\\"file_path\\\":\\\"tenantca539d2f-bc3f-4786-9362-6b1f7d0e8372\\\\\\/products\\\\\\/assets\\\\\\/fc95a4bf-3d31-4a7d-831f-2514fa40d002.jpeg\\\"}\"",
            "deleted_at": null,
            "created_at": "2025-08-25T03:29:08.000000Z",
            "updated_at": "2025-08-25T03:29:08.000000Z"
          }
        ],
        "bundle_items": []
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1
    }
  },
  "errors": null,
  "request_id": "c6e2b504-63c9-46b2-a037-9168fc8a4a04"
}

5. Get Item Details

Retrieve detailed information for a specific item.

Endpoint: GET /api/partner/v1/items/{item_id}

Headers:

Authorization: {token} (required)
X-Tenant-Id: {tenant_id} (required)

Example Request:

bash

curl -X GET "{{url}}/api/partner/v1/items/item_123" \
  -H "Authorization: {token}" \
  -H "X-Tenant-Id: {tenant_id}"

Example Response:

json

{
  "status": 200,
  "message": "Ok",
  "data": {
    "product_id": 1,
    "sku": "ABC001",
    "name": "Produk Pertama",
    "description": "Lorem Ipsum",
    "published_price": "10000.00",
    "cost_price": "1000.00",
    "weight": "200.00",
    "width": "10.00",
    "height": "10.00",
    "length": "10.00",
    "status": "published",
    "is_bundle": false,
    "category_id": 4,
    "category_name": "Kecantikan & Kesehatan",
    "volume": 1000,
    "media": [
      {
        "id": 1,
        "product_id": 1,
        "media_type": "image",
        "media_url": "http://localhost:7000/minio/medio/tenantca539d2f-bc3f-4786-9362-6b1f7d0e8372/products/assets/fc95a4bf-3d31-4a7d-831f-2514fa40d002.jpeg",
        "media_name": "bronze.jpeg",
        "media_description": null,
        "sort_order": 0,
        "is_primary": true,
        "metadata": "\"{\\\"uuid\\\":\\\"fc95a4bf-3d31-4a7d-831f-2514fa40d002\\\",\\\"file_size\\\":9676,\\\"file_path\\\":\\\"tenantca539d2f-bc3f-4786-9362-6b1f7d0e8372\\\\\\/products\\\\\\/assets\\\\\\/fc95a4bf-3d31-4a7d-831f-2514fa40d002.jpeg\\\"}\"",
        "deleted_at": null,
        "created_at": "2025-08-25T03:29:08.000000Z",
        "updated_at": "2025-08-25T03:29:08.000000Z"
      }
    ]
  },
  "errors": null,
  "request_id": "47406059-08af-402f-a8ba-36fb520a1090"
}

6. Get Item Stock

Retrieve stock information for items.

Endpoint: GET /api/partner/v1/items/:id/stocks

Headers:

Authorization: {token} (required)
X-Tenant-Id: {tenant_id} (required)

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	Filter by item ID

Example Request:

bash

curl -X GET "{{url}}/api/partner/v1/items/:id/stocks" \
  -H "Authorization: {token}" \
  -H "X-Tenant-Id: {tenant_id}"

Example Response:

json

{
  "status": 200,
  "message": "Ok",
  "data": {
    "product_id": "1",
    "sku": "ABC001",
    "name": "Produk Pertama",
    "available_stock": 29,
    "allocated_stock": 9,
    "damaged_stock": 0,
    "total_stock": 38,
    "stock_status": "in_stock",
    "last_updated": "2025-09-11T14:55:01.000000Z",
    "stock_details": [
      {
        "stock_id": 1,
        "location_id": 1,
        "location_name": "Warehouse Pusat",
        "grid_id": 1,
        "grid_name": "Grid 1",
        "onhand": 38,
        "available": 29,
        "allocated": 9,
        "damaged": 0,
        "is_freeze": false,
        "updated_at": "2025-09-11T14:55:01.000000Z"
      }
    ]
  },
  "errors": null,
  "request_id": "ea24507c-2737-406d-8759-2dbb82a08c81"
}

Items API Reference ​

Overview ​

Authentication ​

Endpoints ​

1. Get Category List ​

2. Create Item ​

3. Update Item ​

4. Get List of Items ​

5. Get Item Details ​

6. Get Item Stock ​

Items API Reference

Overview

Authentication

Endpoints

1. Get Category List

2. Create Item

3. Update Item

4. Get List of Items

5. Get Item Details

6. Get Item Stock