Product List

This page describes the request data identifiers and response structure required to build a product list page.

Data Identifier

{
  "dataID": "GET_PRODUCT_LIST",
  "page": 1,
  "list_per_page": 20,
  "block_per_page": 5,
  "page_link_url": "/shop",
  "page_link_hash": "",
  "status": "ACTIVE",
  "category_seq": 2,
  "search_keyword": "",
  "sort_key": "recent"
}
KeyDescription
dataIDData identifier GET_PRODUCT_LIST
pagePage number
list_per_pageRows per page (default 20)
block_per_pagePage links per block (default 7)
page_link_urlBase URL for pagination links
page_link_hashHash appended to pagination links
statusDRAFT / ACTIVE / INACTIVE / ARCHIVED. Use ACTIVE on a storefront
product_typeProduct type filter, e.g. PHYSICAL
category_seqOnly products linked to this category
search_keywordPartial match on name, code, brand, summary
sort_keyrecent / modified / name / price_asc / price_desc / stock_asc
stockout (sold out) / low / unset (not tracked)
deletedY also returns deleted products (signed in)

HTML

<div class="row g-3">
  <div class="col-6 col-md-3" v-for="p in output.product_list">
    <a :href="'/shop/product?seq=' + p.seq" class="card h-100 text-decoration-none text-dark">
      <img v-if="p.primary_image" :src="p.primary_image" class="card-img-top" :alt="p.name">
      <div class="card-body">
        <div class="small text-secondary">{{ p.primary_category }}</div>
        <div class="fw-bold">{{ p.name }}</div>
        <div v-if="p.list_price > p.base_price" class="small text-secondary"><del>{{ p.list_price }}</del></div>
        <div class="fw-bold">{{ p.base_price }} {{ p.currency }}</div>
        <span v-if="p.available_stock === 0" class="badge bg-secondary">Sold out</span>
      </div>
    </a>
  </div>
</div>

Response Result

{
  "search_keyword": "",
  "pagination": {
    "total_result_num": 1,
    "total_page_num": 1,
    "page": "1",
    "start_page": 1,
    "end_page": 1,
    "prev_page": 1,
    "next_page": 1
  },
  "product_list": [
    {
      "seq": 340,
      "product_code": "TS-TS01",
      "product_type": "PHYSICAL",
      "status": "ACTIVE",
      "name": "Cotton T-Shirt",
      "brand": "H:Dev+",
      "summary": "100% soft cotton tee",
      "description": "<p>180g cotton jersey</p>",
      "currency": "KRW",
      "base_price": 19000,
      "list_price": 25000,
      "option_rev": 1,
      "stock_flg": 0,
      "variant_count": 6,
      "primary_image": null,
      "available_stock": 23,
      "reorder_margin": -2,
      "primary_category": "T-Shirts"
    }
  ],
  "total_product_count": 1,
  "sort_key": "recent",
  "status_counts": {
    "all": 1,
    "ACTIVE": 1,
    "DRAFT": 0,
    "INACTIVE": 0,
    "ARCHIVED": 0
  },
  "category_list": [
    {
      "seq": 1,
      "parent_seq": null,
      "code": "APPAREL",
      "name": "Apparel",
      "depth": 0,
      "sort_order": 1,
      "status": "ACTIVE"
    },
    {
      "seq": 2,
      "parent_seq": 1,
      "code": "TSHIRTS",
      "name": "T-Shirts",
      "depth": 1,
      "sort_order": 1,
      "status": "ACTIVE"
    }
  ],
  "deleted_product_count": 2
}
KeyDescription
product_listProducts
product_list[n].seqProduct number (number)
product_list[n].product_codeProduct code
product_list[n].nameProduct name
product_list[n].statusDRAFT / ACTIVE / INACTIVE / ARCHIVED
product_list[n].base_priceSelling price (number)
product_list[n].list_priceRegular price (number). null if none
product_list[n].currencyCurrency code, e.g. KRW
product_list[n].variant_countNumber of option rows
product_list[n].available_stockTotal available stock. null if not tracked
product_list[n].primary_imageMain image URL. null if none
product_list[n].primary_categoryMain category name
paginationPaging info
total_product_countTotal products matching the filter
sort_keySort key that was applied
status_countsCounts by status (with all)
category_listCategory tree (for a filter menu)
deleted_product_countDeleted products (signed in)
  • Screen example: call with status=ACTIVE and show name and price on each card. Draw the side menu from category_list and call again with category_seq when a category is clicked.
  • Price: base_price is the selling price and list_price the regular price (null if none). With an option, price = base_price + the row's price_delta. Show a struck-through list price and discount only when list_price is greater.
  • Show a sold-out badge when available_stock is 0. null means stock is not tracked, so the product is never sold out.
  • Product status is DRAFT, ACTIVE (on sale), INACTIVE (paused) or ARCHIVED. Storefront lists, widgets and orders accept ACTIVE only.
  • Error codes — errors also come back as HTTP 200. Check result:false, then error_code (string) and error_message.
  • This read API needs no sign-in. With no match, product_list is an empty array.

Example

T-Shirts
Cotton T-Shirt
₩25,000 24%
₩19,000
Kitchen
Ceramic Mug
₩12,000
Sold out

2 products

<script setup>
const requestData = {
  dataID: 'GET_PRODUCT_LIST', page: 1, list_per_page: 20, page_link_url: '/shop', page_link_hash: '',
  status: 'ACTIVE', category_seq: 2, search_keyword: '', sort_key: 'recent'
}
const { output } = await useNuxtApp().$connector(requestData)
const money = (v, c) => new Intl.NumberFormat('ko-KR', { style: 'currency', currency: c }).format(v)
// Show the regular price only when it is higher than the selling price
const hasDiscount = p => p.list_price !== null && p.list_price > p.base_price
const discountRate = p => Math.round((1 - p.base_price / p.list_price) * 100)
</script>

<template>
  <div class="row g-3">
    <div class="col-6 col-md-3" v-for="p in output.product_list" :key="p.seq">
      <NuxtLink :to="`/shop/product?seq=${p.seq}`" class="card h-100 text-decoration-none text-dark">
        <img v-if="p.primary_image" :src="p.primary_image" class="card-img-top" :alt="p.name">
        <div class="card-body">
          <div class="small text-secondary">{{ p.primary_category }}</div>
          <div class="fw-bold">{{ p.name }}</div>
          <div v-if="hasDiscount(p)" class="small text-secondary">
            <del>{{ money(p.list_price, p.currency) }}</del> <span class="text-danger">{{ discountRate(p) }}%</span>
          </div>
          <div class="fw-bold">{{ money(p.base_price, p.currency) }}</div>
          <span v-if="p.available_stock === 0" class="badge bg-secondary">Sold out</span>
        </div>
      </NuxtLink>
    </div>
  </div>
  <p class="text-secondary mt-3">{{ output.total_product_count }} products</p>
</template>
<?php
$requestData = [
    'dataID'         => 'GET_PRODUCT_LIST',
    'page'           => $_GET['page'] ?? 1,
    'list_per_page'  => 20,
    'page_link_url'  => '/shop',
    'page_link_hash' => '',
    'status'         => 'ACTIVE',          // DRAFT | ACTIVE | INACTIVE | ARCHIVED
    'category_seq'   => 2,                 // includes products linked to this category
    'search_keyword' => $_GET['q'] ?? '',  // name, product_code, brand, summary
    'sort_key'       => 'recent',          // recent | modified | name | price_asc | price_desc | stock_asc
];
$output = $connector->request($requestData);
?>
<div class="row g-3">
<?php foreach ($output['product_list'] as $p) { ?>
  <div class="col-6 col-md-3">
    <a href="/shop/product?seq=<?= $p['seq'] ?>" class="card h-100 text-decoration-none text-dark">
      <div class="card-body">
        <div class="fw-bold"><?= htmlspecialchars($p['name']) ?></div>
        <?php if ($p['list_price'] !== null && $p['list_price'] > $p['base_price']) { ?>
          <del class="small text-secondary"><?= number_format($p['list_price']) ?></del>
        <?php } ?>
        <div class="fw-bold"><?= number_format($p['base_price']) ?> <?= $p['currency'] ?></div>
        <?php if ($p['available_stock'] === 0) { ?><span class="badge bg-secondary">Sold out</span><?php } ?>
      </div>
    </a>
  </div>
<?php } ?>
</div>