Generated from proposal.md by build-proposal-html.py. Edit the Markdown, then re-run the script.

Business day for an online store — proposal and options

0. Summary

The idea works. A day and a shift with no register run through the shift functions and the shift view without an error (read from the code; nothing was run). The reports keep working.

What the idea does not yet cover, and this proposal fills in:

1. The shift totals. On a till, the POS works out the shift totals and confirms the payment lines; the server does not. BO would have to do both, and a closed day would not see a document that is completed or paid later. This proposal avoids the problem: for an online day BO reads the totals live from the sales, so there is nothing to freeze and nothing to refresh (decision D2).
2. Back-dated documents. BO lets a user pick a document date up to 90 days back. A back-dated document goes on its own day (D5).
3. A return changes its date when it is completed (redate_return, sales_commit_service.py:2637-2640). So a return created on Monday and completed on Wednesday must move to Wednesday's day (D7).
4. Cash refunds. A Cash refund on a BO return is a payment row that the shift adds up as cash out, with nobody to count it. The proposal blocks it (D6).
5. Existing online stores already carry a "day end" of 23:59 from the form defaults. The window turns on only when Opens at is filled in, so no store changes by surprise (section 2.1).
6. Two store guards would break: changing the store type, and (with the sweep option) renaming the store code (section 5).

My picks (section 7): D1 your design (Option 1) · D2 day rows are made on the first sale, born closed, with live totals (no sweep) · D3 reuse the day-end fields and add one start-time column · D4 hard block outside the hours · D5 a back-dated document goes on its own day · D6 block Cash refunds in BO · D7 a completed return moves to the completion day · D8 no empty days.

1. The options

What other products do (official docs where they could be fetched; UNVERIFIED where only a forum or snippet):

• Toast: hours are set per weekday, up to 3 periods a day, with date overrides for holidays. Hours may run past midnight but must end 15 minutes before the business-day cut-off (default 4 a.m.). With scheduling off, guests cannot order outside the hours; with it on, they pre-order for the next opening. Orders placed on the POS (staff) are never limited by online hours. There is no online shift: one cut-off ends the business day.
• Square: online hours limit pickup times; the QR-code ordering page does block outside the hours. The close-of-day setting only groups payouts.
• Shopify: the online store has no hours. Pickup has an on/off switch and a preparation time, no cut-off.
• Dynamics 365 Commerce: store hours are information only. Shifts belong to the POS. Online orders are not tied to a shift (inferred).
• Odoo: self-ordering follows an open POS session. Auto-close and opening-hour limits exist only as add-ons.
• Grab / foodpanda: weekly hours plus special dates, a pause switch, and an automatic pause when no menu item is available.

What this means for you. All the products limit the customer, not the staff. Your rule limits the staff who use BO, which none of them does. That is your call (D4). The products also keep opening hours and the business day apart; your design joins them, which is simpler and fine for a store that works one block a day.

1.1 When the day and shift rows are made, and when they change to closed

The example: an online store, hours 08:00 to 23:59, store time. Today is 16 Oct. "Row" means the two ft_dayshift rows of that day: the day (EOD) and the shift (SHIFT).

For comparison — a till store today (not changed). The cashier opens the business day: the POS writes the day row OPENED. The cashier opens a register shift: the POS writes a shift row OPENED with the register. The cashier counts the cash and closes the shift: the shift row is updated to CLOSED with the counted cash. When every shift is closed, the day is closed: the day row is updated to CLOSED. A person does every step. (dayshift_service.py: close needs all shifts closed.)

Option 1 with D2 = A (born closed, live totals) — recommended

The rows are written once. They are never updated.

Option 1 with D2 = B (opened by the first sale, closed by a sweep)

Option 2 (window only)

Option 3 (soft window)

Same as Option 1 (A or B). The only difference: a user with the permission can create a sale at 02:00 on 17 Oct, before the store opens. It goes on the 17 Oct rows, the calendar day in the store's time zone (opened_datetime 08:00, closed_datetime 23:59, even though the sale came earlier). The rows are made by that first sale, as in the tables above.

Option 4 (24 hours: "Opens at" empty)

Same as Option 1, but the day is the whole calendar day: opened_datetime = 00:00, closed_datetime = 23:59:59. With D2 = A the rows are inserted by the first sale of the day and never updated. With D2 = B the sweep closes the day just after 00:00.

2. How Option 1 works

2.1 Store settings

The store table already has hours fields (tables_pg.sql:6956-6968): business_hours (free text, shown on the form and passed to the POS, but no logic uses it), business_dayend_time (time) and force_business2close (switch). There is no open-time field.

When the window is on. The window is on only when Opens at is filled in. Closes at empty then means 23:59. If Opens at is empty the store is open 24 hours, as it is today, and its day ends at 00:00. This matters because every new store form already fills in a day end of 23:59 (StoreFormPage.tsx:148-149; the setup wizard setup_guide_service.py:420), so those stores would otherwise be closed to sales from one day to the next.

Store › General                         Type: Online
  Business hours (online store)
    Opens at     [ 08:00 ]
    Closes at    [ 23:59 ]
    Time zone    [ Asia/Kuala_Lumpur ]
  Leave "Opens at" empty to take orders 24 hours a day.

Rules for the first version: opening must be earlier than closing, and closing may be 23:59. The same hours every day. Hours that pass midnight, a different time for each weekday, and holidays are for a later version (Toast and Grab have all three).

2.2 The window check

A new function assert_store_open(store, now) runs at the start of each place that creates a BO document, using the server clock in the store's time zone. It is not put inside _resolve_store, because that function is also used by price calculation, coupon check and draft replace (sales_commit_service.py:782,2754; sales_document_write_service.py:118), which must not be blocked, and create_return does not call it at all.

Create exchange is not built (it refuses every request: sales_commit_service.py:2719-2740); the check is added when it is.

Outside the hours the user sees: "This online store is closed now. You can create sales from 08:00 to 23:59." The New buttons show the hours.

Not blocked: price calculation, edit a draft, submit, approve, reject, void, issue, payments, and complete a return. A document keeps the day it was created on, except a return, which moves on completion (D7).

2.3 The day and the shift

When a document is created inside the hours the server finds or makes that store's day and shift for the document's date, then writes the shift id on the document (dayshift_id, offline_dayshift_id). The header insert (sales_commit_repository.py:261) must add both columns; today it leaves them empty ("A8", line 256).

Create a sale (online store)
   |-- Opens at set, and server time outside the hours?  --> refuse with the plain message
   |-- find the day + shift for the document's date (store time zone)
   |-- not found?  take the lock, look again, create day + shift (born closed)
   |-- write dayshift_id on the document; register_id stays empty
   '-- save

Columns the new rows must fill (tables_pg.sql:1311-1360):

ft_dayshift has no unique index and none can be added without created_date (the table is partitioned). Two sales at the same moment could both create a day. Look first without a lock; only when nothing is found take the lock and look again. Reuse the lock from sales_document_repository.py:36: pg_advisory_xact_lock(hashtext('online_day:{company}:{store}:{date}')). The two-number form does not fit (the store id is a bigint and a date is not a number).

ft_dayshift is not a workflow table in code (not in WORKFLOW_TABLES; the CI script lists it as excluded). Use a plain INSERT / UPDATE with the audit fields; do not call change_status. (The BO CLAUDE.md rule 17 still names it; that text is out of date.)

BO has no code that writes ft_dayshift today (the only writer is the API, dayshift_query.py:686,729). This is a new repository and service in BO.

2.4 Totals — why there is no sweep

On a till, a closed day shows stored totals (business_day_repository.py:153-189). The POS works them out and sends them. The server functions only add up lines that the POS has already confirmed:

• fn_api_set_dayshift_payment (functions_pg.sql:6194) only inserts payment lines, with no status; running it twice duplicates them.
• fn_api_dayshift_close_business_day (:891) raises unless the day is already CLOSED, adds up only lines with status CONFIRMED, copies the shift's total_* columns (which nothing on the server fills), and returns early if the day already has payment lines.

So a BO-closed day would end with empty totals unless BO builds the totals, confirms the lines, and handles any later change itself. And the rollup counts only documents in a final status (RETURNED, COMPLETED), while a BO invoice is created today and issued tomorrow.

Proposed instead (D2 option A): online days are born closed and their totals are read live from the sales, by joining store.store_type. The live read must use the sales-summary filters (_SUMMARY_DOC_TYPE_SQL and SALES_REPORT_STATUSES = COMPLETED / RETURNED, business_day_repository.py:1023-1024), not the open-day count at :176-186. That count takes every non-voided header, and an online day will also hold drafts, rejected documents and orders (they get a day at creation), so a converted order would be counted twice. Then:

• nothing to roll up, no payment lines to confirm, no refresh when a document is completed, issued or paid later;
• no sweep job, no tenant loop, no catch-up after downtime, no row left OPENED;
• the store code can still be renamed and the company currency changed all day (store_repository.py:103, company_settings_repository.py:35-47 block those while a day is OPENED).

The cost: every place that today reads the stored totals of a closed day needs one shared test, is_live = closed_datetime IS NULL OR the store is ONLINE (section 3 lists them), and the status column shows a fixed label "Online day" for these days instead of Open / Closed (the status is filtered and counted in SQL, and five pages map OPENED / CLOSED by hand, so a status worked out from the clock is not a small change). D2 option B is the till way: open on the first sale, close by a sweep, freeze the totals. It needs the work listed in section 4.

2.5 What the managers see

• The Business Day and Shift lists show an online day and shift with a blank register (the shift list already tolerates it: business_day_repository.py:363-374; ShiftDetailPage.tsx:163 says "No Register").
• The Register tab lists the register-less shift (get_register_summary, :847-876), but opening that row leads to a page that fails, because the header query joins register (:1361-1375, RegisterTab.tsx:106-108). The row must not be clickable when there is no register.
• The X-report and shift summary show the non-cash payments by method (functions_pg.sql:1772, views_pg.sql:9). With Cash refunds blocked there is no cash line to explain.
• Sales Summary and the other reports keep working: they LEFT JOIN ft_dayshift and now read the shift's business date (COALESCE(d.business_date, h.doc_trx_date::date)).

3. What changes in the code

No change to the POS apps. If D2 option B is chosen add: the sweep (a loop over tenants and companies through tenant_pool_manager, safe to run twice, with catch-up after downtime), the totals build, and a refresh when a document changes after the close.

4. Other ways to handle it

These are variations on Option 1. Each is a decision in section 7.

• How the day rows are made and closed (D2).
• A. Born closed, live totals (recommended): described in 2.3 and 2.4. No job, no frozen totals, nothing to refresh. The work moves to the reading side (section 3, "Totals"). A variant that leaves closed_datetime empty on a CLOSED row would make the existing live paths fire without code, but it stores a contradiction (a closed day with no closing time); not proposed.
• B. Opened on the first sale, closed by a sweep, totals frozen (the till way). The sweep closes the shift then the day, BO sets the shift totals itself, writes the payment lines as CONFIRMED, sets the status, then calls the close function. A refresh means deleting the payment lines and running it again. Late issue, late payment and late completion each need a refresh. The sweep runs in the BO scheduler (asyncio loop with a file lock, 2 workers: main.py:58-70, startup.sh:93-108) or the API one (no lock). The rows are OPENED during the day, which blocks a store-code rename and a company currency change.
• Where the hours live (D3). Reuse the day-end fields and add one start column (one migration). Or keep both times as keys in store_settings_json (no migration, but a second place for hours; store_settings.py:17 and its comment must change).
• Outside the hours (D4). Hard block (your rule). Or block unless the user holds a new permission (a manager override): Toast and Square never limit staff.
• Back-dated documents (D5). Own day: the document goes on the day of its document date, and that past day is made if missing (born closed). Or no back-dating on online stores: the document date is always today.
• Cash refund (D6). Block it. Or keep it: a Cash refund is a payment row that the shift adds up as cash out; nobody counts the cash, so the expected cash of the online shift goes negative. Keeping it needs a rule for how the cash audit shows that (build_cash_audit_figures, business_day_service.py:293).
• A completed return (D7). Moves to the completion day (as its date already does today). Or stop re-dating, so it stays on the day it was created.
• Days with no sales (D8). No row. Or a row every day, which needs a daily job and adds about 730 rows a year for each online store to the lists.

5. Risks and things this changes

6. Tests (written with the work)

• A sale inside the hours is saved on today's shift, register_id empty.
• On an 08:00–23:59 store a sale at 07:59 and at 00:00 is refused with the plain message; one at 08:00 and at 23:59 is accepted.
• A store with Opens at empty accepts sales at any hour, even when a day end is set.
• Create invoice, create order, create return and convert order are refused outside the hours; calculate, edit, submit, approve, issue, payment and complete are not.
• Two sales at the same moment make one day and one shift.
• A back-dated document goes on its own day; that day is made once (D5).
• A return created on Monday and completed on Wednesday ends on Wednesday's day (D7).
• The live totals of an online day count only COMPLETED / RETURNED invoices and returns; a draft, a rejected document and an order are not counted, and a converted order is not counted twice.
• The live totals of a closed online day change when a document on it is issued or paid later.
• The Business Day list, its export, the shift list, the day detail and the shift detail show the same live totals for an online day; the status column reads "Online day".
• Cash is not offered and not accepted on a BO return (D6).
• Changing the store type of an online store with online days is allowed; with a real till shift it is refused.
• The register row of a register-less shift is not clickable.
• Existing tests that assume dayshift_id is empty for BO documents (test_sales_summary_repository.py, class TestBackOfficeSaleHasNoShift) still pass; update the comments in sales_doc_semantics.py:124-145.

7. Decisions for the owner

8. Checked against the repository

9. Sources

• Repository: files and lines in sections 2, 3, 5 and 8.
• External (15 Oct 2026): Toast platform guide (online ordering hours, scheduled orders, business day cut-off); Square Online and Square close-of-day help; Shopify local pickup help; Microsoft Learn Dynamics 365 Commerce (store hours, pickup time slots, trickle feed); Odoo POS self-ordering (forum) and third-party add-ons; Grab merchant blog; Lightspeed Bopple help; foodpanda via a partner knowledge base. Pages that did not load are marked UNVERIFIED in the research notes; Olo has no public documentation.
• Review: Draft 1 was checked by a red-team critic (REVISE) and a database/API verifier (GAPS); Draft 2 was checked once more (REVISE: two high findings on the totals design), and those are fixed here. No third review was run.