In light of COVID-19, please review the latest announcement regarding the Reserve with Google guidelines for supporting users and merchants during this time. Additionally, since we are operating with a limited support team, it may take longer to connect with us. Thank you for your patience, and we value your partnership.

OrderFulfillability specification

OrderFulfillability contains the information about the fulfillability of a customer order, including its individual Line Items.

OrderFulfillability Definition

message OrderFulfillability {
  // The result of an order fulfillability check.
  enum OrderFulfillabilityResult {
    // Default value: Don't use.
    ORDER_FULFILLABILITY_RESULT_UNSPECIFIED = 0;
    // The order can be fulfilled.
    CAN_FULFILL = 1;
    // The order cannot be fulfilled due to one or more unfulfillable line
    // item(s).
    UNFULFILLABLE_LINE_ITEM = 2;
    // The combination of the line items requested cannot be fulfilled.
    UNFULFILLABLE_SERVICE_COMBINATION = 3;
    // The order cannot be fulfilled due to reasons that do not fall into the
    // categories above.
    ORDER_UNFULFILLABLE_OTHER_REASON = 4;
  }

  OrderFulfillabilityResult result = 1;
  // Fulfillability results of all line items in this order (required).
  repeated LineItemFulfillability item_fulfillability = 2;
  // Additional description of the reason if the item is unfulfillable.
  // (optional)
  string unfulfillable_reason = 3;
}

LineItemFulfillability Definition

// Fulfillability of a line item.
message LineItemFulfillability {
  // The line item of question. (required)
  LineItem item = 1;

  // The result of a line item fulfillability check.
  enum ItemFulfillabilityResult {
    // Default value: Don't use.
    ITEM_FULFILLABILITY_RESULT_UNSPECIFIED = 0;
    // This line item can be fulfilled.
    CAN_FULFILL = 1;
    // No adequate availability for the slot requested.
    SLOT_UNAVAILABLE = 2;
    // Child tickets cannot be booked without an adult ticket.
    CHILD_TICKETS_WITHOUT_ADULT = 6;
    // The combination of ticket types requested cannot be fulfilled.
    UNFULFILLABLE_TICKET_COMBINATION = 3;
    // The total price of this line item is not correct.
    INCORRECT_PRICE = 4;
    // The line item cannot be fulfilled since a ticket constraint specified by
    // the partner has been violated.
    TICKET_CONSTRAINT_VIOLATED = 7;
    // The line item cannot be fulfilled for reasons that do not fall into
    // the categories above.
    ITEM_UNFULFILLABLE_OTHER_REASON = 5;
  }
  // (required)
  ItemFulfillabilityResult result = 2;
  // Additional description of the reason if the item is unfulfillable.
  // (optional)
  string unfulfillable_reason = 3;
  // Updated availability for this slot can be piggybacked in
  // CheckOrderFulfillabilityResponse.
  message UpdatedAvailability {
    // Number of available spots for the given slot. 0 indicates no
    // availability. (required)
    int32 spots_open = 1;
  }
  // (optional)
  UpdatedAvailability availability = 4;
  // If the item can be fulfilled and any ticket in the booking has changed from
  // the price in the request at the individual ticket level, please use this
  // field to return updated ticket types.
  // Ticket type is required only when the actual price of individual tickets
  // changed from the price in the request. Ticket type is NOT required for
  // price decrease because of deals or promotions, combo tickets, group
  // tickets, reduced price for special group of users. In this case, the
  // individual ticket price has not changed but there is a price decrease for
  // the booking.
  // If the price of a single ticket type changes, please return the following:
  //   1. Populate 'ticket_type' message for every distinct ticket_type_id
  //     specified in the request.
  //     -- Required fields in the TicketType message: 'ticket_type_id', 'price'
  //     -- Optional fields in the TicketType message: 'fees_and_tax',
  //       'localized_short_description', 'localized_option_description',
  //       'option_description', 'short_description'
  //   2. Updated price in the LineItem.
  //   3. Corresponding warning reason enum.
  // Ticket is the quantity unit of a given service at a certain time slot that
  // users can make reservations for. For example, a spot on a raft trip or an
  // admission to a museum. TicketType is used to differentiate among tickets
  // with different prices and/or availabilities due to different user types or
  // different service attributes. If non-empty, all available ticket types for
  // this slot with up-to-date prices should be listed without omitting any.
  // (optional)
  repeated TicketType ticket_type = 5;

  // This proto will represent all the constraints violated by the user.
  // Below are all the ways in which a violated_constraint can be represented.
  //
  // 1 : Constraint violation for the entire line item.
  // { violated_ticket_constraint : { min_ticket_count : 5 } }
  //
  // 2 : Constraint violation for a ticket type within a line item.
  // { violated_ticket_constraint : { min_ticket_count : 5, ticket_id : "ttd1"}}  //
  // 3 : Constraint violation for multiple ticket types within a line item.
  // { violated_ticket_constraint : { min_ticket_count : 3, ticket_id : "ttd1"}}  // { violated_ticket_constraint : { min_ticket_count : 4, ticket_id : "ttd2"}}  //
  // 4 : Constraint violation for entire line item  as well as an override
  // for multiple ticket types within the availability slot.
  // { violated_ticket_constraint : { min_ticket_count : 8 } }
  // { violated_ticket_constraint : { min_ticket_count : 3, ticket_id : "ttd1"}}  // { violated_ticket_constraint : { min_ticket_count : 4, ticket_id : "ttd2"}}  //
  message ViolatedTicketConstraint {
    oneof value {
      int32 min_ticket_count = 1;
      int32 max_ticket_count = 2;
    }
    reserved 3;
    // The absence of this field indicates that the constraint applies to
    // the entire line item.
    string ticket_id = 4;
  }
  // This must be set if ItemFulfillabilityResult is TICKET_CONSTRAINT_VIOLATED.
  repeated ViolatedTicketConstraint violated_ticket_constraint = 6;
}

LineItem Definition

// A single item in an Order--the booking of a single service in a single time
// slot.
message LineItem {
  // ID of the merchant Service. (required)
  string service_id = 1;
  // Start time of the appointment slot in seconds of UTC time since Unix epoch.
  // (required)
  int64 start_sec = 2;
  // Duration of the appointment slot in seconds. (required)
  int64 duration_sec = 3;

  message OrderedTickets {
    string ticket_id = 1;
    int32 count = 2;
  }
  // Number of tickets ordered by Ticket Type.
  repeated OrderedTickets tickets = 4;

  // The price should be updated to the correct value if the line item can be
  // fulfilled but the value from the request has changed. The updated price
  // should align with the enum in the 'warning_reason' field below, otherwise
  // the booking will be considered as failure. (required)
  Price price = 5;

  // Status of the Line Item. (required in CreateOrderResponse and
  // ListOrdersResponse; should not be set in requests)
  BookingStatus status = 6;

  // The user's answers to merchant questions for this services.
  // If there are both service level and per-ticket answers, this message will
  // be ordered with service level answers first and per-ticket answers after.
  // Will not be set in CheckOrderFulfillabilityRequest.
  IntakeFormAnswers intake_form_answers = 7;

  enum WarningReason {
    UNSPECIFIED_WARNING_REASON = 0;
    // This Line Item can be fulfilled and has increased in price.
    PRICE_INCREASE = 1;
    // This Line Item can be fulfilled and has decreased in price.
    PRICE_DECREASE = 2;
  }
  // If the total price is different from the price in the request, please use
  // this field to indicate a price change. The enum has to be aligned with the
  // actual price change, otherwise the booking will be considered as failure.
  WarningReason warning_reason = 8;
}

Fees Definition

// Breakdown of the specific, partner-named per-ticket and per-order fees and
// taxes.
message Fees {
  // Fees and taxes that must be paid for each ticket the user purchases.
  repeated SpecificPerTicketFee per_ticket_fee = 1;
  // Fees and taxes that must be paid once per order, regardless of the number
  // of tickets purchased.
  repeated SpecificPerOrderFee per_order_fee = 2;
}

// The specific partner-named fees that must be paid for each ticket the user
// purchases.
message SpecificPerTicketFee {
  // ID of a ticket type.
  string ticket_id = 1;
  // ID of the parent service of this ticket_type.
  string service_id = 4;
  // A localized partner-provided name for this fee or tax.
  string fee_name = 2;
  // The amount of the fee or tax.
  Price fee_amount = 3;
}

// The specific partner-named fees that must be paid once per order, regardless
// of number of tickets.
message SpecificPerOrderFee {
  // A localized partner-provided name for this fee or tax.
  string fee_name = 1;
  // The amount of the fee or tax.
  Price fee_amount = 2;
}