Browse the docs ▾

Tutorials

Build an online store

Add a catalogue, arrange it into collections, design the shop around it, and leave checkout, stock and order handling to Opmiz.

The brief: "Kaveri Handlooms sells sarees and kurtas. I have a spreadsheet of 40 products with photos."
You'll end with a shop with its products on sale, a collection menu, a designed home page and a working cart. The owner still has to turn on a way to get paid.
You need the catalogue permissions. Check the plan's product limit against the catalogue size, and call get_business_details for the store's currency, since an app can't change it.

1. Know what Opmiz handles

The cart, checkout, order records, stock counts and order emails already exist. Your job is the catalogue and the shop's design. Don't try to build a checkout or a cart page out of elements.

2. Prepare the categories

A category groups products, and it can hold extra fields, like a saree's fabric. If you want fields, add them first with add_category_fields, because import rows must use fields that already exist. Giving it a category name creates the category. Fields need a plan that has them, and list_categories shows whether yours does.

3. Import the products

Use import_products. For more than a few products, call it without items to get a link, then send a file from your shell, so the catalogue doesn't pass through the conversation. Make the first call with dry_run: true, send the file and read get_import: this checks every row without making anything. Then call again for a new link, since each link takes one file.

idempotency_key

Give every product one, such as its handle in the old system, so that sending the file again doesn't make duplicates.

Prices

Prices and MRPs are in the store's currency and include tax. With tax_pct 18, a price of 118 is 100 plus 18 tax.

Variants

Give variants: [{name, price, stock…}], or price and stock directly for a single variant.

Collections

Named collections are made if new. A collection made from a category fills itself from that category, so give those products the category instead.

Images

https addresses are copied in.
Read the results with get_import. Products arrive off sale.

4. Put them on sale with the owner's yes

preview_item_publish {import_id} gives one token for the whole import. Tell the owner how many products it covers and ask. Then call publish_item with the token. This changes the live shop at once if the site is live. On a site that is already live, a preview can warn that old pages would mix with the new catalogue until the draft is published. If it does, offer to publish both together.

5. Arrange what the shop shows

The menu, the featured collections and the product sections belong to the store, not the design. get_store_lists reads them, and preview_store_lists and save_store_lists change them. Use list_collections for the ids.
To set a hand-picked order, use preview_collection_order and save_collection_order, then set the section's sort to arranged.

6. Design the shop

Grids and rows

add_element with kind: "list" and a source of store.featured_collections, store.header_collections or store._ps_id_<section_id>.listings. Add elements to its card_ref and bind them to listData.title, listData.price, listData.cover_img_url and so on.

Product links

Use the url from list_products or list_collections. A product address takes its listing id, not its product id.

Add to cart

set_handlers with po.addToCart. Use this_row in a list of products and this_page on the product page, and set go_to_checkout: true for Buy now. A product with options to choose needs its product page instead.

Cart icon

Wrap the icon in a container, and give it po.showCart.

Category fields

get_category_fields gives the path to bind on a product page, so fabric or care can have its own row.
The ecommerce guide covers these patterns in more depth.

7. Check with screenshots

get_page_screenshot shows category_page (give a collection as item_id) and product_page (give a product as item_id) as well as your own pages. Check both at phone width.

8. Publish, then hand over

A site that sells also needs a legal name and address before its first publish, so ask for them. preview_site_publish warns if no buyer could pay. Then tell the owner what remains in the dashboard: turning on online payments, delivery fees, discount codes and a custom domain. Pay on delivery you can turn on yourself with preview_business_details, once the owner says yes. See Hand over to the owner.
To change a product after the import, use preview_product_update and save_product_update; for stock, preview_stock_adjustment and save_stock_adjustment. A product on sale changes on the shop at once, so show the owner the preview first.

One product row (NDJSON)

{ "idempotency_key": "silk-maroon",
  "name": "Kanchipuram Silk Saree",
  "category": "Sarees",
  "description": "Handwoven silk.",
  "tax_pct": 5,
  "images": [
    "https://example.com/maroon.jpg" ],
  "collections": ["Festive"],
  "fields": { "fabric": "Silk" },
  "variants": [
    { "name": "Maroon", "code": "KS-M",
      "price": 8400, "mrp": 9000,
      "stock": 3 },
    { "name": "Teal", "code": "KS-T",
      "price": 8400, "stock": 5 }
  ] }

A product grid

{ "op": "add_element",
  "kind": "list",
  "to_ref": "home/home-featured",
  "position": "last",
  "source": "store._ps_id_18.listings",
  "name": "Festive grid" }

→ "card_ref": "home/home-featured/…"

{ "op": "bind_field",
  "ref": "<a text in the card>",
  "path": "listData.price|currency" }