// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.shopping.merchant.accounts.v1beta;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/shopping/type/types.proto";
import "google/type/date.proto";

option go_package = "cloud.google.com/go/shopping/merchant/accounts/apiv1beta/accountspb;accountspb";
option java_multiple_files = true;
option java_outer_classname = "OnlineReturnPolicyProto";
option java_package = "com.google.shopping.merchant.accounts.v1beta";

// The service facilitates the management of a merchant's remorse return policy
// configuration, encompassing return policies for both ads and free listings
// ## programs. This API defines the following resource model:
//
// [OnlineReturnPolicy](/merchant/api/reference/rpc/google.shopping.merchant.accounts.v1beta#google.shopping.merchant.accounts.v1beta.OnlineReturnPolicy)
service OnlineReturnPolicyService {
  option (google.api.default_host) = "merchantapi.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/content";

  // Gets an existing return policy for a given merchant.
  rpc GetOnlineReturnPolicy(GetOnlineReturnPolicyRequest)
      returns (OnlineReturnPolicy) {
    option (google.api.http) = {
      get: "/accounts/v1beta/{name=accounts/*/onlineReturnPolicies/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists all existing return policies for a given merchant.
  rpc ListOnlineReturnPolicies(ListOnlineReturnPoliciesRequest)
      returns (ListOnlineReturnPoliciesResponse) {
    option (google.api.http) = {
      get: "/accounts/v1beta/{parent=accounts/*}/onlineReturnPolicies"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a new return policy for a given merchant.
  rpc CreateOnlineReturnPolicy(CreateOnlineReturnPolicyRequest)
      returns (OnlineReturnPolicy) {
    option (google.api.http) = {
      post: "/accounts/v1beta/{parent=accounts/*}/onlineReturnPolicies"
      body: "online_return_policy"
    };
    option (google.api.method_signature) = "parent";
    option (google.api.method_signature) = "parent,online_return_policy";
  }

  // Updates an existing return policy for a given merchant.
  rpc UpdateOnlineReturnPolicy(UpdateOnlineReturnPolicyRequest)
      returns (OnlineReturnPolicy) {
    option (google.api.http) = {
      patch: "/accounts/v1beta/{online_return_policy.name=accounts/*/onlineReturnPolicies/*}"
      body: "online_return_policy"
    };
    option (google.api.method_signature) = "online_return_policy,update_mask";
  }

  // Deletes an existing return policy.
  rpc DeleteOnlineReturnPolicy(DeleteOnlineReturnPolicyRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/accounts/v1beta/{name=accounts/*/onlineReturnPolicies/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// Request message for the `GetOnlineReturnPolicy` method.
message GetOnlineReturnPolicyRequest {
  // Required. The name of the return policy to retrieve.
  // Format: `accounts/{account}/onlineReturnPolicies/{return_policy}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "merchantapi.googleapis.com/OnlineReturnPolicy"
    }
  ];
}

// Request message for the `CreateOnlineReturnPolicy` method.
message CreateOnlineReturnPolicyRequest {
  // Required. The merchant account for which the return policy will be created.
  // Format: `accounts/{account}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "merchantapi.googleapis.com/OnlineReturnPolicy"
    }
  ];

  // Required. The return policy object to create.
  OnlineReturnPolicy online_return_policy = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Request message for the `UpdateOnlineReturnPolicy` method. The method
// supports field masks and when the mask is provided, only the fields specified
// in the mask are updated.
message UpdateOnlineReturnPolicyRequest {
  // Required. The online return policy to update.
  // The online return policy's `name` field is used to identify the
  // online return policy to be updated.
  OnlineReturnPolicy online_return_policy = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. List of fields being updated.
  //
  // The following fields are supported (in both `snake_case` and
  // `lowerCamelCase`):
  //
  // - `accept_defective_only`
  // - `accept_exchange`
  // - `item_conditions`
  // - `policy`
  // - `process_refund_days`
  // - `restocking_fee`
  // - `return_methods`
  // - `return_policy_uri`
  // - `return_shipping_fee`
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Request message for the `DeleteOnlineReturnPolicy` method.
message DeleteOnlineReturnPolicyRequest {
  // Required. The name of the return policy to delete.
  // Format: `accounts/{account}/onlineReturnPolicies/{return_policy}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "merchantapi.googleapis.com/OnlineReturnPolicy"
    }
  ];
}

// Request message for the `ListOnlineReturnPolicies` method.
message ListOnlineReturnPoliciesRequest {
  // Required. The merchant account for which to list return policies.
  // Format: `accounts/{account}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "merchantapi.googleapis.com/OnlineReturnPolicy"
    }
  ];

  // Optional. The maximum number of `OnlineReturnPolicy` resources to return.
  // The service returns fewer than this value if the number of return policies
  // for the given merchant is less that than the `pageSize`. The default value
  // is 10. The maximum value is 100; If a value higher than the maximum is
  // specified, then the `pageSize` will default to the maximum
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListOnlineReturnPolicies`
  // call. Provide the page token to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to
  // `ListOnlineReturnPolicies` must match the call that provided the page
  // token. The token returned as
  // [nextPageToken][google.shopping.merchant.accounts.v1beta.ListOnlineReturnPoliciesResponse.next_page_token]
  // in the response to the previous request.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for the `ListOnlineReturnPolicies` method.
message ListOnlineReturnPoliciesResponse {
  // The retrieved return policies.
  repeated OnlineReturnPolicy online_return_policies = 1;

  // A token, which can be sent as `pageToken` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// [Online return policy](https://support.google.com/merchants/answer/10220642)
// object. This is currently used to represent return policies for ads and free
// listings programs.
message OnlineReturnPolicy {
  option (google.api.resource) = {
    type: "merchantapi.googleapis.com/OnlineReturnPolicy"
    pattern: "accounts/{account}/onlineReturnPolicies/{return_policy}"
    plural: "onlineReturnPolicies"
    singular: "onlineReturnPolicy"
  };

  // The return shipping fee. This can either be a fixed fee or a boolean to
  // indicate that the customer pays the actual shipping cost.
  message ReturnShippingFee {
    // Return shipping fee types.
    enum Type {
      // Default value. This value is unused.
      TYPE_UNSPECIFIED = 0;

      // The return shipping fee is a fixed value.
      FIXED = 1;

      // Customers will pay the actual return shipping fee.
      CUSTOMER_PAYING_ACTUAL_FEE = 2;
    }

    // Required. Type of return shipping fee.
    Type type = 1 [(google.api.field_behavior) = REQUIRED];

    // Fixed return shipping fee amount. This value is only applicable when type
    // is `FIXED`. We will treat the return shipping fee as free if type is
    // `FIXED` and this value is not set.
    google.shopping.type.Price fixed_fee = 2;
  }

  // The restocking fee. This can be a flat fee or a micro percent.
  message RestockingFee {
    oneof type {
      // Fixed restocking fee.
      google.shopping.type.Price fixed_fee = 1;

      // Percent of total price in micros. 15,000,000 means 15% of the total
      // price would be charged.
      int32 micro_percent = 2;
    }
  }

  // The available policies.
  message Policy {
    // Return policy types.
    enum Type {
      // Default value. This value is unused.
      TYPE_UNSPECIFIED = 0;

      // The number of days within which a return is valid after delivery.
      NUMBER_OF_DAYS_AFTER_DELIVERY = 1;

      // No returns.
      NO_RETURNS = 2;

      // Life time returns.
      LIFETIME_RETURNS = 3;
    }

    // Policy type.
    Type type = 1;

    // The number of days items can be returned after delivery, where one day
    // is defined as 24 hours after the delivery timestamp. Required for
    // `NUMBER_OF_DAYS_AFTER_DELIVERY` returns.
    int64 days = 2;
  }

  message SeasonalOverride {
    // ReturnWindow: Specifies either a fixed return date or the number of
    // days (from the delivery date) until which a product can be returned.
    // [Merchant Return Days](https://schema.org/merchantReturnDays)
    oneof return_window {
      // Number of days (from the delivery date) that the product can be
      // returned.
      int32 return_days = 5;

      // Fixed end date until which the product can be returned.
      google.type.Date return_until_date = 6;
    }

    // Required. Display name of this seasonal override in Merchant Center.
    string label = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Defines the date range when this seasonal override applies.
    // Both start_date and end_date are inclusive.
    // The dates of the seasonal overrides should not overlap.
    google.type.Date start_date = 2 [(google.api.field_behavior) = REQUIRED];

    // Required. seasonal override end date (inclusive).
    google.type.Date end_date = 3 [(google.api.field_behavior) = REQUIRED];
  }

  // The available return methods.
  enum ReturnMethod {
    // Default value. This value is unused.
    RETURN_METHOD_UNSPECIFIED = 0;

    // Return by mail.
    BY_MAIL = 1;

    // Return in store.
    IN_STORE = 2;

    // Return at a kiosk.
    AT_A_KIOSK = 3;
  }

  // The available item conditions.
  enum ItemCondition {
    // Default value. This value is unused.
    ITEM_CONDITION_UNSPECIFIED = 0;

    // New.
    NEW = 1;

    // Used.
    USED = 2;
  }

  // The available return label sources.
  enum ReturnLabelSource {
    // Default value. This value is unused.
    RETURN_LABEL_SOURCE_UNSPECIFIED = 0;

    // Download and print.
    DOWNLOAD_AND_PRINT = 1;

    // Label include in the package.
    IN_THE_PACKAGE = 2;

    // Customer to provide.
    CUSTOMER_RESPONSIBILITY = 3;
  }

  // Identifier. The name of the `OnlineReturnPolicy` resource.
  // Format: `accounts/{account}/onlineReturnPolicies/{return_policy}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. Return policy ID generated by Google.
  string return_policy_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Immutable. This field represents the unique user-defined label of
  // the return policy. It is important to note that the same label cannot be
  // used in different return policies for the same country. Unless a product
  // specifies a specific label attribute, policies will be automatically
  // labeled as 'default'. To assign a custom return policy to certain product
  // groups, follow the instructions provided in the [Return policy label]
  // (https://support.google.com/merchants/answer/9445425).
  // The label can contain up to 50 characters.
  string label = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Required. Immutable. The countries of sale where the return policy applies.
  // The values must be a valid 2 letter ISO 3166 code.
  repeated string countries = 4 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Optional. The return policy.
  Policy policy = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Overrides to the general policy for orders placed during a
  // specific set of time intervals.
  repeated SeasonalOverride seasonal_overrides = 14
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The restocking fee that applies to all return reason categories.
  // This would be treated as a free restocking fee if the value is not set.
  RestockingFee restocking_fee = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The return methods of how customers can return an item. This
  // value is required to not be empty unless the type of return policy is
  // noReturns.
  repeated ReturnMethod return_methods = 7
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The item conditions accepted for returns must not be empty unless
  // the type of return policy is 'noReturns'.
  repeated ItemCondition item_conditions = 8
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The return shipping fee. Should be set only when customer need to
  // download and print the return label.
  ReturnShippingFee return_shipping_fee = 9
      [(google.api.field_behavior) = OPTIONAL];

  // Required. The return policy uri. This can used by Google to do a sanity
  // check for the policy. It must be a valid URL.
  string return_policy_uri = 10 [(google.api.field_behavior) = REQUIRED];

  // Optional. This field specifies if merchant
  // only accepts defective products for returns.
  optional bool accept_defective_only = 11
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The field specifies the number of
  // days it takes for merchants to process refunds.
  optional int32 process_refund_days = 12
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. This field specifies if merchant
  // allows customers to exchange products.
  optional bool accept_exchange = 13 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The field specifies the return
  // label source.
  optional ReturnLabelSource return_label_source = 15
      [(google.api.field_behavior) = OPTIONAL];
}
