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)
    }
  ]
}
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.

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 parameters' names and values are defined in the offer's parameter definitions.

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)
  }
}
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.

PaymentOption

Determines scheduled payment frequency.

Enums
PAYMENT_OPTION_UNSPECIFIED Default value. This state doesn't show unless an error occurs.
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 Default value. This state doesn't show unless an error occurs.
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 would be the underlying Subscription ID.

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 Default value. This state doesn't show unless an error occurs.
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.

lookupOffer

Returns the requested Offer resource.

startPaidService

Starts paid service for a trial entitlement.

suspend

Suspends a previously fulfilled entitlement.