Browse the docs ▾

Agent guides

Build ecommerce experiences

The catalogue and checkout belong to the store. Your design shows them, and changes to store data are often live at once.

Where things live

Products and variants

The catalogue. Add them with import_products, change them with preview_product_update, and read them with list_products and get_product.

Categories

Group products, and can hold fields. Read them with list_categories.

Collections

Either made from categories or hand-picked. Only hand-picked ones can be arranged, using preview_collection_order.

Menu, featured and product sections

The store's lists. Use get_store_lists and preview_store_lists. These aren't in the draft.

Cart and checkout

Opmiz's own. Style around them. There are no tools to change their steps.

Stock

Counted by Opmiz, and checked again at checkout. Read it with list_stock, and adjust it with preview_stock_adjustment.

Patterns

A home page grid

Make a product section with preview_store_lists. Its binding is the source for add_element kind: "list", or for set_list_source.

A carousel of products

duplicate_section a section with a product carousel, then set_list_source its carousel to the new section. Tune it with set_settings.

A menu of collections

A list with source store.header_collections in the header.

Sort order

A section's sort takes the options in get_store_lists. Use arranged to follow the collection's own order.

Linking to one product

Use the url from list_products. A link to a product that's missing, archived or off sale stops the site publishing, and the error names each one.

Add to cart

po.addToCart with this_row in a list you made, and this_page on the product page. It sets the quantity rather than adding to it.

Buy now

po.addToCart with go_to_checkout: true.

Products with options

Link to the product page. Adding from a card skips option choices, booking slots and customisation.

Category fields

Bind with the paths from get_category_fields, and hide empty rows with a field condition.
Cards on a category page are a shared part, so this_row isn't offered there.

What's live at once

Store data has no draft. Putting products on sale, changing them, adjusting stock, archiving, store lists, a collection's products and order, and product field values all change a live shop as soon as you save. Each has a preview, and each needs the owner's yes.
On a live site with an unpublished draft, a preview can lead with live_warning: the live site would mix old pages with the new catalogue until the draft is published. Say so and offer to publish together.

What needs the dashboard

Getting paid

Turning on online payments. An app can turn on Pay on delivery with preview_business_details, after the owner's yes. The first publish preview warns if buyers can't pay.

Selling rules

Discount codes, delivery fees, free delivery, minimum order, pickup.

After the sale

Cancellations and returns. Apps can only move an order forward: ready_to_ship, shipped, delivered. A step usually emails the buyer, and the preview's effects says whether it will, so preview it first.

Good product data

Import prices that include tax, in the store's currency. Keep description to plain words and put HTML tables and lists in specifications. Use real product photos at consistent proportions, and make each code unique, since a used code is refused. If the owner gave you no prices or stock, ask rather than guess. A wrong number can reach a real buyer.

A new product section

{
  "name": "preview_store_lists",
  "arguments": {
    "org_id": 1042,
    "product_sections": [
      { "section_id": 18 },
      { "name": "Festive picks",
        "collection_id": 233,
        "sort": "arranged" }
    ]
  }
}

→ before, after, warnings, publish_token

(a section left out comes off the store,
 so send all of them)

Add to cart on a card

{ "op": "set_handlers",
  "ref": "<a button in the card>",
  "handlers": [{
    "event": "click",
    "action": "po.addToCart",
    "params": {
      "product": "this_row",
      "quantity": 1,
      "show_cart": true } }] }