# REST Resource: accounts.customers.entitlements

- [Resource: Entitlement](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Entitlement)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Entitlement.SCHEMA_REPRESENTATION)
- [CommitmentSettings](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#CommitmentSettings)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#CommitmentSettings.SCHEMA_REPRESENTATION)
- [RenewalSettings](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#RenewalSettings)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#RenewalSettings.SCHEMA_REPRESENTATION)
- [PaymentPlan](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#PaymentPlan)
- [Period](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Period)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Period.SCHEMA_REPRESENTATION)
- [PeriodType](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#PeriodType)
- [ProvisioningState](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisioningState)
- [ProvisionedService](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisionedService)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisionedService.SCHEMA_REPRESENTATION)
- [SuspensionReason](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#SuspensionReason)
- [TrialSettings](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#TrialSettings)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#TrialSettings.SCHEMA_REPRESENTATION)
- [AssociationInfo](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#AssociationInfo)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#AssociationInfo.SCHEMA_REPRESENTATION)
- [Parameter](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Parameter)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Parameter.SCHEMA_REPRESENTATION)
- [Value](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Value)
  - [JSON representation](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Value.SCHEMA_REPRESENTATION)
- [Methods](https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#METHODS_SUMMARY)

## Resource: Entitlement

An entitlement is a representation of a customer's ability to use a service.

| JSON representation |
|---|
| ``` { "name": string, "createTime": string, "updateTime": string, "offer": string, "commitmentSettings": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#CommitmentSettings`) }, "provisioningState": enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisioningState`), "provisionedService": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisionedService`) }, "suspensionReasons": [ enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#SuspensionReason`) ], "purchaseOrderId": string, "trialSettings": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#TrialSettings`) }, "associationInfo": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#AssociationInfo`) }, "parameters": [ { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Parameter`) } ], "billingAccount": string, "priceReferenceId": string } ``` |

| Fields ||
|---|---|
| `name` | `string` Output only. Resource name of an entitlement in the form: accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}. |
| `createTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. The time at which the entitlement is created. Uses RFC 3339, where generated output is always Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `updateTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. The time at which the entitlement is updated. Uses RFC 3339, where generated output is always Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `offer` | `string` Required. The offer resource name for which the entitlement is to be created. Takes the form: accounts/{account_id}/offers/{offer_id}. |
| `commitmentSettings` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#CommitmentSettings`)`` Commitment settings for a commitment-based Offer. Required for commitment based offers. |
| `provisioningState` | ``enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisioningState`)`` Output only. Current provisioning state of the entitlement. |
| `provisionedService` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#ProvisionedService`)`` Output only. Service provisioning details for the entitlement. |
| `suspensionReasons[]` | ``enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#SuspensionReason`)`` Output only. Enumerable of all current suspension reasons for an entitlement. |
| `purchaseOrderId` | `string` Optional. This purchase order (PO) information is for resellers to use for their company tracking usage. If a purchaseOrderId value is given, it appears in the API responses and shows up in the invoice. The property accepts up to 80 plain text characters. This is only supported for Google Workspace entitlements. |
| `trialSettings` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#TrialSettings`)`` Output only. Settings for trial offers. |
| `associationInfo` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#AssociationInfo`)`` Association information to other entitlements. |
| `parameters[]` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Parameter`)`` Extended entitlement parameters. When creating an entitlement, valid parameter names and values are defined in the `https://docs.cloud.google.com/channel/docs/reference/rest/v1/Offer#FIELDS.parameter_definitions`. For Google Workspace, the following Parameters may be accepted as input: - max_units: The maximum assignable units for a flexible offer OR - num_units: The total commitment for commitment-based offers The response may additionally include the following output-only Parameters: - assigned_units: The number of licenses assigned to users. For Google Cloud billing subaccounts, the following Parameter may be accepted as input: - displayName: The display name of the billing subaccount. |
| `billingAccount` | `string` Optional. The billing account resource name that is used to pay for this entitlement. |
| `priceReferenceId` | `string` Optional. Price reference ID for the offer. Only for offers that require additional price information. Used to guarantee that the pricing is consistent between quoting the offer and placing the order. |

## CommitmentSettings

Commitment settings for commitment-based offers.

| JSON representation |
|---|
| ``` { "startTime": string, "endTime": string, "renewalSettings": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#RenewalSettings`) } } ``` |

| Fields ||
|---|---|
| `startTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Commitment start timestamp. Uses RFC 3339, where generated output is always Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `endTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Commitment end timestamp. Uses RFC 3339, where generated output is always Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `renewalSettings` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#RenewalSettings`)`` Optional. Renewal settings applicable for a commitment-based Offer. |

## RenewalSettings

Renewal settings for renewable Offers.

| JSON representation |
|---|
| ``` { "enableRenewal": boolean, "resizeUnitCount": boolean, "paymentPlan": enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#PaymentPlan`), "paymentCycle": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Period`) } } ``` |

| Fields ||
|---|---|
| `enableRenewal` | `boolean` If false, the plan will be completed at the end date. |
| `resizeUnitCount` | `boolean` If true and enableRenewal = true, the unit (for example seats or licenses) will be set to the number of active units at renewal time. |
| `paymentPlan` | ``enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#PaymentPlan`)`` Describes how a reseller will be billed. |
| `paymentCycle` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Period`)`` Describes how frequently the reseller will be billed, such as once per month. |

## PaymentPlan

Describes how the reseller will be billed.

| Enums ||
|---|---|
| `PAYMENT_PLAN_UNSPECIFIED` | Not used. |
| `COMMITMENT` | Commitment. |
| `FLEXIBLE` | No commitment. |
| `FREE` | Free. |
| `TRIAL` | Trial. |
| `OFFLINE` | Price and ordering not available through API. |

## Period

Represents period in days/months/years.

| JSON representation |
|---|
| ``` { "duration": integer, "periodType": enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#PeriodType`) } ``` |

| Fields ||
|---|---|
| `duration` | `integer` Total duration of Period Type defined. |
| `periodType` | ``enum (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#PeriodType`)`` Period Type. |

## PeriodType

Period Type.

| Enums ||
|---|---|
| `PERIOD_TYPE_UNSPECIFIED` | Not used. |
| `DAY` | Day. |
| `MONTH` | Month. |
| `YEAR` | Year. |

## ProvisioningState

Indicates the current provisioning state of the entitlement.

| Enums ||
|---|---|
| `PROVISIONING_STATE_UNSPECIFIED` | Not used. |
| `ACTIVE` | The entitlement is currently active. |
| `SUSPENDED` | The entitlement is currently suspended. |

## ProvisionedService

Service provisioned for an entitlement.

| JSON representation |
|---|
| ``` { "provisioningId": string, "productId": string, "skuId": string } ``` |

| Fields ||
|---|---|
| `provisioningId` | `string` Output only. Provisioning ID of the entitlement. For Google Workspace, this is the underlying Subscription ID. For Google Cloud, this is the Billing Account ID of the billing subaccount. |
| `productId` | `string` Output only. The product pertaining to the provisioning resource as specified in the Offer. |
| `skuId` | `string` Output only. The SKU pertaining to the provisioning resource as specified in the Offer. |

## SuspensionReason

Suspension reason for an entitlement if `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Entitlement.FIELDS.provisioning_state` = SUSPENDED.

| Enums ||
|---|---|
| `SUSPENSION_REASON_UNSPECIFIED` | Not used. |
| `RESELLER_INITIATED` | Entitlement was manually suspended by the Reseller. |
| `TRIAL_ENDED` | Trial ended. |
| `RENEWAL_WITH_TYPE_CANCEL` | Entitlement renewal was canceled. |
| `PENDING_TOS_ACCEPTANCE` | Entitlement was automatically suspended on creation for pending ToS acceptance on customer. |
| `OTHER` | Other reasons (internal reasons, abuse, etc.). |

## TrialSettings

Settings for trial offers.

| JSON representation |
|---|
| ``` { "trial": boolean, "endTime": string } ``` |

| Fields ||
|---|---|
| `trial` | `boolean` Determines if the entitlement is in a trial or not: - `true` - The entitlement is in trial. - `false` - The entitlement is not in trial. |
| `endTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Date when the trial ends. The value is in milliseconds, using the UNIX Epoch format. See an example [Epoch converter](https://www.epochconverter.com). Uses RFC 3339, where generated output is always Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |

## AssociationInfo

Association links that an entitlement has to other entitlements.

| JSON representation |
|---|
| ``` { "baseEntitlement": string } ``` |

| Fields ||
|---|---|
| `baseEntitlement` | `string` The name of the base entitlement, for which this entitlement is an add-on. |

## Parameter

Definition for extended entitlement parameters.

| JSON representation |
|---|
| ``` { "name": string, "value": { object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Value`) }, "editable": boolean } ``` |

| Fields ||
|---|---|
| `name` | `string` Name of the parameter. |
| `value` | ``object (`https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Value`)`` Value of the parameter. |
| `editable` | `boolean` Output only. Specifies whether this parameter is allowed to be changed. For example, for a Google Workspace Business Starter entitlement in commitment plan, num_units is editable when entitlement is active. |

## Value

Data type and value of a parameter.

| JSON representation |
|---|
| ``` { // Union field `kind` can be only one of the following: "int64Value": string, "stringValue": string, "doubleValue": number, "protoValue": { "@type": string, field1: ..., ... }, "boolValue": boolean // End of list of possible types for union field `kind`. } ``` |

| Fields ||
|---|---|
| Union field `kind`. The kind of value. `kind` can be only one of the following: ||
| `int64Value` | `string (https://developers.google.com/discovery/v1/type-format format)` Represents an int64 value. |
| `stringValue` | `string` Represents a string value. |
| `doubleValue` | `number` Represents a double value. |
| `protoValue` | `object` Represents an 'Any' proto value. An object containing fields of an arbitrary type. An additional field `"@type"` contains a URI identifying the type. Example: `{ "id": 1234, "@type": "types.example.com/standard/id" }`. |
| `boolValue` | `boolean` Represents a boolean value. |

| ## Methods ||
|---|---|
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/activate` | Activates a previously suspended entitlement. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/cancel` | Cancels a previously fulfilled entitlement. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/changeOffer` | Updates the Offer for an existing customer entitlement. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/changeParameters` | Change parameters of the entitlement. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/changeRenewalSettings` | Updates the renewal settings for an existing customer entitlement. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/create` | Creates an entitlement for a customer. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/get` | Returns the requested `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Entitlement` resource. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/list` | Lists `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements#Entitlement`s belonging to a customer. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/listEntitlementChanges` | List entitlement history. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/lookupOffer` | Returns the requested `https://docs.cloud.google.com/channel/docs/reference/rest/v1/Offer` resource. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/startPaidService` | Starts paid service for a trial entitlement. |
| ### `https://docs.cloud.google.com/channel/docs/reference/rest/v1/accounts.customers.entitlements/suspend` | Suspends a previously fulfilled entitlement. |