This tutorial walks through:
- A high level description of what fee & fulfillment time use cases are supported
- Specific instructions on how to specify order fulfillment time and fees for
action_link(s) in your feeds - 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 } } }
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
- 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" } } } ]
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.