Order specification

Order contains the information about a customer order, including information about each Line Item.

// An order for service appointments with a merchant.
message Order {
  // ID of this Order, chosen by the booking partner who handles the order
  // (required in CreateOrderResponse and ListOrdersResponse, must not be set in
  // CreateOrderRequest)
  string order_id = 1;
  // Personal information of the user making the order (required)
  UserInformation user_information = 2;
  // Information about payment transactions that relate to the Order.
  // (optional)
  PaymentInformation payment_information = 3;
  // The merchant that all services in this Order belong to.
  string merchant_id = 4;
  // Line items in this order.
  repeated LineItem item = 5;
}
// 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;

  // In handling CreateOrderRequest and CheckOrderFulfillabilityRequest,
  // the total price (excluding taxes) of the item must be verified to guard
  // against price changes. In CreateOrderResponse and
  // CheckOrderFulfillabilityResponse, the price should be updated to the
  // correct value if the value from the request was incorrect or outdated.
  // (reqired)
  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.
  IntakeFormAnswers intake_form_answers = 7;
}
// Status data that conveys why creating an order fails.
// OrderFailure is intended to primarily capture business logic errors.
message OrderFailure {
  enum Cause {
    // Default value: Don't use; amounts to an "unknown error"
    CAUSE_UNSPECIFIED = 0;
    // The order is no longer fulfillable.
    ORDER_UNFULFILLABLE = 1;
    // An error was encountered while processing the payment because the
    // provided credit card type was not accepted by the merchant. The credit
    // card type must be supplied in rejected_card_type.
    PAYMENT_ERROR_CARD_TYPE_REJECTED = 2;
    // An error was encountered while processing the payment because the
    // provided credit card was declined.
    PAYMENT_ERROR_CARD_DECLINED = 3;
    // An error was encountered while processing the payment for this order.
    // Use this value to indicate a general payment related error, only if the
    // error does not match to a specific payment error above.
    PAYMENT_ERROR = 4;
  }
  // The reason why the order failed. (required)
  Cause cause = 1;

  // (required only if cause is ORDER_UNFULFILLABLE)
  OrderFulfillability fulfillability = 2;

  // (required only if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED)
  CreditCardType rejected_card_type = 3;

  // This optional field is used for the partner to include additional
  // information for debugging purpose only. (optional)
  string description = 4;
}