Appearance
Kit: the shop
A shop: products with options, variants and customizations, stocked by SKU and sent by the owner's zones and rates.
kind: shop, version 1. A shop is not a kind of business: this is the shop module's kit, in contract 3's words, laid over a contract-3 site by npx @jtakeit/astro add shop — beside a booking kit or without one — and never by jtk create --kit. What a kit is: kits.
Taken whole, with the business's facts put into it; anything taken out is a decision said to the developer and written in the brief.
Ask
The facts only the business has. Never fill them in; what is not answered is NEEDS CLIENT.
- the catalogue: what it sells and roughly how many products — a spreadsheet, or a WooCommerce or Shopify export, with the SKUs and the stock it already has
- variants and customizations: whether any product has variants (sizes, colours) or customizations (a name on a tag) — customizations are written only for the products that have them
- the country it sends from: the zone the kit starts with — from the address; say it back rather than asking
- where it ships, and each method's price: flat or by weight, and free above a total
- pick-up: whether the business offers it, and where to collect
- VAT: which products are not ordinary goods — books, food, children's clothing — where the business charges it
Taken by default — say it, get a yes
What this kit chose for the shop. Say each back to the developer and get a yes: a «no» to stock is a product's tracked: false, and the last is the owner's to switch on.
- Stock is counted for every product (
tracked), and a product nobody stocked is sold out until its count is set — or is any made to order (tracked: false)? - A checkout holds what it sells for 31 minutes while the buyer pays on Stripe's page; the last item goes to the first who goes on to pay.
- Every order is paid online — by card, Apple Pay or Google Pay — a pick-up too.
- The buyer gets a confirmation, and an on its way email with its tracking link, or ready for pick-up, when the owner marks the order fulfilled.
- New orders go where the site's enquiries go — the Telegram chat or the email a person links in the panel, which an agent cannot link.
- VAT and paying in one's own currency are off until the owner turns them on, on the site's Payments screen.
Collection
Where a product's page and the listing are is the collection's contract-3 route.
| collection | the shop's | uk | en | de | an entry is | where |
|---|---|---|---|---|---|---|
products | products | Товари | Products | Produkte | product | "route": {"detail":"/shop/{slug}","listing":"/shop"} |
The product type
Every field is client_editable and every label is in the eight languages; the table says them in English. The fields from options on are what the shop reads of a product, and what its card draws in the panel: no entry type's form places them (modules).
| field | kind | en | rules |
|---|---|---|---|
title | text | Name | required; at most 120 |
description | textarea | Description | at most 4000 |
cover | media | Cover | — |
pictures | media | Pictures | several |
options | list | Options | rows of name (text, required), values (list, required; rows of label (text, required)) |
variants | list | Variants | required; rows of sku (sku, required), price (money, required), weight (number, whole), picks (picks), on_sale (bool) |
customizations | list | Customizations | rows of name (text, required), kind (select, required; one of choice, yes_no, text), required (bool), max (number, whole), choices (list, rows of label (text, required), adds (money)), adds (money) |
tracked | bool | Counted | — |
size_class | select | Shipping size | one of letter, parcel, bulky |
tax_code | text | Tax code | — |
tariff_number | text | Customs tariff number | — |
made_in | text | Made in | — |
Settings
The keys of settings in jtk/modules/shop.json, {"v": 1, "settings": {…}}, as jtk add shop writes them: one zone, whose countries is the site's country, and two methods with no price. kit and kit_version are written beside them. The modules reference says what each does; every name is in the eight languages in the kit, and in the site's in the file.
| row | key | in the zone | en | what it has |
|---|---|---|---|---|
| zone | home | — | Domestic | no country: the business's, from its address |
| method | post | home | Post | no price yet: a draft, which preflight names |
| method | pickup | home | Pick-up | "pickup": true: nothing is sent, so nothing is priced |
The kit, whole
As GET /v1/kits/shop serves it, in contract 3's words — which a booking kit's GET /v1/kits/<kind> is not. Not a file to copy into a site: npx @jtakeit/astro add shop lays it, and writes the version above as kit_version.
json
{
"kind": "shop",
"module": "shop",
"contract": 3,
"version": 1,
"sum": "8e2e16ea7500",
"about": "A shop: products with options, variants and customizations, stocked by SKU and sent by the owner's zones and rates.",
"ask": [
"the catalogue: what it sells and roughly how many products — a spreadsheet, or a WooCommerce or Shopify export, with the SKUs and the stock it already has",
"variants and customizations: whether any product has variants (sizes, colours) or customizations (a name on a tag) — customizations are written only for the products that have them",
"the country it sends from: the zone the kit starts with — from the address; say it back rather than asking",
"where it ships, and each method's price: flat or by weight, and free above a total",
"pick-up: whether the business offers it, and where to collect",
"VAT: which products are not ordinary goods — books, food, children's clothing — where the business charges it"
],
"catalogue": {
"blocks": [
{
"type": "product",
"v": 1,
"label": {
"uk": "Товар",
"en": "Product",
"de": "Produkt",
"ru": "Товар",
"es": "Producto",
"it": "Prodotto",
"pt": "Produto",
"fr": "Produit"
},
"fields": [
{
"key": "title",
"label": {
"uk": "Назва",
"en": "Name",
"de": "Name",
"ru": "Название",
"es": "Nombre",
"it": "Nome",
"pt": "Nome",
"fr": "Nom"
},
"kind": "text",
"required": true,
"max": 120,
"client_editable": true
},
{
"key": "description",
"label": {
"uk": "Опис",
"en": "Description",
"de": "Beschreibung",
"ru": "Описание",
"es": "Descripción",
"it": "Descrizione",
"pt": "Descrição",
"fr": "Description"
},
"kind": "textarea",
"max": 4000,
"client_editable": true
},
{
"key": "cover",
"label": {
"uk": "Обкладинка",
"en": "Cover",
"de": "Titelbild",
"ru": "Обложка",
"es": "Portada",
"it": "Copertina",
"pt": "Capa",
"fr": "Couverture"
},
"kind": "media",
"client_editable": true
},
{
"key": "pictures",
"label": {
"uk": "Фотографії",
"en": "Pictures",
"de": "Bilder",
"ru": "Фотографии",
"es": "Imágenes",
"it": "Immagini",
"pt": "Imagens",
"fr": "Images"
},
"kind": "media",
"multiple": true,
"client_editable": true
},
{
"key": "options",
"label": {
"uk": "Параметри",
"en": "Options",
"de": "Optionen",
"ru": "Параметры",
"es": "Opciones",
"it": "Opzioni",
"pt": "Opções",
"fr": "Options"
},
"kind": "list",
"of": [
{
"key": "name",
"label": {
"uk": "Назва",
"en": "Name",
"de": "Name",
"ru": "Название",
"es": "Nombre",
"it": "Nome",
"pt": "Nome",
"fr": "Nom"
},
"kind": "text",
"required": true,
"client_editable": true
},
{
"key": "values",
"label": {
"uk": "Значення",
"en": "Values",
"de": "Werte",
"ru": "Значения",
"es": "Valores",
"it": "Valori",
"pt": "Valores",
"fr": "Valeurs"
},
"kind": "list",
"required": true,
"of": [
{
"key": "label",
"label": {
"uk": "Підпис",
"en": "Label",
"de": "Bezeichnung",
"ru": "Подпись",
"es": "Etiqueta",
"it": "Etichetta",
"pt": "Etiqueta",
"fr": "Libellé"
},
"kind": "text",
"required": true,
"client_editable": true
}
],
"client_editable": true
}
],
"client_editable": true
},
{
"key": "variants",
"label": {
"uk": "Варіанти",
"en": "Variants",
"de": "Varianten",
"ru": "Варианты",
"es": "Variantes",
"it": "Varianti",
"pt": "Variantes",
"fr": "Variantes"
},
"kind": "list",
"required": true,
"of": [
{
"key": "sku",
"label": {
"uk": "Артикул",
"en": "SKU",
"de": "Artikelnummer",
"ru": "Артикул",
"es": "Referencia",
"it": "Codice articolo",
"pt": "Referência",
"fr": "Référence"
},
"kind": "sku",
"required": true,
"client_editable": true
},
{
"key": "price",
"label": {
"uk": "Ціна",
"en": "Price",
"de": "Preis",
"ru": "Цена",
"es": "Precio",
"it": "Prezzo",
"pt": "Preço",
"fr": "Prix"
},
"kind": "money",
"required": true,
"client_editable": true
},
{
"key": "weight",
"label": {
"uk": "Вага, г",
"en": "Weight (g)",
"de": "Gewicht (g)",
"ru": "Вес, г",
"es": "Peso (g)",
"it": "Peso (g)",
"pt": "Peso (g)",
"fr": "Poids (g)"
},
"kind": "number",
"integer": true,
"client_editable": true
},
{
"key": "picks",
"label": {
"uk": "Комбінація",
"en": "Combination",
"de": "Auswahl",
"ru": "Комбинация",
"es": "Combinación",
"it": "Combinazione",
"pt": "Combinação",
"fr": "Combinaison"
},
"kind": "picks",
"client_editable": true
},
{
"key": "on_sale",
"label": {
"uk": "У продажу",
"en": "On sale",
"de": "Im Verkauf",
"ru": "В продаже",
"es": "A la venta",
"it": "In vendita",
"pt": "À venda",
"fr": "En vente"
},
"kind": "bool",
"client_editable": true
}
],
"client_editable": true
},
{
"key": "customizations",
"label": {
"uk": "Персоналізація",
"en": "Customizations",
"de": "Personalisierungen",
"ru": "Персонализация",
"es": "Personalizaciones",
"it": "Personalizzazioni",
"pt": "Personalizações",
"fr": "Personnalisations"
},
"kind": "list",
"of": [
{
"key": "name",
"label": {
"uk": "Що питають у покупця",
"en": "What the buyer is asked",
"de": "Was der Käufer gefragt wird",
"ru": "О чём спрашивают покупателя",
"es": "Lo que se pregunta al comprador",
"it": "Cosa si chiede all’acquirente",
"pt": "O que se pergunta ao comprador",
"fr": "Ce que l’on demande à l’acheteur"
},
"kind": "text",
"required": true,
"client_editable": true
},
{
"key": "kind",
"label": {
"uk": "Вид",
"en": "Kind",
"de": "Art",
"ru": "Вид",
"es": "Tipo",
"it": "Tipo",
"pt": "Tipo",
"fr": "Type"
},
"kind": "select",
"required": true,
"options": [
{
"value": "choice",
"label": {
"uk": "Один зі списку",
"en": "One of a list",
"de": "Eines aus einer Liste",
"ru": "Один из списка",
"es": "Uno de una lista",
"it": "Uno di un elenco",
"pt": "Um de uma lista",
"fr": "Un choix dans une liste"
}
},
{
"value": "yes_no",
"label": {
"uk": "Так чи ні",
"en": "Yes or no",
"de": "Ja oder Nein",
"ru": "Да или нет",
"es": "Sí o no",
"it": "Sì o no",
"pt": "Sim ou não",
"fr": "Oui ou non"
}
},
{
"value": "text",
"label": {
"uk": "Короткий текст",
"en": "A short text",
"de": "Ein kurzer Text",
"ru": "Короткий текст",
"es": "Un texto breve",
"it": "Un testo breve",
"pt": "Um texto curto",
"fr": "Un texte court"
}
}
],
"client_editable": true
},
{
"key": "required",
"label": {
"uk": "Покупець має відповісти",
"en": "The buyer must answer",
"de": "Der Käufer muss antworten",
"ru": "Покупатель должен ответить",
"es": "El comprador debe responder",
"it": "L’acquirente deve rispondere",
"pt": "O comprador tem de responder",
"fr": "L’acheteur doit répondre"
},
"kind": "bool",
"client_editable": true
},
{
"key": "max",
"label": {
"uk": "Найбільше символів",
"en": "Most characters",
"de": "Höchstzahl der Zeichen",
"ru": "Максимум символов",
"es": "Máximo de caracteres",
"it": "Massimo di caratteri",
"pt": "Máximo de caracteres",
"fr": "Nombre maximal de caractères"
},
"kind": "number",
"integer": true,
"client_editable": true
},
{
"key": "choices",
"label": {
"uk": "Що можна обрати",
"en": "Choices",
"de": "Auswahl",
"ru": "Что можно выбрать",
"es": "Qué se puede elegir",
"it": "Scelte",
"pt": "Escolhas",
"fr": "Choix"
},
"kind": "list",
"of": [
{
"key": "label",
"label": {
"uk": "Підпис",
"en": "Label",
"de": "Bezeichnung",
"ru": "Подпись",
"es": "Etiqueta",
"it": "Etichetta",
"pt": "Etiqueta",
"fr": "Libellé"
},
"kind": "text",
"required": true,
"client_editable": true
},
{
"key": "adds",
"label": {
"uk": "Додає до ціни",
"en": "Adds to the price",
"de": "Kommt zum Preis hinzu",
"ru": "Добавляет к цене",
"es": "Suma al precio",
"it": "Si aggiunge al prezzo",
"pt": "Acresce ao preço",
"fr": "S’ajoute au prix"
},
"kind": "money",
"client_editable": true
}
],
"client_editable": true
},
{
"key": "adds",
"label": {
"uk": "Додає до ціни",
"en": "Adds to the price",
"de": "Kommt zum Preis hinzu",
"ru": "Добавляет к цене",
"es": "Suma al precio",
"it": "Si aggiunge al prezzo",
"pt": "Acresce ao preço",
"fr": "S’ajoute au prix"
},
"kind": "money",
"client_editable": true
}
],
"client_editable": true
},
{
"key": "tracked",
"label": {
"uk": "Рахується",
"en": "Counted",
"de": "Gezählt",
"ru": "Учитывается",
"es": "Con recuento",
"it": "Conteggiato",
"pt": "Com contagem",
"fr": "Compté"
},
"kind": "bool",
"client_editable": true
},
{
"key": "size_class",
"label": {
"uk": "Розмір для доставки",
"en": "Shipping size",
"de": "Versandgrösse",
"ru": "Размер для доставки",
"es": "Tamaño para el envío",
"it": "Dimensione per la spedizione",
"pt": "Tamanho para o envio",
"fr": "Format pour la livraison"
},
"kind": "select",
"options": [
{
"value": "letter",
"label": {
"uk": "Лист",
"en": "Letter",
"de": "Brief",
"ru": "Письмо",
"es": "Carta",
"it": "Lettera",
"pt": "Carta",
"fr": "Lettre"
}
},
{
"value": "parcel",
"label": {
"uk": "Посилка",
"en": "Parcel",
"de": "Paket",
"ru": "Посылка",
"es": "Paquete",
"it": "Pacco",
"pt": "Volume",
"fr": "Colis"
}
},
{
"value": "bulky",
"label": {
"uk": "Громіздкі товари",
"en": "Bulky goods",
"de": "Sperrgut",
"ru": "Громоздкие товары",
"es": "Artículos voluminosos",
"it": "Articoli ingombranti",
"pt": "Artigos volumosos",
"fr": "Articles volumineux"
}
}
],
"client_editable": true
},
{
"key": "tax_code",
"label": {
"uk": "Податковий код",
"en": "Tax code",
"de": "Steuercode",
"ru": "Налоговый код",
"es": "Código de impuestos",
"it": "Codice imposta",
"pt": "Código de imposto",
"fr": "Code de taxe"
},
"kind": "text",
"client_editable": true,
"no_tap_target": true
},
{
"key": "tariff_number",
"label": {
"uk": "Митний код",
"en": "Customs tariff number",
"de": "Zolltarifnummer",
"ru": "Таможенный код",
"es": "Código arancelario",
"it": "Codice doganale",
"pt": "Código aduaneiro",
"fr": "Code douanier"
},
"kind": "text",
"client_editable": true,
"no_tap_target": true
},
{
"key": "made_in",
"label": {
"uk": "Країна виробництва",
"en": "Made in",
"de": "Herkunftsland",
"ru": "Страна производства",
"es": "País de fabricación",
"it": "Paese di produzione",
"pt": "País de fabrico",
"fr": "Pays de fabrication"
},
"kind": "text",
"client_editable": true
}
]
}
],
"collections": [
{
"name": "products",
"label": {
"uk": "Товари",
"en": "Products",
"de": "Produkte",
"ru": "Товары",
"es": "Productos",
"it": "Prodotti",
"pt": "Produtos",
"fr": "Produits"
},
"one": {
"uk": "товар",
"en": "product",
"de": "Produkt",
"ru": "товар",
"es": "producto",
"it": "prodotto",
"pt": "produto",
"fr": "produit"
},
"type": "product",
"route": {
"detail": "/shop/{slug}",
"listing": "/shop"
}
}
],
"modules": {
"shop": {
"products": "products"
}
}
},
"settings": {
"zones": [
{
"_key": "home",
"name": {
"uk": "Всередині країни",
"en": "Domestic",
"de": "Inland",
"ru": "По стране",
"es": "Nacional",
"it": "Nazionale",
"pt": "Nacional",
"fr": "National"
},
"countries": []
}
],
"methods": [
{
"_key": "post",
"zone": "home",
"name": {
"uk": "Пошта",
"en": "Post",
"de": "Post",
"ru": "Почта",
"es": "Correo",
"it": "Posta",
"pt": "Correio",
"fr": "Poste"
}
},
{
"_key": "pickup",
"zone": "home",
"name": {
"uk": "Самовивіз",
"en": "Pick-up",
"de": "Abholung",
"ru": "Самовывоз",
"es": "Recogida en tienda",
"it": "Ritiro in sede",
"pt": "Recolha no local",
"fr": "Retrait sur place"
},
"pickup": true
}
]
},
"entries": []
}