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,
  "offer": string,
  "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".
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 (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:

  • 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. 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.

Not yet implemented: if this field is populated in a request, it isn't evaluated in the API.

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,
  "paymentPlan": enum (PaymentPlan),
  "paymentCycle": {
    object (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 (PaymentPlan)

Describes how a reseller will be billed.
paymentCycle

object (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 (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.
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, 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 (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.

cancel

 Cancels a previously fulfilled entitlement.

changeOffer

 Updates the Offer for an existing customer entitlement.

changeParameters

 Change parameters of the entitlement.

changeRenewalSettings

 Updates the renewal settings 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.