REST Resource: accounts.customers.entitlements

Resource: Entitlement

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

JSON representation 
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "channelPartnerId": string,
  "offer": string,
  "numUnits": integer,
  "maxUnits": integer,
  "assignedUnits": integer,
  "commitmentSettings": {
    object (CommitmentSettings)
  },
  "provisioningState": enum (ProvisioningState),
  "provisionedService": {
    object (ProvisionedService)
  },
  "suspensionReasons": [
    enum (SuspensionReason)
  ],
  "purchaseOrderId": string,
  "trialSettings": {
    object (TrialSettings)
  },
  "associationInfo": {
    object (AssociationInfo)
  },
  "parameters": [
    {
      object (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 (Timestamp format)

Output only. The time at which the entitlement is created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. The time at which the entitlement is updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
channelPartnerId
(deprecated)

string

Cloud Identity ID of a channel partner who will be the direct reseller for the customer's order. This field is generally used in 2-tier ordering, where the order is placed by a top-level distributor on behalf of their channel partner or reseller. Required for distributors. Deprecated: channelPartnerId has been moved to the Customer.
offer

string

Required. The offer resource name for which the entitlement is to be created. Takes the form: accounts/{account_id}/offers/{offer_id}.
numUnits
(deprecated)

integer

Number of units for a commitment-based Offer. For example, for seat-based Offers, this would be the number of seats; for license-based Offers, this would be the number of licenses. Required for creating commitment-based Offers. Deprecated: Use parameters instead.
maxUnits
(deprecated)

integer

Maximum number of units for a non commitment-based Offer, such as Flexible, Trial or Free entitlements. For commitment-based entitlements, this is a read-only field, which only the internal support team can update. Deprecated: Use parameters instead.
assignedUnits
(deprecated)

integer

The current number of users that are assigned a license for the product defined in provisionedService.skuId. Read-only. Deprecated: Use parameters instead.
commitmentSettings

object (CommitmentSettings)

Commitment settings for a commitment-based Offer. Required for commitment based offers.
provisioningState

enum (ProvisioningState)

Output only. Current provisioning state of the entitlement.
provisionedService

object (ProvisionedService)

Output only. Service provisioning details for the entitlement.
suspensionReasons[]

enum (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 (TrialSettings)

Output only. Settings for trial offers.
associationInfo

object (AssociationInfo)

Association information to other entitlements.
parameters[]

object (Parameter)

Extended entitlement parameters. When creating an entitlement, valid parameter names and values are defined in the Offer.parameter_definitions.

For Google Workspace, the following Parameters may be accepted as input:

  • maxUnits: The maximum assignable units for a flexible offer

OR

  • numUnits: The total commitment for commitment-based offers

The response may additionally include the following output-only Parameters:

  • assignedUnits: 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. Optional field only for offers that require additional price information. Used to guarantee that the pricing is consistent between quoting the offer and placing the order.

Yet to be implemented: this field is currently not evaluated in the API if populated in a request.

CommitmentSettings

Commitment settings for commitment-based offers.

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "renewalSettings": {
    object (RenewalSettings)
  }
}
Fields
startTime

string (Timestamp format)

Output only. Commitment start timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endTime

string (Timestamp format)

Output only. Commitment end timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
renewalSettings

object (RenewalSettings)

Optional. Renewal settings applicable for a commitment-based Offer.

RenewalSettings

Renewal settings for renewable Offers.

JSON representation 
{
  "enableRenewal": boolean,
  "resizeUnitCount": boolean,
  "disableCommitment": boolean,
  "paymentOption": enum (PaymentOption),
  "paymentPlan": enum (PaymentPlan),
  "paymentCycle": {
    object (Period)
  },
  "scheduledRenewalOffer": string
}
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.
disableCommitment
(deprecated)

boolean

If true, disables commitment-based offer on renewal and switches to flexible or pay as you go. Deprecated: Use paymentPlan instead.
paymentOption
(deprecated)

enum (PaymentOption)

Set if enableRenewal=true. Deprecated: Use paymentCycle instead.
paymentPlan

enum (PaymentPlan)

Describes how a reseller will be billed.
paymentCycle

object (Period)

Describes how frequently the reseller will be billed, such as once per month.
scheduledRenewalOffer

string

Output only. The offer resource name that the entitlement will renew on at the end date. Takes the form: accounts/{account_id}/offers/{offer_id}.

PaymentOption

Determines scheduled payment frequency.

Enums
PAYMENT_OPTION_UNSPECIFIED Not used.
ANNUAL Paid in yearly installments.
MONTHLY Paid in monthly installments.

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 (PeriodType)
}
Fields
duration

integer

Total duration of Period Type defined.
periodType

enum (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.
CANCELED

The entitlement was canceled. After an entitlement is CANCELED, its status will not change. Deprecated: Canceled entitlements will no longer be visible.
COMPLETE

The entitlement reached end of term and was not renewed. After an entitlement is COMPLETE, its status will not change. Deprecated: This is represented as ProvisioningState=SUSPENDED and suspensionReason in (TRIAL_ENDED, RENEWAL_WITH_TYPE_CANCEL)
PENDING

The entitlement is pending. Deprecated: This is represented as ProvisioningState=SUSPENDED and suspensionReason=PENDING_TOS_ACCEPTANCE
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 provisioningState = 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 (Timestamp format)

Date when the trial ends. The value is in milliseconds using the UNIX Epoch format. See an example Epoch converter.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

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 (Value)
  },
  "editable": boolean
}
Fields
name

string

Name of the parameter.
value

object (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, numUnits 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 (int64 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

activate

 Activates a previously suspended entitlement.

assignChannelPartner

 Assigns a channel partner to an Entitlement resource.

cancel

 Cancels a previously fulfilled entitlement.

changeOffer

 Updates the Offer for an existing customer entitlement.

changeParameters

 Change parameters of the entitlement.

changePlan
(deprecated)

 Updates the plan for an existing customer entitlement.

changeQuantity
(deprecated)

 Updates the quantity for existing seat-based entitlements.

changeRenewalSettings

 Updates the renewal settings for an existing customer entitlement.

changeSku
(deprecated)

 Updates the SKU for an existing customer entitlement.

create

 Creates an entitlement for a customer.

get

 Returns the requested Entitlement resource.

list

 Lists Entitlements belonging to a customer.

listEntitlementChanges

 List entitlement history.

lookupOffer

 Returns the requested Offer resource.

startPaidService

 Starts paid service for a trial entitlement.

suspend

 Suspends a previously fulfilled entitlement.