1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.channel.v1;
18
19import "google/api/field_behavior.proto";
20import "google/api/resource.proto";
21import "google/cloud/channel/v1/common.proto";
22import "google/cloud/channel/v1/offers.proto";
23import "google/cloud/channel/v1/products.proto";
24import "google/protobuf/timestamp.proto";
25
26option go_package = "cloud.google.com/go/channel/apiv1/channelpb;channelpb";
27option java_multiple_files = true;
28option java_outer_classname = "EntitlementsProto";
29option java_package = "com.google.cloud.channel.v1";
30
31// An entitlement is a representation of a customer's ability to use a service.
32message Entitlement {
33  option (google.api.resource) = {
34    type: "cloudchannel.googleapis.com/Entitlement"
35    pattern: "accounts/{account}/customers/{customer}/entitlements/{entitlement}"
36  };
37
38  // Indicates the current provisioning state of the entitlement.
39  enum ProvisioningState {
40    // Not used.
41    PROVISIONING_STATE_UNSPECIFIED = 0;
42
43    // The entitlement is currently active.
44    ACTIVE = 1;
45
46    // The entitlement is currently suspended.
47    SUSPENDED = 5;
48  }
49
50  // Suspension reason for an entitlement if
51  // [provisioning_state][google.cloud.channel.v1.Entitlement.provisioning_state]
52  // = SUSPENDED.
53  enum SuspensionReason {
54    // Not used.
55    SUSPENSION_REASON_UNSPECIFIED = 0;
56
57    // Entitlement was manually suspended by the Reseller.
58    RESELLER_INITIATED = 1;
59
60    // Trial ended.
61    TRIAL_ENDED = 2;
62
63    // Entitlement renewal was canceled.
64    RENEWAL_WITH_TYPE_CANCEL = 3;
65
66    // Entitlement was automatically suspended on creation for pending ToS
67    // acceptance on customer.
68    PENDING_TOS_ACCEPTANCE = 4;
69
70    // Other reasons (internal reasons, abuse, etc.).
71    OTHER = 100;
72  }
73
74  // Output only. Resource name of an entitlement in the form:
75  // accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}.
76  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
77
78  // Output only. The time at which the entitlement is created.
79  google.protobuf.Timestamp create_time = 5
80      [(google.api.field_behavior) = OUTPUT_ONLY];
81
82  // Output only. The time at which the entitlement is updated.
83  google.protobuf.Timestamp update_time = 6
84      [(google.api.field_behavior) = OUTPUT_ONLY];
85
86  // Required. The offer resource name for which the entitlement is to be
87  // created. Takes the form: accounts/{account_id}/offers/{offer_id}.
88  string offer = 8 [
89    (google.api.field_behavior) = REQUIRED,
90    (google.api.resource_reference) = {
91      type: "cloudchannel.googleapis.com/Offer"
92    }
93  ];
94
95  // Commitment settings for a commitment-based Offer.
96  // Required for commitment based offers.
97  CommitmentSettings commitment_settings = 12;
98
99  // Output only. Current provisioning state of the entitlement.
100  ProvisioningState provisioning_state = 13
101      [(google.api.field_behavior) = OUTPUT_ONLY];
102
103  // Output only. Service provisioning details for the entitlement.
104  ProvisionedService provisioned_service = 16
105      [(google.api.field_behavior) = OUTPUT_ONLY];
106
107  // Output only. Enumerable of all current suspension reasons for an
108  // entitlement.
109  repeated SuspensionReason suspension_reasons = 18
110      [(google.api.field_behavior) = OUTPUT_ONLY];
111
112  // Optional. This purchase order (PO) information is for resellers to use for
113  // their company tracking usage. If a purchaseOrderId value is given, it
114  // appears in the API responses and shows up in the invoice. The property
115  // accepts up to 80 plain text characters. This is only supported for Google
116  // Workspace entitlements.
117  string purchase_order_id = 19 [(google.api.field_behavior) = OPTIONAL];
118
119  // Output only. Settings for trial offers.
120  TrialSettings trial_settings = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
121
122  // Association information to other entitlements.
123  AssociationInfo association_info = 23;
124
125  // Extended entitlement parameters. When creating an entitlement, valid
126  // parameter names and values are defined in the
127  // [Offer.parameter_definitions][google.cloud.channel.v1.Offer.parameter_definitions].
128  //
129  // For Google Workspace, the following Parameters may be accepted as input:
130  //
131  // - max_units: The maximum assignable units for a flexible offer
132  //
133  // OR
134  //
135  // - num_units: The total commitment for commitment-based offers
136  //
137  // The response may additionally include the following output-only Parameters:
138  //
139  // - assigned_units: The number of licenses assigned to users.
140  //
141  // For GCP billing subaccounts, the following Parameter may be accepted as
142  // input:
143  //
144  // - display_name: The display name of the billing subaccount.
145  repeated Parameter parameters = 26;
146
147  // Optional. The billing account resource name that is used to pay for this
148  // entitlement.
149  string billing_account = 28 [(google.api.field_behavior) = OPTIONAL];
150}
151
152// Definition for extended entitlement parameters.
153message Parameter {
154  // Name of the parameter.
155  string name = 1;
156
157  // Value of the parameter.
158  Value value = 2;
159
160  // Output only. Specifies whether this parameter is allowed to be changed. For
161  // example, for a Google Workspace Business Starter entitlement in commitment
162  // plan, num_units is editable when entitlement is active.
163  bool editable = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
164}
165
166// Association links that an entitlement has to other entitlements.
167message AssociationInfo {
168  // The name of the base entitlement, for which this entitlement is an add-on.
169  string base_entitlement = 1 [(google.api.resource_reference) = {
170    type: "cloudchannel.googleapis.com/Entitlement"
171  }];
172}
173
174// Service provisioned for an entitlement.
175message ProvisionedService {
176  // Output only. Provisioning ID of the entitlement. For Google Workspace, this
177  // is the underlying Subscription ID. For Google Cloud Platform, this is the
178  // Billing Account ID of the billing subaccount."
179  string provisioning_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
180
181  // Output only. The product pertaining to the provisioning resource as
182  // specified in the Offer.
183  string product_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
184
185  // Output only. The SKU pertaining to the provisioning resource as specified
186  // in the Offer.
187  string sku_id = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
188}
189
190// Commitment settings for commitment-based offers.
191message CommitmentSettings {
192  // Output only. Commitment start timestamp.
193  google.protobuf.Timestamp start_time = 1
194      [(google.api.field_behavior) = OUTPUT_ONLY];
195
196  // Output only. Commitment end timestamp.
197  google.protobuf.Timestamp end_time = 2
198      [(google.api.field_behavior) = OUTPUT_ONLY];
199
200  // Optional. Renewal settings applicable for a commitment-based Offer.
201  RenewalSettings renewal_settings = 4 [(google.api.field_behavior) = OPTIONAL];
202}
203
204// Renewal settings for renewable Offers.
205message RenewalSettings {
206  // If false, the plan will be completed at the end date.
207  bool enable_renewal = 1;
208
209  // If true and enable_renewal = true, the unit (for example seats or licenses)
210  // will be set to the number of active units at renewal time.
211  bool resize_unit_count = 2;
212
213  // Describes how a reseller will be billed.
214  PaymentPlan payment_plan = 5;
215
216  // Describes how frequently the reseller will be billed, such as
217  // once per month.
218  Period payment_cycle = 6;
219}
220
221// Settings for trial offers.
222message TrialSettings {
223  // Determines if the entitlement is in a trial or not:
224  //
225  // * `true` - The entitlement is in trial.
226  // * `false` - The entitlement is not in trial.
227  bool trial = 1;
228
229  // Date when the trial ends. The value is in milliseconds
230  // using the UNIX Epoch format. See an example [Epoch
231  // converter](https://www.epochconverter.com).
232  google.protobuf.Timestamp end_time = 2;
233}
234
235// TransferableSku represents information a reseller needs to view existing
236// provisioned services for a customer that they do not own.
237// Read-only.
238message TransferableSku {
239  // Describes the transfer eligibility of a SKU.
240  TransferEligibility transfer_eligibility = 9;
241
242  // The SKU pertaining to the provisioning resource as specified in the Offer.
243  Sku sku = 11;
244
245  // Optional. The customer to transfer has an entitlement with the populated
246  // legacy SKU.
247  Sku legacy_sku = 12 [(google.api.field_behavior) = OPTIONAL];
248}
249
250// Specifies transfer eligibility of a SKU.
251message TransferEligibility {
252  // Reason of ineligibility.
253  enum Reason {
254    // Not used.
255    REASON_UNSPECIFIED = 0;
256
257    // Reseller needs to accept TOS before transferring the SKU.
258    PENDING_TOS_ACCEPTANCE = 1;
259
260    // Reseller not eligible to sell the SKU.
261    SKU_NOT_ELIGIBLE = 2;
262
263    // SKU subscription is suspended
264    SKU_SUSPENDED = 3;
265  }
266
267  // Whether reseller is eligible to transfer the SKU.
268  bool is_eligible = 1;
269
270  // Localized description if reseller is not eligible to transfer the SKU.
271  string description = 2;
272
273  // Specified the reason for ineligibility.
274  Reason ineligibility_reason = 3;
275}
276