# Subset Operating Flow

## End-to-end diagram

```mermaid
flowchart TD
    A["Create company"] --> B["Owner signs in"]
    B --> C["Create users and assign roles"]
    C --> D["Configure P&L, margin rules, RTO and alerts"]
    D --> E["Connect Shopify Admin API"]
    E --> F["Fetch catalogue, inventory and vendors"]
    F --> G{"Shopify unit cost exists?"}
    G -- Yes --> H["Store actual Shopify unit cost"]
    G -- No --> I["Mark the item cost as estimated until the complete order total is available"]
    H --> J["Fetch current or historical orders"]
    I --> J
    J --> K["Map SKU to supplier and cost"]
    K --> L{"Order product cost exists?"}
    L -- Yes --> M["Calculate P&L using recorded cost"]
    L -- No --> N["Estimate total product cost from tax-inclusive order sale and the first matching margin rule"]
    N --> M
    M --> O["Create profit snapshot and evaluate exceptions"]
    O --> P["Correct or approve exceptions"]
    P --> Q["Review day, week, month or custom P&L"]
    Q --> R["Create partner settlement request"]
    R --> S["Partner approves or rejects"]
    S --> T{"Approved?"}
    T -- Yes --> U["Tenant admin marks settlement paid"]
    T -- No --> V["Revise agreement or settlement"]
    U --> W["Settled ledger and dashboard"]
    B --> X["Owner-only close shop"]
    X --> Y["Password plus typed company confirmation"]
    Y --> Z["Delete tenant data and cancel company"]
```

## Required setup order

1. Create the company. The creator becomes the tenant owner.
2. In **Team & access**, create administrators, partners, accountants and suppliers.
3. In **Configuration**, set gateway fees, Shopify fees, shipping, packaging, RTO cost and ordered margin rules.
4. In **Setup & health**, connect Shopify with `read_orders`, `read_products` and `read_inventory`. Add approved `read_all_orders` for older orders.
5. Fetch the catalogue. Shopify `vendor` creates or matches suppliers, SKU creates mappings, inventory is stored, and Shopify unit cost is used when available.
6. When product cost is absent, Subset labels it `estimated_margin_rule`. The estimated total product cost is calculated from the complete order sale including tax: total sale minus the configured 30% or 35% margin. The total is allocated across order lines for traceability.
7. Fetch orders for the required date period. SKU mappings assign suppliers and mapped costs.
8. If an order still has missing product cost, Subset applies the first matching rule to the total order sale including tax. It calculates cost as total sale minus the target margin, then allocates that cost across missing lines.
9. Review **Orders**, **Exceptions**, and **P&L analytics**. Estimated costs are visibly marked and can be replaced with a manual or Shopify cost.
10. In **Partner settlements**, create an agreement and settlement period. The assigned partner must approve before an administrator can mark it paid.

## Margin rule behavior

- Rules run from top to bottom.
- The first enabled matching rule wins.
- Supported criteria are order amount below, order amount at or above, payment status, order status, and all orders.
- If no rule matches, **Default target margin %** applies.
- A missing order cost is calculated as:

```text
estimated product cost =
(total order sale including tax) × (1 - target margin %)
```

This keeps the final order margin at the configured target rather than producing an artificial near-100% margin.

## Cost provenance

| Label | Meaning | Recommended action |
|---|---|---|
| `shopify_unit_cost` | Shopify InventoryItem supplied the cost | Treat as source cost and verify periodically |
| `manual` | A user entered the cost | Retain invoice or supplier evidence |
| `estimated_margin_rule` | Subset calculated a temporary cost | Replace when the actual supplier cost becomes available |
| `mixed` | Order lines use more than one cost source | Review line-level mappings |

## Closing a company

Only the tenant owner can close a shop. In **Configuration**, use **Close shop and clear company data**, type the company name or URL, enter the owner password, acknowledge the warning and confirm. Subset deletes tenant-scoped operations and configuration, cancels the tenant, and retains only the tenant identity plus a closure audit record.