Skip to navigation

Batch Market Data Subscription

View as Markdown

Subscribe many users to market data in one call.

Available to: Organization administrators (users in their organization)

Environments: Live

Rate Limit: No endpoint-specific limit

On Live, some organizations restrict administrators from accessing other members’ accounts unless they hold an approved trading permission for that account.

Subscribe several users in your organization to market data plans in a single request. Each entry in subscriptions names one user (userId), the plans (marketDataSubscriptionPlanIds), the month (year, month), and how to pay (accountId or creditCardId). Each entry works like addMarketDataSubscription for that user, including its payment rules.

The whole batch is checked first. If the batch is rejected, the response has a top-level errorText and errorCode, results is empty, and nothing is charged. Otherwise each entry is processed on its own: results has one entry per user, in request order, with that user’s marketDataSubscription on success (the last one created, when the entry names several plans) or its own errorText and errorCode on failure. The response also returns a batchSubmissionId.

Common Failure Scenarios

  • Whole batch rejected: you aren’t an organization administrator; the batch is larger than the configured maximum; an entry has no userId, or a user appears more than once; or a user, account, or card in the batch isn’t available to you (the message lists the IDs).
  • One entry rejected: the entry names more plans than the configured maximum, or repeats a plan; a field is out of range; or the entry fails for any of the reasons addMarketDataSubscription lists (payment, plan availability, live account, conflicts, balance, card charge).
  • Outcome unknown: processing an entry took too long. The user may have been charged, so check the user’s subscriptions before retrying that entry.
  • subscriptions is empty. This returns HTTP 400.
  • You call it on Demo. This returns HTTP 501.

This endpoint returns HTTP 200 for both successful and rejected requests, so check the top-level errorText and each entry’s errorText in results to confirm the result. Other failures, such as denied access or an invalid request, return their own HTTP status.

Error Messages

MessageResponseTrigger
"Subscriptions should be specified"400subscriptions is empty.
"Access is denied"401The caller’s user type, or the API key’s permissions, don’t include full access to the Users resource.
"This endpoint should be called on live.tradovateapi.com"501Called on the Demo environment.
"Batch market data subscriptions require organization administrator access"200 (in errorText)The caller isn’t an organization administrator. The whole batch is rejected.
"A batch may contain at most {limit} subscriptions"200 (in errorText)The batch has more entries than the configured maximum.
"Every subscription in a batch must name a user"200 (in errorText)An entry’s userId isn’t greater than 0.
"A batch may contain at most one subscription per user"200 (in errorText)The same userId appears in more than one entry.
"Some subscriptions reference resources that are not available to you: {list}"200 (in errorText)A user in the batch doesn’t exist or isn’t in the caller’s organization, or an accountId or creditCardId isn’t one the caller can read. {list} names the IDs, such as users {ids}; accounts {ids}; payment methods {ids}. The whole batch is rejected.
"A subscription may name at most {limit} market data subscription plans"200 (in the entry’s errorText)The entry names more plans than the configured maximum.
"Market data subscription plans must be unique within a subscription"200 (in the entry’s errorText)The entry repeats a plan ID.
"{field}: {message}"200 (in the entry’s errorText)An entry field is out of range, for example year: Year should be between 2015 and 2050 or month: Month should be between 1 and 12. Several are joined with ; .
"Plan discontinued"200 (in the entry’s errorText)A plan ID isn’t available to the caller, doesn’t exist, or the plan is past its end date or before its start date.
"Credit card or account is not specified"200 (in the entry’s errorText)The entry has neither accountId nor creditCardId.
"Wrong account"200 (in the entry’s errorText)The account isn’t an active Customer, House, or Employee account owned by the user, or the caller can’t pay with it on the user’s behalf.
"Wrong credit card"200 (in the entry’s errorText)The card isn’t the user’s own unarchived card, or the caller can’t pay with it on the user’s behalf.
"Live account is required"200 (in the entry’s errorText)The user isn’t professional or a migrated user, has no active live account, and hasn’t certified as non-professional (a few other exceptions also lift this requirement).
"Migrated user must sign market data agreement first"200 (in the entry’s errorText)The user is a migrated user who hasn’t signed the market data agreement.
"Plan conflicts with existing one"200 (in the entry’s errorText)The user already has an active subscription for that month (or, shortly before the monthly renewal, for the next month) whose plan covers the new plan: its exchanges include all of the new plan’s exchanges, and its data type is the same or is DOM.
"All selected CME plans must be either 'TOP OF BOOK' or 'MARKET DEPTH', but in your settings they are mixed."200 (in the entry’s errorText)The user’s existing and new CME Group plans would mix top-of-book and market-depth data.
"The choice you selected is more than your current balance. Please pay with a credit card or deposit additional funds to complete this purchase."200 (in the entry’s errorText)The account’s total cash is less than the charge, or paying would leave its net liquidating value (plus any risk credit) below its margin and collateral requirements plus the commissions and fees on its open positions.
(payment processor message)200 (in the entry’s errorText)The card charge failed at the payment processor. The text comes from the processor.
"The subscription was submitted but its outcome is unknown; check the subscription before retrying"200 (in the entry’s errorText)Processing the entry timed out. The user may have been charged.
"Internal Error. Error ID: {id}"200 (in errorText)Processing the batch, or one entry, failed unexpectedly. The error ID is generated per request.

Related Endpoints

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
subscriptionslist of objectsRequired

Response

BatchMarketDataSubscriptionResponse
resultslist of objects
errorTextstringOptional<=8192 characters

Non-empty if the request failed

errorCodeenumOptional
BatchTooLarge, ConflictWithExisting, DuplicateItem, IncompatibleCMEMarketDataSubscriptionPlans, IncorrectPaymentMethod, InsufficientFunds, InternalError, InvalidRequest, NotAuthorized, OutcomeUnknown, PaymentProviderError, PlanDiscontinued, Success
batchSubmissionIdstringOptional<=64 characters