Drivers & stores

Drivers are independent accounts. A driver delivers for a store only after joining its team, and a driver may belong to several stores at once.

Joining a team#

Either side can start:

	Driver asks to join	Store invites the driver
Start	Driver: POST stores/{store}/request	Store: POST drivers/{driver}/invite
Status	pending	invited
Accept	Store: approve	Driver: accept-invitation
Decline	Store: reject	Driver: reject-invitation
Withdraw	Driver: DELETE stores/{store}/request	Store: cancel-invitation

stateDiagram-v2
    [*] --> pending: driver asks to join
    [*] --> invited: store invites
    pending --> approved: store approves
    invited --> approved: driver accepts
    pending --> rejected: store rejects
    invited --> rejected: driver rejects
    approved --> [*]: driver leaves or store removes

• While a pair is pending, invited or approved, neither side can open another request or invitation; the server answers 409 and says why. If the store has already invited the driver, the message points the driver to accept instead.
• rejected is not permanent: either side may start again.
• Each step pushes the other side (see Push notifications).

Finding each other#

• Drivers browse active stores near them with stores/browse. It searches around the position saved on the driver's profile (lat, lng via PUT profile), with the same radius rules as store discovery. A driver with no saved position gets 422.
• Stores browse active drivers near the store with browse-drivers. Inviting a driver whose account is not active yet returns 422.

Lists#

Driver app	Merchant app
stores/my — stores the driver works for	drivers — the store's team
store-requests — the driver's own requests	driver-requests — drivers asking to join
stores/invitations — invitations to answer	invited-drivers — invitations sent

Leaving#

A driver leaves with POST stores/{store}/leave; a store removes a driver with DELETE drivers/{driver}. Either ends the membership, and the pair can start over later.

Availability#

A driver who registers stays inactive until Tote approves the account (see Drivers). Once active, the driver goes on and off duty with POST profile/toggle-availability, which flips the flag and returns the new is_available. Stores see that flag when choosing a driver.

Assigning an order to a driver is covered in Order lifecycle.