Field Sales

The field sales feature lets your team sign up new customers and sell services in the field using the mobile app. It combines customer creation, property setup, invoicing, and payment collection into a streamlined mobile workflow.

Overview

Field sales supports three core workflows:

Door-to-Door Enrollment

The enrollment flow creates a complete customer record from the field.

Step-by-Step

1. Open the mobile app and tap Field Sales > New Customer
2. Enter the customer's information:
   • First name and last name (or full name)
   • Email (optional, but needed for receipts)
   • Phone (optional)
   • Address — the service property address
3. Select a service plan
4. Choose a payment method:
   • Tap to Pay — collect payment immediately with contactless card
   • Card entry — manually enter card details
   • Send invoice — email an invoice for later payment
5. If using Tap to Pay or card entry, the payment is processed through Stripe
6. Tap Submit

What Happens Behind the Scenes

When an enrollment is submitted, the API performs these steps in order:

1. Geocode the address to get lat/lng coordinates
2. Auto-match zone — if the coordinates fall within a service zone, the zone is assigned
3. Look up the service plan to get pricing
4. Create the customer record with billing status active
5. Create a property linked to the customer with the geocoded address
6. Create an invoice with the service plan price, tax calculation, and line items
7. If payment was collected via Stripe, create a payment record with card brand, last4, and receipt URL
8. Run lifecycle hooks — welcome email, route template sync, referral processing

Pricing Logic

The invoice amount is calculated as:

base_price + (extra_bins * additional_bin_price)

Where extra_bins = max(0, bin_count - 1). Tax is calculated using the service plan's tax rate (or the tenant's default rate) and added to the total.

Quick Sale

Quick sale lets you sell a service to a customer who already exists in your system.

Step-by-Step

1. Open the mobile app and tap Field Sales > Existing Customer
2. Search for the customer by name, email, or phone
3. Select the customer from the results
4. Choose a service plan for this sale
5. Select a payment method (Tap to Pay, card entry, or send invoice)
6. If collecting payment, process via Stripe
7. Tap Submit

Customer Search

The search endpoint supports partial matching on:

• Customer name
• Email address
• Phone number

Results are limited to 10 matches and sorted alphabetically. A minimum of 2 characters is required.

Tap to Pay

Tap to Pay enables contactless card payments directly from the driver's mobile device. It uses Stripe Terminal with the device's built-in NFC reader.

Requirements

• iPhone XS or later with iOS 16+
• Stripe Terminal integration configured
• Connected Stripe account with Tap to Pay enabled

Payment Flow

1. Driver selects "Tap to Pay" as the payment method
2. The app creates a Stripe PaymentIntent for the invoice amount
3. The customer taps their card or phone on the driver's device
4. Payment is confirmed and the Stripe PaymentIntent ID is saved
5. The invoice is immediately marked as paid
6. Card details (brand, last4) and receipt URL are stored

Digital Receipts

After collecting payment, drivers can send a digital receipt to the customer's email.

Sending a Receipt

1. After a successful payment, tap Send Receipt
2. Confirm or enter the customer's email address
3. Tap Send

Receipt Contents

The receipt email includes:

• Company name as the header
• Customer greeting using their first name
• Line items table with description and amount
• Total with tax included
• Payment method — card brand and last 4 digits
• Payment status — "Paid"
• Link to Stripe receipt — if available, a link to the full Stripe receipt

API Reference

Enroll a new customer

curl -X POST "https://api.nextroute.app/api/field-sales/enroll" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_first_name": "Sarah",
    "customer_last_name": "Johnson",
    "customer_email": "sarah@example.com",
    "customer_phone": "555-0199",
    "address": "456 Oak Ave, Austin, TX 78702",
    "service_plan_id": "plan_weekly_standard",
    "payment_method": "tap_to_pay",
    "stripe_payment_intent_id": "pi_3abc123",
    "bin_count": 2
  }'

Response (200):

{
  "customer_id": "cus_new123",
  "property_id": "prop_new456",
  "invoice_id": "inv_new789",
  "zone_id": "zone_central"
}

Quick sale to existing customer

curl -X POST "https://api.nextroute.app/api/field-sales/quick-sale" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "service_plan_id": "plan_one_time_cleanup",
    "payment_method": "send_invoice"
  }'

Response (200):

{
  "invoice_id": "inv_qs456"
}

Search existing customers

curl "https://api.nextroute.app/api/field-sales/search-customers?q=sarah" \
  -H "Authorization: Bearer YOUR_TOKEN"

Send a receipt

curl -X POST "https://api.nextroute.app/api/field-sales/send-receipt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "inv_new789",
    "customer_email": "sarah@example.com"
  }'

Related Pages

• Invoices — invoice management and statuses
• Service Plans — configuring plan pricing
• Enrollment — online self-service enrollment
• Webhooks — payment event processing