Skip to navigation

Plugin Is Entitled

View as Markdown

Check whether a user is entitled to a plugin.

Available to: Traders (own records); organization administrators (any user in their organization)

Environments: Live

Rate Limit: No endpoint-specific limit

Check whether a user holds an unexpired plugin for entitlementName that fits their current subscription plan. A plugin is a user’s subscription to an entitlement. To check another user, an organization administrator also passes that user’s userId; omit userId to check yourself. When the user is entitled, the response returns the plugin in entitlementSubscription.

Set withTolerance to true to treat a plugin (or the user’s subscription plan) that expires today as unexpired until 19:00 Central Time. If you omit it, a plugin or plan that expires today counts as expired.

Common Failure Scenarios

  • The user has no unexpired plugin for entitlementName that fits their current subscription plan. This returns HTTP 200 with "No plugins found" in errorText and no entitlementSubscription. A plugin with planCategories fits only users whose plan category is one of them; a plugin without them fits any user with a current plan.
  • The request includes userId and the caller isn’t an organization administrator. This returns HTTP 401 even when userId is the caller’s own ID, so omit userId to check yourself.
  • No user matches userId, or you can’t access that user. Both return HTTP 404 with an empty body. Most organization administrators can’t access users outside their organization.
  • The caller’s user type, or the API key’s permissions, don’t include full access to the Users resource. This returns HTTP 401 with "Access is denied".
  • entitlementName is empty or longer than 64 characters, or userId isn’t greater than 0. These return HTTP 400.
  • The request is sent to Demo. This endpoint runs on Live only, so Demo returns HTTP 501.

This endpoint returns HTTP 200 for both successful and rejected requests, so check the errorText field to confirm the result. Other failures, such as denied access or an invalid request, return their own HTTP status.

Error Messages

MessageResponseTrigger
"Entitlement Name should be specified"400entitlementName is empty or null.
"Entitlement Name should be no longer than 64"400entitlementName is longer than 64 characters.
"User Id should be greater than 0"400userId is included and isn’t greater than 0.
"mustBeOrganizationAdmin"401The request includes userId and the caller isn’t an organization administrator.
"Access is denied"401The caller’s user type, or the API key’s permissions, don’t include full access to the Users resource.
(no message text)404No user matches userId, or you can’t access that user (most organization administrators can’t access users outside their organization).
"This endpoint should be called on live.tradovateapi.com"501Called on the Demo environment.
"No plugins found"200 (in errorText)The user has no unexpired plugin for entitlementName that fits their current subscription plan (a plugin with planCategories needs the user’s plan category to be one of them; one without needs the user to have a current plan).
"Internal Error. Error ID: {id}"200 (in errorText)The entitlement check failed unexpectedly. The error ID is generated per request.
"Request timeout. Error ID: {id}"200 (in errorText)The entitlement check didn’t respond in time. The error ID is generated per request.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
entitlementNamestringRequired<=64 characters
withTolerancebooleanOptional
userIdlongOptional

Response

EntitlementSubscriptionResponse
errorTextstringOptional<=8192 characters

Non-empty if the request failed

errorCodeenumOptional
ConflictWithExisting, DowngradeNotAllowed, IncompatibleCMEMarketDataSubscriptionPlans, IncorrectPaymentMethod, InsufficientFunds, PaymentProviderError, PlanDiscontinued, SingleTrialOnly, Success, UnknownError
entitlementSubscriptionobjectOptional