Fulfillment Time and Fees (Legacy Only)

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: 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) 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.

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 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 message, as part of the food_ordering_metadata field. For each action_link 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:

{
  "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:

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

Warning: Do not specify both fulfillment_lead_time_duration and fulfillment_lead_time_duration_range as part of a single action_link object.

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 and provides users with an ETA for their fulfillment action.

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). Please review Differentiating between Food Ordering Pickup and Delivery Tutorial to understand providing multiple action_link(s) per merchant.

Note: For the reference definition of food_ordering_metadata, see the Merchant feed reference. For a feed sample that includes order fulfillment time in JSON format, see Food Ordering Metadata Code Sample

Specifying fees through feeds

Similar to order fulfillment time, fees can be included as part of the action_link message under the food_ordering_metadata field. For each action_link 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:

  [
    {
      "type": "DELIVERY",
      "fee_amount": {
        "amount": {
          "currency_code": "USD",
          "units": "1",
          "nanos": "990000000"
        }
      }
    }
  ]

• A percentage delivery fee of 5.6%.

  [
    {
      "type": "DELIVERY",
      "fee_amount": {
        "cart_percentage": {
          "value": "5.6"
        }
      }
    }
  ]

• A service fee range from $1.99 to $9.99

  [
    {
      "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%

  [
    {
      "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%.

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

Note: The amount and amount_range entries are of type google.type.Money

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.