Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shopi.lk/llms.txt

Use this file to discover all available pages before exploring further.

shop.products.list(params?)

Returns a paginated list of visible products for the shop.
const { products, total, limit, offset } = await shop.products.list({
  limit: 12,
  offset: 0,
  sort_by: 'created_at',
  sort_order: 'desc',
});

Parameters

ParamTypeDefaultDescription
limitnumber50Max products to return (max 100)
offsetnumber0Pagination offset
categorystringFilter by category name
searchstringSearch by product name
sort_by`‘created_at''name''price''sales''updated_at’`'created_at'Sort field
sort_order`‘asc''desc’`'desc'Sort direction

Response

{
  products: Product[];
  total: number;   // total matching products (for pagination)
  limit: number;
  offset: number;
}

Product type

{
  id: string;
  shop_id: string;
  name: string;
  slug: string;
  description: string | null;
  price: number;                    // in smallest currency unit (e.g. cents)
  compare_at_price: number | null;  // original price for sale display
  category: string | null;
  images: string[];                 // array of image URLs
  is_visible: boolean;
  stock_quantity: number | null;
  track_inventory: boolean;
  sku: string | null;
  weight: number | null;
  variants: ProductVariant[] | null;
  created_at: string;
  updated_at: string;
}

Example — Product grid with pagination

let currentOffset = 0;
const PAGE_SIZE = 12;

async function loadProducts() {
  const { products, total } = await shop.products.list({
    limit: PAGE_SIZE,
    offset: currentOffset,
    sort_by: 'created_at',
    sort_order: 'desc',
  });

  renderGrid(products);

  const hasMore = currentOffset + PAGE_SIZE < total;
  loadMoreBtn.style.display = hasMore ? 'block' : 'none';
}

loadMoreBtn.addEventListener('click', () => {
  currentOffset += PAGE_SIZE;
  loadProducts();
});

Example — Category filter

async function filterByCategory(category: string) {
  const { products } = await shop.products.list({ category });
  renderGrid(products);
}
searchInput.addEventListener('input', async (e) => {
  const query = (e.target as HTMLInputElement).value;
  if (query.length < 2) return;

  const { products } = await shop.products.list({ search: query });
  renderGrid(products);
});

shop.products.getBySlug(slug)

Returns a single product by its URL slug.
const product = await shop.products.getBySlug('red-cotton-t-shirt');

Parameters

ParamTypeDescription
slugstringThe product’s URL slug

Example — Product detail page

const slug = window.location.pathname.split('/').pop()!;
const product = await shop.products.getBySlug(slug);

productName.textContent = product.name;
productPrice.textContent = formatPrice(product.price);

if (product.compare_at_price) {
  originalPrice.textContent = formatPrice(product.compare_at_price);
  saleBadge.style.display = 'block';
}

product.images.forEach(url => {
  const img = document.createElement('img');
  img.src = url;
  gallery.appendChild(img);
});
Returns ShopiError with status: 404 if the product does not exist or is not visible.