# Fulfillment Time and Fees (Legacy Only)

> [!NOTE]
> **Objective:** Learn how to specify order fulfillment time and fees for pickup and delivery food ordering action links, and how to update the values as it changes.

> [!NOTE]
> **Note:** This guide only applies to partners who are currently onboarding inventory through our Actions Center Ordering Redirect Integration with food ordering actions.

This tutorial walks through:

1. A high level description of what fee \& fulfillment time use cases are supported
2. Specific instructions on how to specify order fulfillment time and fees for [`action_link`(s)](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition) in your feeds
3. Expectations for accuracy

For a full feed sample that shows usage of order fulfillment time and fees, see the
[Ordering Redirect EPA sample](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/action-link-feeds/sample-feed).

## Fee \& fulfillment time use cases

### Fee use cases


We provide several different ways to specify fees. The points below describe the different use
cases supported, along with some example language similar to what the user will see on the
front end.

- Fixed Fee: "Delivery fee $5" or "Service fee $5"
- Percentage Fee: "Delivery fee 5%" or "Service fee 5%"
- Fee Ranges: "Delivery Fees $2-$10" or "Service Fees 3%-6%"
- Open Ended Ranges: "Delivery Fees start at 5%" or "Service Fees up to $20"


As shown in the examples above, fees can be specified as either a delivery fee or service fee.
It is also possible to specify multiple fees (e.g. "Service fee 5%-10%, Delivery Fee $5").


Not supported are use cases that require fees to be updated throughout the day, or to change
based on information about the user.

### Fulfillment Time use cases


We allow several different formats for specifying availability time to help ensure you're
providing accurate data. The points below describe the different use cases supported, along
with some example language similar to what the user will see on the front end.

- Fixed Times: "Delivers in 30 min" or "Pickup in 15 min"
- Time Ranges: "Delivers in 30 min-1 hr" or "Pickup in 15-20 min"
- Open Ended Time Ranges: "Delivers in more than 10 mins" or "Pickup in less than 1 hr"


Fulfillment time can be specified for both pickup and delivery using a common format
(described below). As shown in the examples above, the text shown to users will
reflect the [fulfilment
type](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/action-link-feeds/ordering-action-links-delivery-and-takeout) specified in the action link.


Not supported are use cases that require times to be updated throughout the day, or to change
based on information about the user.

## Specifying order fulfillment time through feeds

Order fulfillment time for action links is included in the Merchant feed
[`action_link`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition)
message, as part of the
[`food_ordering_metadata`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#FoodOrderingMetadata-definition)
field. For each
[`action_link`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition)
associated with the merchant, you are required to provide fulfillment
information using one of the message paths.

### Fixed Fulfillment Time

- `Merchant.action_link.food_ordering_metadata.fulfillment_lead_time_duration`

This messages should be in the following format:

```json
{
  "fulfillment_lead_time_duration": {
    "seconds" : 1800
  }
}
```

### Range Fulfillment Time

- `Merchant.action_link.food_order_metadata.fulfillment_lead_time_duration_range`

This message should be in the following format:

```json
{
  "fulfillment_lead_time_duration_range": {
    "min_duration": {
       "seconds" : 1800
     },
    "max_duration": {
     "seconds" : 2400
    }
  }
}
```

> [!WARNING]
> **Warning:** Do **not** specify both `fulfillment_lead_time_duration` and `fulfillment_lead_time_duration_range` as part of a single [`action_link`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition) object.

> [!NOTE]
> **Note:** The `fulfillment_lead_time_duration`, `fulfillment_lead_time_duration_range.min_duration`, `fulfillment_lead_time_duration_range.max_duration` are of type [`google.protobuf.Duration`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/duration.proto) and provides users with an ETA for their fulfillment action.

> [!NOTE]
> **Note:** If a single merchant has multiple fulfillment options (pickup and delivery), the order fulfillment time must be specified separately using two separate [`action_link`(s)](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition). Please review [Differentiating between Food Ordering Pickup and Delivery Tutorial](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/action-link-feeds/ordering-action-links-delivery-and-takeout) to understand providing multiple [`action_link`(s)](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition) per merchant.

> [!NOTE]
> **Note:** For the reference definition of [`food_ordering_metadata`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#FoodOrderingMetadata-definition), see the Merchant feed reference. For a feed sample that includes order fulfillment time in JSON format, see [Food Ordering Metadata Code Sample](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/action-link-feeds/sample-feed)

## Specifying fees through feeds

Similar to order fulfillment time, fees can be included as part of the
[`action_link`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition) message under the [`food_ordering_metadata`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#FoodOrderingMetadata-definition)
field. For each [`action_link`](https://developers.google.com/actions-center/verticals/ordering/redirect/reference/feeds/merchants-feed#ActionLink-definition) associated with a merchant you can
provide fee information using the message path:

`merchant.action_link.food_ordering_metadata.fee_details`
Below are several examples of the different use cases.

- A fixed delivery fee of $1.99:

  ```json
  [
    {
      "type": "DELIVERY",
      "fee_amount": {
        "amount": {
          "currency_code": "USD",
          "units": "1",
          "nanos": "990000000"
        }
      }
    }
  ]
  ```
- A percentage delivery fee of 5.6%.

  ```json
  [
    {
      "type": "DELIVERY",
      "fee_amount": {
        "cart_percentage": {
          "value": "5.6"
        }
      }
    }
  ]
  ```
- A service fee range from $1.99 to $9.99

  ```json
  [
    {
      "type": "SERVICE",
      "fee_amount": {
        "amount_range": {
          "min_amount": {
            "currency_code": "USD",
            "units": "1",
            "nanos": "990000000"
          },
          "max_amount": {
            "currency_code": "USD",
            "units": "9",
            "nanos": "990000000"
          }
        }
      }
    }
  ]
  ```
- A service fee percentage range from 1.2% to 2.7%

  ```json
  [
    {
      "type": "SERVICE",
      "fee_amount": {
        "cart_percentage": {
          "value_range": {
            "min_value": "1.2",
            "max_value": "2.7"
          }
        }
      }
    }
  ]
  ```
- Two fees, a service fee of $5, and a delivery fee of 1.2%.

  ```json
  [
    {
      "type": "SERVICE",
      "fee_amount": {
        "amount": {
          "currency_code": "USD",
          "units": "5",
          "nanos": "0"
        }
      }
    },
    {
      "type": "DELIVERY",
      "fee_amount": {
        "cart_percentage": {
          "value": "1.2"
        }
      }
    }
  ]
  ```

> [!NOTE]
> **Note:** The `amount` and `amount_range` entries are of type [`google.type.Money`](https://github.com/googleapis/googleapis/blob/master/google/type/money.proto)

## Fee \& fulfillment time accuracy

### Fee accuracy

When you provide fee data for a merchant, we expect you to provide an accurate representation
of your fees. You should include all delivery and service fees that may apply to an order.

We recognize that fees may vary over time and across users. For this reason we offer the
ability to specify fees as ranges, including open ended ranges. In cases where fees can vary
significantly be sure that the range provided encompasses the fees a user could see during
their transaction.

If you are unsure of specifically what is required in your case, reach out to your
Actions Center contact.

### Order fulfillment time accuracy

We understand that the specifics of order fulfillment
time change based on a variety of factors. These factors include:

- Changes to order fulfillment time based on order size
- Changes to order fulfillment time based on time to complete ordering and checkout
- Latency between when order fulfillment time changes are updated through feeds
- The user's delivery address.

Any of these factors may lead to situations where the order fulfillment
time displayed to the user initially is not the exact fulfillment time they
will see at checkout. The goal of the fulfillment time implementation is not
to eliminate these entirely, but to provide clear information to users as
often as possible.

Partners are expected to provide an implementation that leads to accurate
fulfillment time displayed to users as often as is possible, on a best effort
basis. If there is significant variability in timing due to these factors we suggest
you provide a range of times that encompass that variability.
Additionally, if fulfillment time does change due to order details,
this should be clearly shown to users when the arrive in your ordering flow.

If you are unsure of specifically what
is required in your case, reach out to your Actions Center contact.