Billable Transactions

If your contract with Google specifies billing on a per-transaction basis, your app must call NavigationTransactionRecorder.pickup() and NavigationTransactionRecorder.dropoff() to mark the start and end of each transaction, so that Google can track and log billable transactions. Refer to the implementation guidelines on this page to determine how to allocate billable transactions to rides and deliveries.

Get a NavigationTransactionRecorder object

In order to use the pickup() and dropoff() methods, you must first create an instance of NavigationTransactionRecorder by calling NavigationApi.getTransactionRecorder, as shown in the following example:

NavigationTransactionRecorder transactionRecorder = NavigationApi.getTransactionRecorder(application);

Start a transaction with pickup()

When the driver picks up a passenger or collects an item for delivery, your application must call NavigationTransactionRecorder.pickup(). You should initiate this call when the driver interacts with your app to register the pickup. Do not make this call as part of the onArrival() callback.

The following sample code assumes that the driver taps a button on your app's UI when picking up a passenger or delivery item:

Button b = (Button) findViewById(R.id.btn_pickup);
b.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    transactionRecorder.pickup(
        null /* waypoint */,
        Arrays.asList("MY_TRANSACTION_ID"));
  }
});

Pass the following parameters to the pickup() method:

  • The Waypoint at which the pickup is occurring, or null if the pickup is not part of an existing navigation session.
  • One or more transaction IDs that apply to this pickup. A transaction ID is an arbitrary string that uniquely identifies a billable transaction. See more on transaction IDs below.

End a transaction with dropoff()

When the driver drops off a passenger or delivers an item, your application must call NavigationTransactionRecorder.dropoff(). You should initiate this call when the driver interacts with your app to register the dropoff. Do not make this call as part of the onArrival() callback.

The following sample code assumes that the driver taps a button on your app's UI when dropping off a passenger or delivery item:

Waypoint waypoint = mNavigator.getCurrentRouteSegment().getDestinationWaypoint();

Button b = (Button) findViewById(R.id.btn_dropoff);
b.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
    transactionRecorder.dropoff(
        waypoint,
        Arrays.asList("MY_TRANSACTION_ID"));
  }
});

Pass the following parameters to the dropoff() method:

  • The Waypoint at which the dropoff is occurring, or null if the dropoff is not part of an existing navigation session.
  • One or more transaction IDs that apply to this dropoff. A transaction ID is an arbitrary string that uniquely identifies a billable transaction. See more on transaction IDs below.

Use your own transaction ID or generate one

The transaction ID provides a way to link a ride with a billing transaction from Google. A transaction ID is an arbitrary string with a maximum length of 64 characters. The ID must be unique across transactions.

It's best if you can provide your own transaction ID: one which your systems already use and store.

Alternatively, you can generate a random, unique transaction ID by calling NavigationTransactionRecorder.generateTransactionId(). Store the generated ID in case your organization needs it for reconciling ride transactions.

Implementation guidelines for the navigation transaction recorder

Use the following guidelines to determine how to allocate billable transactions to rides and deliveries.

General guidelines:

  • You must report billable transactions whenever the Navigation SDK for Android is in use, including the use of the road-snapped location provider, and even if the app is not in the foreground for a specific journey. When you want to stop reporting billable transactions, disable navigation by calling stopGuidance() and turn off road-snapped location with stopRequestingLocationUpdates().
  • You must register rides and deliveries as separate and independent transactions, even if a driver does both a ride and a delivery at the same time.
  • You must record pickup and dropoff events immediately when the event occurs.

Guidelines for ride transactions:

  • Navigation sessions not involving a passenger (for example, driving to a pickup point or directing a driver to a popular location for future pickups) do not count as billable transactions.
  • The pickup and dropoff of one passenger counts as one billable transaction.
  • A ride for a group of passengers billed as a group, counts as one billable transaction. In more detail: if the driver picks up two or more passengers at one location and drops them off at another location, and you bill them as a group, this counts as a single transaction. Call pickup() just once, and dropoff() just once, with the relevant transaction ID.
  • A shared ride for two separately billed passengers counts as two billable transactions, even if the passengers are picked up and dropped off at the same locations. Call pickup() with both transaction IDs (one for each transaction) when the driver picks up the passengers, and call dropoff() with both transaction IDs when the driver drops off the passengers.
  • Discretionary stopovers do not count as separate billable transactions. Examples include breaking the journey to pick up coffee, or to drop off a co-passenger who is not separately billed. Do not call dropoff() for stopovers like these as normal.
  • If your organization bills some rides indirectly rather than billing at ride time, you must treat these rides as if billing is per ride. For example, your organization may provide a monthly subscription model for unlimited rides. Call pickup() and dropoff() for these rides.
  • If your organization provides bus services that pick up and drop off passengers at a fixed set of stops but do not keep track of the individuals who get in and out at each stop, you must get a separate product license. These types of bus services are outside the scope of per-transaction billing.
  • If your organization provides vehicle for hire services that allow a passenger to make unlimited stops over an extended time period that is all billed as one fee, you must get a separate product license. These services are outside the scope of the per-transaction billing.

Guidelines for delivery transactions:

  • Navigation sessions not involving an item for delivery (for example, driving to a store for picking up goods to be delivered) do not count as billable transactions.
  • The pickup and dropoff of an order from a single location counts as one billable transaction. An order may include multiple physical objects - for example, two bags of groceries. Call pickup() when the driver picks up the order, and dropoff() when the driver delivers the order.
  • When a driver picks up items from multiple locations (for example, stores or restaurants) as part of the same order, each location counts as a separate billable transaction. Use a different transaction ID for each location.
  • When a driver picks up items for multiple customers’ orders from the same location, each order counts as a separate billable transaction. Use a different transaction ID for each order.
  • When two drivers separately pick up and drop off items as part of the same customer order, each driver's delivery counts as a separate billable transaction, even if the items are from the same store location. Use a different transaction ID for each driver.