Product Variants

This page describes the request data identifiers and response structure required to list a product's variants (stock units) and inventory.

Data Identifier

{
  "dataID": "GET_PRODUCT_VARIANTS",
  "seq": 340
}
KeyDescription
dataIDData identifier GET_PRODUCT_VARIANTS
seqProduct number

HTML

<table class="table table-sm align-middle">
  <thead><tr><th>SKU</th><th>Option</th><th class="text-end">+Price</th><th class="text-end">On hand</th><th class="text-end">Reserved</th><th class="text-end">Available</th></tr></thead>
  <tbody>
    <tr v-for="v in output.variants">
      <td><code>{{ v.sku }}</code></td>
      <td>{{ v.set_label }} {{ v.combo_key }}</td>
      <td class="text-end">{{ v.price_delta }}</td>
      <td class="text-end">{{ v.quantity_on_hand }}</td>
      <td class="text-end">{{ v.quantity_reserved }}</td>
      <td class="text-end">{{ v.quantity_available }}</td>
    </tr>
  </tbody>
</table>

Response Result

{
  "product_seq": 340,
  "variants": [
    {
      "seq": 5001,
      "product_seq": 340,
      "set_seq": 12,
      "base_flg": 0,
      "combo_key": "101-103",
      "sku": "TS-TS01-WHT-V103",
      "barcode": null,
      "status": "ACTIVE",
      "price_override": null,
      "price_delta": 0,
      "combo_active": "781-783",
      "base_active": null,
      "set_label": "Color / Size",
      "quantity_on_hand": 10,
      "quantity_reserved": 0,
      "reorder_level": 2,
      "version_no": 1,
      "quantity_available": 10,
      "option_values": []
    },
    {
      "seq": 5002,
      "product_seq": 340,
      "set_seq": 12,
      "base_flg": 0,
      "combo_key": "101-104",
      "sku": "TS-TS01-WHT-V104",
      "barcode": null,
      "status": "ACTIVE",
      "price_override": null,
      "price_delta": 0,
      "combo_active": "781-784",
      "base_active": null,
      "set_label": "Color / Size",
      "quantity_on_hand": 3,
      "quantity_reserved": 0,
      "reorder_level": 2,
      "version_no": 1,
      "quantity_available": 3,
      "option_values": []
    },
    {
      "seq": 5003,
      "product_seq": 340,
      "set_seq": 12,
      "base_flg": 0,
      "combo_key": "101-105",
      "sku": "TS-TS01-WHT-V105",
      "barcode": null,
      "status": "ACTIVE",
      "price_override": null,
      "price_delta": 2000,
      "combo_active": "781-785",
      "base_active": null,
      "set_label": "Color / Size",
      "quantity_on_hand": 0,
      "quantity_reserved": 0,
      "reorder_level": 2,
      "version_no": 1,
      "quantity_available": 0,
      "option_values": []
    }
  ],
  "total_variant_count": 6
}
KeyDescription
product_seqProduct number
variantsOption rows
variants[n].seqRow number. variant_seq for UPDATE_INVENTORY
variants[n].set_seqOption set number
variants[n].set_labelOption set name
variants[n].base_flg1 for the base row of a product without options
variants[n].combo_keyCombination key (value seqs joined by -)
variants[n].skuSKU
variants[n].statusACTIVE / INACTIVE
variants[n].price_deltaExtra amount
variants[n].quantity_on_handStock on hand
variants[n].quantity_reservedReserved quantity
variants[n].quantity_availableAvailable = on hand − reserved
variants[n].reorder_levelLow-stock level. null if not set
variants[n].version_noStock version. Send it back when updating
total_variant_countNumber of rows
  • Use this for admin stock screens. On a storefront detail page, GET_PRODUCT option_sets[n].rows (with option_text and orderable) is easier.
  • Stock: available = on hand (quantity_on_hand) − reserved (quantity_reserved). The server adds reservations when an order is placed and releases them on shipping or cancellation.
  • variants[n].option_values is empty since v1.0.35. Read option names from GET_PRODUCT option_sets.
  • 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. An unknown product returns an empty array.

Example

SKUOption+PriceOn handReservedAvailable
TS-TS01-WHT-V103Color / Size 101-103010010
TS-TS01-WHT-V104Color / Size 101-1040303
TS-TS01-WHT-V105Color / Size 101-1052,000000 Low
<script setup>
const { output } = await useNuxtApp().$connector({ dataID: 'GET_PRODUCT_VARIANTS', seq: 340 })
const low = v => v.reorder_level !== null && v.quantity_available <= v.reorder_level
</script>

<template>
  <table class="table table-sm align-middle">
    <thead><tr><th>SKU</th><th>Option</th><th class="text-end">+Price</th><th class="text-end">On hand</th><th class="text-end">Reserved</th><th class="text-end">Available</th></tr></thead>
    <tbody>
      <tr v-for="v in output.variants" :key="v.seq">
        <td><code>{{ v.sku }}</code></td>
        <td>{{ v.set_label }} <span class="text-secondary">{{ v.combo_key }}</span></td>
        <td class="text-end">{{ v.price_delta.toLocaleString() }}</td>
        <td class="text-end">{{ v.quantity_on_hand }}</td>
        <td class="text-end">{{ v.quantity_reserved }}</td>
        <td class="text-end">{{ v.quantity_available }} <span v-if="low(v)" class="badge bg-warning text-dark">Low</span></td>
      </tr>
    </tbody>
  </table>
</template>
<?php
$output = $connector->request(['dataID' => 'GET_PRODUCT_VARIANTS', 'seq' => 340]);
?>
<table class="table table-sm">
  <tr><th>SKU</th><th>Option</th><th>On hand</th><th>Reserved</th><th>Available</th></tr>
<?php foreach ($output['variants'] as $v) { ?>
  <tr>
    <td><code><?= htmlspecialchars((string)$v['sku']) ?></code></td>
    <td><?= htmlspecialchars($v['set_label']) ?> <?= $v['combo_key'] ?></td>
    <td><?= $v['quantity_on_hand'] ?></td>
    <td><?= $v['quantity_reserved'] ?></td>
    <td><?= $v['quantity_available'] ?></td>
  </tr>
<?php } ?>
</table>