📖 User Manual

🧮 Overview

The Artikelkalkulation app enables central management of purchase prices, calculation factors, and selling prices for all products in your Shopify store. The app consists of four areas accessible via the sidebar menu or the tabs at the top.

First-Run Setup Wizard

On first launch the app shows a setup wizard that walks through 6 steps: backup settings, autosave (including delay), VAT rates, price rounding, and the disclaimer. The wizard can be skipped ahead to the disclaimer step via 'Skip' — the disclaimer must be confirmed with a checkbox before the app can be used.

💶 Purchase Prices

Shows all products and their variants with the current purchase price (unit cost) from Shopify. The cost price is stored in each variant's inventory (inventoryItem.unitCost).

Loading Data

On first opening the tab the first 25 products are loaded automatically (default). The load limit can be adjusted directly in the filter row. A progress bar shows the loading status. The tab caches loaded data – a reload only occurs when data has changed in another tab.

Load Limit

The 'Load limit' dropdown on the right side of the filter row controls how many products are loaded initially: 25 / 50 / 100 / 250 / All. Default is 25 — ideal for large catalogs. When a collection or tag filter is active, all matching products are always fetched from Shopify regardless of the limit. A hint below the filters shows whether a limit is active, a filter loaded all matches, or all products are loaded.

Sorting

A 'Sort by' dropdown to the right of the load-limit control lets you sort by Name, Vendor, Cost status, or Variant count. Once a sort option is selected, two buttons ↑ (ascending) and ↓ (descending) appear. Sorting is applied after the active filters.

Filter & Search

• Search field – filters products by name (local, only on loaded products)
• All / With cost / Without cost – quick filters for data completeness
• Collection – loads all products in the collection from Shopify (ignores load limit)
• Vendor – loads all products from the selected vendor directly from Shopify (ignores load limit)
• Tag – loads all products with the selected tag from Shopify (ignores load limit)

The ⊞ (expand all) and ⊟ (collapse all) buttons on the right side of the filter bar open or close all visible products at once.

Editing Prices

Expand a product, then change the cost price directly in the input field. Changed fields are highlighted in orange.

Status badges

Each product shows badges in its title bar indicating the status of its variants at a glance — even when the product is collapsed.

• Red – No price: At least one variant has no purchase price. The number shows how many variants are affected.
• Orange – Changed: At least one variant has been edited but not yet saved.
• No badge = all variants have a saved purchase price and no pending changes.

Saving

Save all (bar at the bottom, from the Basic plan) saves all changed unit costs in one batch. A confirmation dialog appears first. Individual products can also be saved one by one (Free plan and above). The Cancel button next to Save all discards all pending changes and restores the last saved state — available on all plans. Each saved product counts as one unit against your monthly quota.

Zero-price warning

Automatic Pre-Save Backup

The browser can automatically download a JSON file with the original values before save operations. This behaviour is configurable in Settings under 'Automatic backup' (Never / On batch save only / Always). Downloaded files can be restored via the Backup tab.

Automatic Saving (Autosave)

When autosave is active, changed cost prices are saved automatically after the configured delay — without clicking Save manually. Whether autosave is on and which delay is active can be read and changed directly in the status bar. Each automatically saved product counts as one unit against your monthly quota.

Status bar

A compact status bar is embedded in the sticky filter area, to the left of the session row. It shows whether autosave is active, the selected delay, and the current state (pending / saving / last saved HH:MM:SS). Toggle and delay can be changed directly in the bar without opening settings.

Calculation Factor at a Glance

The saved calculation factor or advanced percentage values are shown inline in the collapsed product header — e.g. Factor: 2.50 or BK: 5% · GZ: 20%. This lets you see the calculation status without expanding the product.

Work Sessions

Work sessions let you track editing progress across multiple sittings. Whenever a product is saved, the app marks it as processed in the active session. Sessions are stored in the browser and persist after the window is closed.

Creating and Using a Session

1. Set a filter or collection first, then click New Session and enter a name. The name is automatically prefixed with EK_ (Purchase Prices) or VK_ (Article Calculation).
2. Saving a product automatically marks it as processed in the active session.
3. Use the pill buttons (All / Processed / Unprocessed) to filter products by status — only products within the session scope are counted.
4. End deactivates the session for this tab only – the session and other tabs remain unaffected.
5. Delete permanently removes the session from the browser. A confirmation dialog prevents accidental deletion.

Multiple sessions can exist simultaneously. The dropdown lets you switch between them. An EK session also activates automatically in the Kalk tab if no session is running there yet.

Session Scope

When a session is created, the app stores the active filter (collection, tag) and the IDs of visible products as its scope. The progress counter shows processed / scope size instead of processed / all loaded products.

Scope Banner

When switching to a tab where the active session has a different filter than currently loaded, a blue banner appears showing the scope filter and size. Clicking Load now restores the matching filter automatically. The × closes the banner without reloading.

Excel Export / Import

Two buttons in the Purchase Prices tab enable Excel-based workflows: Excel Export creates a .xlsx file with all currently visible variants. Columns A–D (Variant ID, Product, Variant, SKU) are locked and shaded grey; column E (unit cost) is editable and highlighted green.

Re-import the edited file: the app reads column E, compares each value to the currently displayed cost price, and only applies rows with actual changes. Result summary: X applied · X skipped (no change) · X errors. Rows with errors are listed in an error modal and marked with a red X in the variant list; affected products expand automatically.

🏷 Article Calculation

Calculates a new selling price from cost and factor and writes it directly to Shopify. The factor and a saved reference price are also stored as metafields.

Entering a Factor

• Expand a product – enter the factor directly in the number field
• − / + buttons change the value in 0.01 increments

Derived Factor

If no factor is saved for a variant but both cost and selling price exist, the factor is calculated automatically (selling price ÷ cost). A yellow banner offers to adopt this derived factor.

Cost-Change Detection

Price Calculation

New price = cost × factor, rounded to the step configured in Settings (default: €0.05). Example: cost €12.00 × factor 2.30 = €27.60 → rounded to €27.60. The factor can be adjusted directly with the input field or the −/+ buttons.

Product Status

Status Filters

Use the filter buttons to narrow down products by status:

In addition to the status filter, dropdowns for collection, vendor and tag are available. All three trigger a server-side reload and fetch all matching products directly from Shopify — regardless of the configured load limit.

The ⊞ (expand all) and ⊟ (collapse all) buttons on the right of the filter bar open or close all visible products at once.

Load Limit

The dropdown on the right of the filter row limits how many products are loaded initially (25 / 50 / 100 / 250 / All). The limit is ignored when a collection or tag filter is active.

Sorting

A 'Sort by' dropdown to the right of the load-limit control lets you sort by Name, Vendor, Status, or Calculation factor. Once a sort option is selected, ↑ (ascending) and ↓ (descending) buttons appear. Sorting is applied after the active filters.

Factor Display in the Product Header

The saved factor (simple mode: Factor: 2.50, advanced mode: BK: 5% · HK: 3% · GZ: 20%) is shown inline in the collapsed product header for a quick overview.

Advanced Calculation

In advanced mode (from the Premium plan) the simple factor is replaced by a formula chain: cost → landed cost (+ procurement %) → bar price (+ handling %) → + markup % → net price (÷ discount buffer %) → gross price (+ VAT %). Each percentage is entered directly in the formula header row of the expanded product table. The VAT setting (standard / reduced) is saved per product.

Work Sessions

Work sessions let you track editing progress across multiple sittings. Whenever a product is saved, the app marks it as processed in the active session. Sessions are stored in the browser and persist after the window is closed.

Creating and Using a Session

1. Set a filter or collection first, then click New Session and enter a name. The name is automatically prefixed with EK_ (Purchase Prices) or VK_ (Article Calculation).
2. Saving a product automatically marks it as processed in the active session.
3. Use the pill buttons (All / Processed / Unprocessed) to filter products by status — only products within the session scope are counted.
4. End deactivates the session for this tab only – the session and other tabs remain unaffected.
5. Delete permanently removes the session from the browser. A confirmation dialog prevents accidental deletion.

Multiple sessions can exist simultaneously. The dropdown lets you switch between them. An EK session also activates automatically in the Kalk tab if no session is running there yet.

Session Scope

When a session is created, the app stores the active filter (collection, tag) and the IDs of visible products as its scope. The progress counter shows processed / scope size instead of processed / all loaded products.

Scope Banner

When switching to a tab where the active session has a different filter than currently loaded, a blue banner appears showing the scope filter and size. Clicking Load now restores the matching filter automatically. The × closes the banner without reloading.

Saving

Three levels are available: Per variant – Save button in the variant row (all plans). Per product – Save button in the product header (all plans). Saves factor, reference price and selling price. Save all – via the bottom bar (from the Basic plan).

Bulk edit

A bulk-edit row sits above the product list. Select a field from the dropdown (calculation factor, VAT; in advanced mode also procurement costs, handling costs, markup and buffer), enter a value, and click 'Apply to visible'. The value is immediately applied to all currently filtered products and marked as changed.

Save all

Save all in the bottom bar saves all products with pending changes at once. Available from the Basic plan; usage is counted per saved product. The Cancel button next to it discards all local changes and restores the last saved state — no server call, available on all plans.

Autosave

When autosave is active, changes to calculation factors and advanced fields are saved automatically after the configured delay — no manual save needed. Each automatically saved product counts as one unit against your monthly quota.

Status bar

A compact status bar is embedded in the sticky filter area, to the left of the session row. It shows the autosave state and lets you toggle it on/off and change the delay (2 s / 10 s / tab switch) directly in the tab.

💾 Backup

Allows export and import of all relevant price data as a JSON file. Before every major change a Full Backup should be created.

Exporting

Four export types are available:

• Full Backup – cost, selling price and factor for all variants (recommended)
• Purchase Prices – unit cost only
• Selling Prices – Shopify prices only
• Calculation Factors – factors only

Full Backup is available from the Basic plan. Selective backups (purchase prices, selling prices, factors) require the Premium plan. Restoring requires the Basic plan.

Restoring

1. Select backup file (JSON)
2. App compares the file with current Shopify data
3. All differences are shown in a table
4. Individual changes can be selected or deselected via checkbox
5. "OK – Apply changes" writes only the selected values back

Restore is available from the Basic plan. Without an eligible plan, clicking the button shows an upgrade prompt. A restore is not counted against your monthly quota and always completes in full, regardless of how many products are affected.

⚙ Settings

The Settings & Subscription tab configures global options for the app and provides access to subscription management. Settings apply to all tabs and are stored in your browser (localStorage).

Autosave

Two separate toggles enable autosave for the purchase prices tab and the article calculation tab independently. Below each toggle, choose the delay: 2 s and 10 s start a timer after the last input; 'Tab switch' saves all pending changes when leaving the tab. Toggle and delay are also accessible directly in the status bar of each tab.

Automatic backup

Before save operations, the browser can automatically download a JSON backup file. Configurable separately for purchase prices and article calculation: 'No automatic backup', 'On batch save only', or 'Always'. Default: Always. Switching to 'No automatic backup' shows a warning dialog highlighting the risk.

VAT rates

Sets the standard and reduced VAT rates used in article calculation. The rate is selected per product and applied to gross price calculations.

Price Rounding

Sets which step the calculated selling price is rounded to. Available steps: €1.00 · €0.50 · €0.10 · €0.05 · No rounding.

Rounding is applied in Article Calculation on every save: new price = cost × factor, rounded to the chosen step. A live preview shows the result for each rounding step directly in the selection.

Product load limit

The number of products loaded initially is set directly in the filter row of the Purchase Prices and Article Calculation tabs (25 / 50 / 100 / 250 / All). The setting is saved and applies to both tabs.

Language

The app language can be switched to German or English. The setting is stored per shop and applies to all users of the same shop.

💳 Subscription

Subscription management is part of the Settings & Subscription tab (below the settings section). It shows your active plan, monthly usage, and all available plans.

Choosing a plan

Use the toggle above the plan cards to switch between monthly and annual billing. The annual rate is cheaper -- the savings percentage is shown directly on each plan card. Click the desired plan to be taken to Shopify's payment page. Your plan is updated automatically after checkout.

Usage & Status

Your current plan, monthly usage, and the next reset date are shown in the status area. A progress bar visualises usage. A warning appears when usage exceeds 80%. One unit of usage is counted per saved product – whether a purchase price, an article calculation, or autosave, saved individually or via 'Save all'. Discarding changes and restoring a backup do not count.

Cancellation

Your subscription can be cancelled directly in the app without leaving to Shopify. Click 'Cancel subscription', confirm the dialog -- the cancellation takes effect immediately. You retain access to all features until the end of the current billing period. After that, the app automatically switches to the Free plan.

💡 Tips & Notes

Recommended Workflow

1. Create a backup (full backup)
2. Update purchase prices
3. Check / adjust calculation factors
4. Open Article Calculation – review cost-changed products
5. Save new prices

Plans & Action Limits

The app uses an action system. In the Purchase Prices tab, one action equals one click on Save. In the Article Calculation tab, 'Save all' counts one action per saved product.

Your current plan and usage can be found under Subscription in the sidebar.

Frequently Asked Questions