Chapter 16 — Merchandising

Module code: merchandising Home: /merchandising/

A longer standalone treatment of this module, including worked examples, is kept at docs/MERCHANDISING_USER_MANUAL.md. This chapter is the version consistent with the rest of the manual.

16.1 What the module is for

Merchandising plans and tracks field visits to retail stores. A supervisor divides the market into territories, profiles the stores in each, plans routes, and states what must be done at each store. The merchandiser follows the route, checks in on arrival, does the work, and checks out.

It reuses the master data that already exists. Stores are customer partners; the sales team and the salesperson come from the partner record; product objectives point at real items. The module adds only what is genuinely merchandising-specific.

16.2 Who uses it

16.3 Screens

/merchandising/                          dashboard
/merchandising/territories/              territories
/merchandising/stores/                   store profiles
/merchandising/objectives/               visit objectives
/merchandising/routes/                   route plans
/merchandising/visits/                   store visits

16.4 The workflow

   Territory
      ↓
   Store profile
      ↓
   Visit objectives
      ↓
   Route plan  ──►  Stores added to the route
                          ↓
                    Store visits
                          ↓
                    Check in  →  work  →  Check out
                          ↓
                    Supervisor review

16.5 Territories

Screen: /merchandising/territories/

A territory is a geographical and team responsibility area.

1. Select Create territory.
2. Enter the name and code.
3. Set the geography — country, state or region, city. These come from Chapter 3, so load geography first.
4. Set the sales team and the supervisor.
5. Assign the merchandisers who cover it.
6. Save.

16.6 Store profiles

Screen: /merchandising/stores/

A store profile links an existing customer partner to its merchandising rules. The partner record stays the source of truth for the customer's identity, address, sales team and salesperson; the profile adds only the field-work settings.

1. Select Create store profile.
2. Choose the store partner. It must already exist as a customer (Chapter 5).
3. Set the territory.
4. Set the default merchandiser only if it differs from the salesperson on the partner record. Leave it blank to inherit.
5. Set the visit frequency: daily, weekly, bi-weekly, monthly, or custom.
6. Enter the store's latitude and longitude, and the geo-fence radius in metres — how close a merchandiser must be for a check-in to count as at the store.
7. Save.

The ownership rule the module follows is:

Store sales team   = the partner's sales team
Store merchandiser = the profile's default merchandiser, if set
                     otherwise the partner's salesperson

Setting the merchandiser on the partner record rather than the profile keeps store ownership in one place.

16.7 Visit objectives

Screen: /merchandising/objectives/

An objective states what must be done at a store. Typical objectives:

1. Select Create objective.
2. Enter the name and the type.
3. Optionally link it to a product category or a specific item, so the objective names exactly what to check.
4. Mark it required if the visit is not complete without it.
5. Save.

Objectives attach to a route plan (applying to every store on it) or to an individual route store (applying only there).

16.8 Route plans

Screen: /merchandising/routes/

1. Select Create route plan.
2. Enter: - Route name. - Territory. - Merchandiser who will walk it. - Sales team — normally the same as the stores' partner sales team. - Start and end dates. - Objectives that apply to every store on the route. - Notes.
3. Save as Draft.

Route status

Keep a route in Draft while planning and publish it when it is ready. A merchandiser should never be working from a route that is still being edited.

Adding stores to a route

For each store on the route:

1. Choose the store profile.
2. Set the planned visit date.
3. Set the sequence — the order stores should be visited in. Number in tens (10, 20, 30) so a store can be inserted later without renumbering everything.
4. Mark required if the visit is mandatory.
5. Add any store-specific objectives.
6. Add notes.

Create a visit directly from a route store with /merchandising/route-stores/<id>/create-visit/.

16.9 Store visits

Screen: /merchandising/visits/

A visit is the execution record. It holds the store profile, the merchandiser, the route store it came from, the date, the status, the check-in and check-out times, the GPS coordinates, the time spent and any notes.

Visit status

Checking in

Screen: /merchandising/visits/<id>/check-in/

On arriving at the store, the merchandiser opens the visit and selects Check in. The system records the date and time, the latitude and longitude where available, and sets the status to Checked in.

Checking out

Screen: /merchandising/visits/<id>/check-out/

On finishing, the merchandiser selects Check out. The date, time and coordinates are recorded, the time spent is calculated, and the status becomes Completed.

Location capture requires a secure connection. On a plain http address the browser will not give the page a location, so coordinates will be blank. This is a browser rule.

16.10 Monitoring

The dashboard at /merchandising/ shows planned, completed and missed visits, and field activity by merchandiser.

The questions worth asking weekly:

[ ] Which required visits were missed, and why?
[ ] Which stores are being visited less often than their frequency says?
[ ] Are check-in coordinates consistent with the store's location?
[ ] Is time spent per visit plausible?

A visit checked in and out within two minutes, from a coordinate a kilometre from the store, is the pattern this module exists to make visible.

16.11 Troubleshooting