prepaid or postpaid. Describes whether money will be collected upfront or on explicit /complete call from partner. CURRENTLY ONLY prepaid is SUPPORTED.
partner_business_id
utf8_string(1..100)
partner’s id of business that is “fulfilling” the order
partner_order_id
utf8_string(1..64)
an order id provided by partner for this order for partner’s tracking purposes
sets the proportion of the total cost of goods which is given to the merchant. If this is not provided, it will default to the value in the partner contract. On updates, if this is missing, the existing merchant_commission_rate will be used. This field is only used as part of order create and update requests.
Validation
order_lines must have at least one OrderLineItem or OrderLineBooking or OrderLineMedicalCompliant.
order_lines must have at least one OrderLineTax ($0 amount is okay for states, cities, etc. with no tax). We are requiring tax lines (even for $0) to be explicit that Yelp doesn't handle tax (yet), and the partner is responsible for specifying it.
order_lines must total to $0 or greater
partner_business_id must map to a yelp_business_id, which we determined when they uploaded their business feed to us via Data Ingestion API
merchant_commission_rate is enabled on a per partner basis at this time.
Orders for food-related goods (food delivery, takeout)
booking
Orders that are reserving appointments (e.g. spas) or requesting a service at a future date (e.g. plumber, repairs)
hotel_reservation
Orders that reserve hotel rooms
restaurant_reservation
Orders that reserve tables at restaurants
goods
Orders for physical non-food items
club_service
Orders for club service (table booking and bottles)
medical_compliant
Orders that are reserving medical appointments (e.g. dentist, doctor)
OptionType enum
Type Value (utf8_string)
Description
at_customer
Service will be at customer’s address or food will be delivered to customer’s address
at_business
Service will be at business’ address or food will be picked up at business’ address
BillingType enum
Type Value (utf8_string)
Description
partner
Partner will collect payment from the business, which will in turn collect it directly from the customer. Yelp will debit Partner’s account for revenue sharing purposes.
yelp
Yelp will collect payment from the customer (via credit card). Yelp will credit Partner’s account for revenue sharing purposes.
CollectionType enum
Type Value (utf8_string)
Description
prepaid
Yelp will collect payment from the user as soon as order is submitted, without any explicit action from partner.
postpaid
NOT SUPPORTED.
OrderLine
OrderLine is polymorphic on the object field. The resources below describe the different types of OrderLines and what fields are required per type.
A line for specifying misc adjustments e.g. discounts, delivery fee, etc.
📘
Notes
OrderLine is polymorphic instead of Order
OrderLine loosely corresponds to lines you would see on customer receipt or invoice and its structure depends on the partner. More information can be placed in description or can be split out into another OrderLine.
OrderLineTax, OrderLineAdjustment, OrderLineTip
If OrderLineAdjustment is used for specifying service fee, Please prefix while specifying name property. For example, "Yelp Test" partner would provide name as "Yelp Test Service Fee".
Property
Type
Description
object
utf8_string(1..256)
one of OrderLineTax, OrderLineAdjustment, OrderLineTip
price for reservation (could be negative). This is total value of the service. At the service time, the customer is expected to pay (price - upfront_price)
partner_item_id
utf8_string(0..64)
partner’s unique id for what’s being purchased with this OrderLine
start_time
timestamp
start datetime of reservation
end_time
timestamp
(optional) end datetime of reservation
cancellation_policy
CancellationPolicy
(optional) polymorphic object
quantity
uint32
number of items being reserved
Validation
quantity must be >= 1 for all types
price is required for all types but may be 0
In cases where cancellation_policy object is missing, Yelp assumes that there is no cancellation policy to enforce, and the user can cancel an appointment without any penalty up to the start of the appointment.
Address
Property
Type
Description
object
utf8_string(1..255)
object type, value: Address
address1
utf8_string(0..255)
address line 1
address2
utf8_string(0..255)
(optional) address line 2
address3
utf8_string(0..255)
(optional) address line 3
city
utf8_string(1..255)
city / district / town / village
region
utf8_string(1..64)
state (US) or region
postal_code
utf8_string(1..64)
postal code
county
utf8_string(0..255)
(optional) county
country
utf8_string(2)
country code (ISO 3166-1 alpha 2)
Currency
Property
Type
Description
amount
decimal(10, 3)
currency amount with exact precision; number of decimal places should follow ISO 4217
currency_code
utf8_string(3)
3-char code ISO 4217
Validation
amount must be above -10,000,000 and below 10,000,000.
CustomerAddressConstraint
This is provided as an availablity_constraint of Opportunity
(optional) This is a list of constraints entered by the user. At the moment, it may be CustomerAddressConstraint
CancellationPolicy
A polymorphic object that describes when a particular cancellation action (e.g. it's ok to cancel, the user must contact business, etc). The following object types are supported.
describes a cancellation policy that is in effect if current time is within this many minutes before the appointment start time (E.g. 24 hours would be minutes_before=24*60)
indicates who should enforce the cancellation policy and how, in cases when User wants to cancel within cancellation policy window
ViolationActionEnum
Describes who should enforce the cancellation fee and how
Type Value (utf8_string)
Description
contact_business
Yelp will show user a message to call/contact the business for cancellation. Whether a cancellation fee is waived, or partially or fully applied is up to the discretion of the business/partner.
Opportunity
This resource represents a user's request to enter the ordering flow.
Property
Type
Description
opportunity_id
uuid_hex
unique identifier for this Opportunity
partner_business_id
utf8_string(1..100)
partner’s business id to check availability against. Partner provided this to Yelp via Data Ingestion.
waiting for user to provide billing/required information and to confirm purchase or reservation
charge_pending
waiting for the billing to charge user
update_pending
Yelp is processing an /update call
cancel_pending
Yelp is processing a /cancels call
ready_for_fulfillment
Order is in a completed state and Yelp is not waiting on the Partner to call any other API endpoint. Partner/business could fulfill orders in this state.
cancelled
order was cancelled by partner
cancelled_by_yelp
order was cancelled by Yelp because there has been no action on it after a while or for other reasons like security
cancelled_by_user
order was cancelled by user
cancel_by_user_pending
Yelp is processing a cancel by user request.
OperationType enum
Type Value (utf8_string)
Description
charge
user submitted purchase on the Yelp checkout page
update
update operation requested by partner
cancel
cancel operation requested by partner.
OperationStatus enum
Type Value (utf8_string)
Description
success
operation specified from OperationType is successful
This /cancel call would be in response to AWAITING_CANCEL_POLICY_RESOLUTION, which the case where a user initiated a cancel on the yelp, yelp notified the partner of user’s intent, and now yelp is waiting for the partner to call /cancels with an appropriate cancellation_fee and bring the order to one of the cancelled states. Yelp Platform Action: fully refund the order and set it to CANCELLED or CANCELLED_WITH_FEE state.
cancelled_by_partner
Administrative cancelled by partner. In this case, cancellation_fee should not be present in the POST request body. Yelp Platform Action: fully refund the order and set it to CANCELLED state.
customer_no_show
Business has reported to the partner that the customer was not at the appointment. cancellation_fee contains the penalty that business wishes to charge the customer. YTP Action: charge the user the cancellation_fee, and set the order to CANCELLED or CANCELLED_WITH_FEE as appropriate.
customer_contacted_business_to_cancel
Customer contacted the business and cancelled the appointment. cancellation_fee contains the penalty that business wishes to charge the customer. If customer cancels in time when and no penalty applies, cancellation_fee should be $0. YTP Action: charge the user the cancellation_fee, and set the order to CANCELLED or CANCELLED_WITH_FEE as appropriate.
customer_cancelled_through_yelp
This is an order cancelled by Yelp, most likely because a customer contacted Yelp requesting a cancel / disputing an order.
