Installation Guide

Installation Overview

Budgeting Pro is installed from Shopify and then accessed on a shop-specific subdomain.

The current installation flow creates the shop and shop super admin automatically. It does not automatically create all company, location, budget, and user data for the merchant.

Shopify Install Flow

Step 1: Install and authorize the app

When the merchant installs the app from Shopify and completes OAuth:

the Shopify access token is stored for the shop
the shop record is created or updated locally
a super admin user is created for that shop
the super admin email is taken from Shopify shop data

Step 2: Credentials are emailed

After a successful install, the app sends the shop super admin:

the shop subdomain URL
the admin email address
a generated password

The admin account is created as an admin user type with the super_admin role.

Step 3: Background setup runs

After installation, the app also starts background work to:

register webhooks
import Shopify companies for the shop

First Access After Install

The application is reached through the shop subdomain, for example:

https://your-shop-subdomain.4budgetingpro.app/admin
https://your-shop-subdomain.4budgetingpro.app/app

Admin panel access

The first account created by installation is the shop admin. This user signs in to /admin with:

email
password

App panel access

Company users use /app. They do not use the admin password flow. The company-facing panel uses:

registration plus email verification for new company setup
OTP login for company users

Subscription Approval

Initial access window

The current middleware allows a newly installed shop to access the app for about 30 minutes after installation before subscription approval is enforced.

Billing flow

After the initial window, the app can redirect the merchant into the Shopify billing approval flow:

/billing/create
/billing/confirmed

Depending on Shopify's response, the shop may be:

activated
pending approval
declined
blocked until billing is resolved

Company Onboarding After Shop Install

Shop installation and company onboarding are separate concerns in the current build.

After the shop is installed, company data can be introduced in two ways:

Option 1: Import existing companies from Shopify

From the admin panel, open Companies and use Import From Shopify.

Option 2: Register a new company from the app panel

From /app/register, a company contact can submit:

company name
first location name
shipping address
billing address
main contact details
payment terms

That registration is stored as pending until the email address is verified. After verification, the app creates the company and first location in Shopify and locally.

Troubleshooting

I installed the app but cannot log in

Check:

the email that received the admin credentials
the shop subdomain in the email
that you are opening /admin for the shop admin account

I can access the app right after install, but later I see a payment-required screen

That is expected when the initial access window ends and the shop has not completed subscription approval yet.

A company is missing after install

Companies are not guaranteed to appear immediately unless:

they were imported from Shopify, or
they were created through the app registration flow and verified successfully

A new company registration is stuck