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 Service feeds.
- Expectations for accuracy
For a full feed sample that shows usage of order fulfillment time and fees, see the Ordering Redirect EPA sample.
Fees
We provide several different ways to specify fees, such as:
- 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"
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 change based on information about the user.
Fee Examples
Delivery and Pickup fees
Application supports the `DELIVERY` and `SERVICE` fee types.Delivery
{ "fee": { "fee_id": "12345/delivery_fee", "fee_type": "DELIVERY", "fixed_amount": { "currency_code": "USD", "units": 10, "nanos": 0 }, "service_ids": ["service/entity002"] } }
Service
{ "fee": { "fee_id": "12345/service_fee", "fee_type": "SERVICE", "fixed_amount": { "currency_code": "USD", "units": 10, "nanos": 0 }, "service_ids": ["service/entity002"] } }
Different fee types
The following outlines some easy-to-use examples for specifying a chosen fee type.Fixed
{ "fee": { "fee_id": "12345/delivery_fee", "fee_type": "DELIVERY", "fixed_amount": { "currency_code": "USD", "units": 10, "nanos": 0 }, "service_ids": ["service/entity002"] } }
Cart percentage
{ "fee": { "fee_id": "12345/delivery_fee", "fee_type": "DELIVERY", "cart_percentage": { "base_value": { "currency_code": "USD", "units": 3, "nanos": 500000000 }, "percentage_of_cart_value": 10 }, "service_ids": [ "service/entity002" ] } }
Range
{ "fee": { "fee_id": "12345/delivery_fee", "fee_type": "DELIVERY", "range_amount": { "min_amount": { "currency_code": "USD", "units": 3, "nanos": 500000000 }, "max_amount": { "currency_code": "USD", "units": 5, "nanos": 600000000 } }, "service_ids": [ "service/entity002" ] } }
Fulfillment Time
We allow several different formats for specifying availability time to help ensure you're providing accurate data. The following points describe the different use cases supported, along with some example language similar to what the user will see on the frontend.
- 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"
Fulfillment time can be specified for both pickup and delivery using a common format (described below).
Not supported are use cases that require ETAs to change based on information about the user.
Fulfillment time examples
Order fulfillment time for action links is included in the Services feed
ETA
message, as part of the
FoodOrderingService
field.
Fixed
{ "service": { "service_id": "service-id", "service_type": "TAKEOUT", "parent_entity_id": "entity-id", "lead_time": { "min_lead_time_duration": "900s" }, "action_link_id": "action-link-id" } },
Time range
{ "service": { "service_id": "service-id", "service_type": "TAKEOUT", "parent_entity_id": "entity-id", "lead_time": { "min_lead_time_duration": "900s" "max_lead_time_duration": "1200s" }, "action_link_id": "action-link-id" } },
Fulfillment time windows
With ServiceHours,
fulfillment times can be set for a specific time window. The default
lead_time set in the
FoodOrderingService is used
when outside of service hour time windows.
lead_time of
2400s will be displayed from 11:00am to 1:30pm.
The
lead_time of 1200s will be displayed before
11:00am and after 1:30pm.
{ "data": [ { "service": { "service_id": "merchant-1-service-delivery", "service_type": "DELIVERY", "parent_entity_id": "merchant-1", "lead_time": { "min_lead_time_duration": "1200s" }, "action_link_id": "merchant-1-takeout-delivery-action" } }, { "service_hours": { "hours_id": "merchant-1-advance-hours-delivery", "service_ids": ["merchant-1-service-delivery"], "asap_hours": [ { "time_windows": { "time_windows": { "open_time": { "hours": 11 }, "close_time": { "hours": 13, "minutes": 30 } } }, "lead_time": { "min_lead_time_duration": "2400s" } } ] } } ] }
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.
Timely updates to Fees and ETAs
Any changes using a normal feed upload can take at least 2 hours to process. This is especially important to note if you plan on changing ETAs frequently.
Partners are highly encouraged to implement Real-time Updates, which enables an API call to change the Service feed (including fees and ETAs) within 5 minutes or less.