Scopes

Read Group/Clan Forums, Wall, and Members for groups and clans that the
user has joined.

WriteGroups

Write Group/Clan Forums, Wall, and Members for groups and clans that the
user has joined.

AdminGroups

Administer Group/Clan Forums, Wall, and Members for groups and clans that the
user is a founder or an administrator.

BnetWrite

Create new groups, clans, and forum posts.

MoveEquipDestinyItems

Move or equip Destiny items

ReadDestinyInventoryAndVault

Read Destiny 1 Inventory and Vault contents.
For Destiny 2, this scope is needed to read anything regarded as private. This is the only scope a
Destiny 2 app needs for read operations against Destiny 2 data such as inventory, vault, currency,
vendors, milestones, progression, etc.

ReadUserData

Read user data such as who they are web notifications,
clan/group memberships, recent activity, muted users.

Edit an existing group. You must have suitable permissions in the group to perform this operation. This latest revision will only edit the fields you pass in - pass null for properties you want to leave unaltered.

Returns the static definition of an entity of the given Type and hash identifier. Examine the API Documentation for the Type Names of entities that have their own definitions. Note that the return type will always *inherit from* DestinyDefinition, but the specific type returned will be the requested entity type if it can be found. Please don't use this as a chatty alternative to the Manifest database if you require large sets of data, but for simple and one-off accesses this should be handy.

Path Parameters

entityType

The type of entity for whom you would like results. These correspond to the entity's definition contract name. For instance, if you are looking for items, this property should be 'DestinyInventoryItemDefinition'. PREVIEW: This endpoint is still in beta, and may experience rough edges. The schema is tentatively in final form, but there may be bugs that prevent desirable operation.

Path Parameters

Querystring Parameters

components

A comma separated list of components to return (as strings or numeric values). See the DestinyComponentType enum for valid components to request. You must request at least one component to receive results.

Path Parameters

Querystring Parameters

components

A comma separated list of components to return (as strings or numeric values). See the DestinyComponentType enum for valid components to request. You must request at least one component to receive results.

Returns information on the weekly clan rewards and if the clan has earned them or not. Note that this will always report rewards as not redeemed.

Path Parameters

groupId

A valid group id of clan.

Type: int64

Response

Represents a runtime instance of a user's milestone status. Live Milestone data should be combined with DestinyMilestoneDefinition data to show the user a picture of what is available for them to do in the game, and their status in regards to said "things to do." Consider it a big, wonky to-do list, or Advisors 3.0 for those who remember the Destiny 1 API.

Retrieve the details of an instanced Destiny Item. An instanced Destiny item is one with an ItemInstanceId. Non-instanced items, such as materials, have no useful instance-specific details and thus are not queryable here.

Querystring Parameters

components

A comma separated list of components to return (as strings or numeric values). See the DestinyComponentType enum for valid components to request. You must request at least one component to receive results.

Response

The response object for retrieving an individual instanced item. None of these components are relevant for an item that doesn't have an "itemInstanceId": for those, get your information from the DestinyInventoryDefinition.

Get currently available vendors from the list of vendors that can possibly have rotating inventory. Note that this does not include things like preview vendors and vendors-as-kiosks, neither of whom have rotating/dynamic inventories. Use their definitions as-is for those. PREVIEW: This service is not yet active, but we are returning the planned schema of the endpoint for review, comment, and preparation for its eventual implementation.

Path Parameters

characterId

The Destiny Character ID of the character for whom we're getting vendor info.

Querystring Parameters

components

A comma separated list of components to return (as strings or numeric values). See the DestinyComponentType enum for valid components to request. You must request at least one component to receive results.

Get the details of a specific Vendor. PREVIEW: This service is not yet active, but we are returning the planned schema of the endpoint for review, comment, and preparation for its eventual implementation.

Path Parameters

characterId

The Destiny Character ID of the character for whom we're getting vendor info.

Querystring Parameters

components

A comma separated list of components to return (as strings or numeric values). See the DestinyComponentType enum for valid components to request. You must request at least one component to receive results.

Extract an item from the Postmaster, with whatever implications that may entail. You must have a valid Destiny account. You must also pass BOTH a reference AND an instance ID if it's an instanced item.

Insert a plug into a socketed item. I know how it sounds, but I assure you it's much more G-rated than you might be guessing. We haven't decided yet whether this will be able to insert plugs that have side effects, but if we do it will require special scope permission for an application attempting to do so. You must have a valid Destiny Account, and either be in a social space, in orbit, or offline. Request must include proof of permission for 'InsertPlugs' from the account owner.

Report a player that you met in an activity that was engaging in ToS-violating activities. Both you and the offending player must have played in the activityId passed in. Please use this judiciously and only when you have strong suspicions of violation, pretty please.

Required Scope(s)

oauth2: BnetWrite

Path Parameters

activityId

The ID of the activity where you ran into the brigand that you're reporting.

Gets leaderboards with the signed in user's friends and the supplied destinyMembershipId as the focus. PREVIEW: This endpoint is still in beta, and may experience rough edges. The schema is in final form, but there may be bugs that prevent desirable operation.

Path Parameters

groupId

Group ID of the clan whose leaderboards you wish to fetch.

Type: int64

Querystring Parameters

maxtop

Maximum number of top players to return. Use a large number to get entire leaderboard.

Type: int32

modes

List of game modes for which to get leaderboards. See the documentation for DestinyActivityModeType for valid values, and pass in string representation, comma delimited.

Type: string

statid

ID of stat to return rather than returning all Leaderboard stats.

Type: string

Response

Look at the Response property for more information about the nature of this response

Gets aggregated stats for a clan using the same categories as the clan leaderboards. PREVIEW: This endpoint is still in beta, and may experience rough edges. The schema is in final form, but there may be bugs that prevent desirable operation.

Path Parameters

groupId

Group ID of the clan whose leaderboards you wish to fetch.

Type: int64

Querystring Parameters

modes

List of game modes for which to get leaderboards. See the documentation for DestinyActivityModeType for valid values, and pass in string representation, comma delimited.

Type: string

Response

Look at the Response property for more information about the nature of this response

Gets leaderboards with the signed in user's friends and the supplied destinyMembershipId as the focus. PREVIEW: This endpoint has not yet been implemented. It is being returned for a preview of future functionality, and for public comment/suggestion/preparation.

Gets leaderboards with the signed in user's friends and the supplied destinyMembershipId as the focus. PREVIEW: This endpoint is still in beta, and may experience rough edges. The schema is in final form, but there may be bugs that prevent desirable operation.

Path Parameters

characterId

The specific character to build the leaderboard around for the provided Destiny Membership.

Path Parameters

searchTerm

The string to use when searching for Destiny entities.

Type: string

type

The type of entity for whom you would like results. These correspond to the entity's definition contract name. For instance, if you are looking for items, this property should be 'DestinyInventoryItemDefinition'.

Type: string

Querystring Parameters

page

Page number to return, starting with 0.

Type: int32

Response

The results of a search for Destiny content. This will be improved on over time, I've been doing some experimenting to see what might be useful.

Gets custom localized content for the milestone of the given hash, if it exists.

Path Parameters

milestoneHash

The identifier for the milestone to be returned.

Type: uint32

Response

Represents localized, extended content related to Milestones. This is intentionally returned by a separate endpoint and not with Character-level Milestone data because we do not put localized data into standard Destiny responses, both for brevity of response and for caching purposes. If you really need this data, hit the Milestone Content endpoint.

Returns the detailed results for a specific trending entry. Note that trending entries are uniquely identified by a combination of *both* the TrendingEntryType *and* the identifier: the identifier alone is not guaranteed to be globally unique.

Entities

Valid Enum Values

Read Group/Clan Forums, Wall, and Members for groups and clans that the user has joined.

WriteGroups: 4

Write Group/Clan Forums, Wall, and Members for groups and clans that the user has joined.

AdminGroups: 8

Administer Group/Clan Forums, Wall, and Members for groups and clans that the user is a founder or an administrator.

BnetWrite: 16

Create new groups, clans, and forum posts.

MoveEquipDestinyItems: 32

Move or equip Destiny items

ReadDestinyInventoryAndVault: 64

Read Destiny 1 Inventory and Vault contents. For Destiny 2, this scope is needed to read anything regarded as private. This is the only scope a Destiny 2 app needs for read operations against Destiny 2 data such as inventory, vault, currency, vendors, milestones, progression, etc.

ReadUserData: 128

Read user data such as who they are web notifications, clan/group memberships, recent activity, muted users.

This contract supplies basic information commonly used to display a minimal amount of information about a user. Take care to not add more properties here unless the property applies in all (or at least the majority) of the situations where UserInfoCard is used. Avoid adding game specific or platform specific details here. In cases where UserInfoCard is a subset of the data needed in a contract, use UserInfoCard as a property of other contracts.

Object Properties

If useTotalResults is true, then totalResults represents an accurate count.
If False, it does not, and may be estimated/only the size of the current page.
Either way, you should probably always only trust hasMore.
This is a long-held historical throwback to when we used to do paging with known total results. Those queries toasted our database, and we were left to hastily alter our endpoints and create backward- compatible shims, of which useTotalResults is one.

Object Properties

If useTotalResults is true, then totalResults represents an accurate count.
If False, it does not, and may be estimated/only the size of the current page.
Either way, you should probably always only trust hasMore.
This is a long-held historical throwback to when we used to do paging with known total results. Those queries toasted our database, and we were left to hastily alter our endpoints and create backward- compatible shims, of which useTotalResults is one.

If useTotalResults is true, then totalResults represents an accurate count.
If False, it does not, and may be estimated/only the size of the current page.
Either way, you should probably always only trust hasMore.
This is a long-held historical throwback to when we used to do paging with known total results. Those queries toasted our database, and we were left to hastily alter our endpoints and create backward- compatible shims, of which useTotalResults is one.

This property will be populated if the authenticated user is a member of the group. Note that because of account linking, a user can sometimes be part of a clan more than once. As such, this returns the highest member type available.

This property will be populated if the authenticated user is an applicant or has an outstanding invitation to join. Note that because of account linking, a user can sometimes be part of a clan more than once.

Minimum Member Level allowed to invite new members to group
Always Allowed: Founder, Acting Founder
True means admins have this power, false means they don't
Default is false for clans, true for groups.

Valid Enum Values

The member levels used by all V2 Groups API. Individual group types use their own mappings in their native storage (general uses BnetDbGroupMemberType and D2 clans use ClanMemberLevel), but they are all translated to this in the runtime api. These runtime values should NEVER be stored anywhere, so the values can be changed as necessary.

Object Properties

Information about a current character's status with a Progression. A progression is a value that can increase with activity and has levels. Think Character Level and Reputation Levels. Combine this "live" data with the related DestinyProgressionDefinition for a full picture of the Progression.

Type: object

Object Properties

progressionHash

Mapped to Definition

The hash identifier of the Progression in question. Use it to look up the DestinyProgressionDefinition in static data.

The amount of progress earned toward this progression in the current week.

Type: int32

weeklyLimit

If this progression has a weekly limit, this is that limit.

Type: int32

currentProgress

This is the total amount of progress obtained overall for this progression (for instance, the total amount of Character Level experience earned)

Type: int32

level

This is the level of the progression (for instance, the Character Level).

Type: int32

levelCap

This is the maximum possible level you can achieve for this progression (for example, the maximum character level obtainable)

Type: int32

stepIndex

Progressions define their levels in "steps". Since the last step may be repeatable, the user may be at a higher level than the actual Step achieved in the progression. Not necessarily useful, but potentially interesting for those cruising the API. Relate this to the "steps" property of the DestinyProgression to see which step the user is on, if you care about that. (Note that this is Content Version dependent since it refers to indexes.)

Type: int32

progressToNextLevel

The amount of progression (i.e. "Experience") needed to reach the next level of this Progression. Jeez, progression is such an overloaded word.

Type: int32

nextLevelAt

The total amount of progression (i.e. "Experience") needed in order to reach the next level.

Object Properties

hash

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

A "Progression" in Destiny is best explained by an example.
A Character's "Level" is a progression: it has Experience that can be earned, levels that can be gained, and is evaluated and displayed at various points in the game. A Character's "Faction Reputation" is also a progression for much the same reason.
Progression is used by a variety of systems, and the definition of a Progression will generally only be useful if combining with live data (such as a character's DestinyCharacterProgressionComponent.progressions property, which holds that character's live Progression states).
Fundamentally, a Progression measures your "Level" by evaluating the thresholds in its Steps (one step per level, except for the last step which can be repeated indefinitely for "Levels" that have no ceiling) against the total earned "progression points"/experience. (for simplicity purposes, we will henceforth refer to earned progression points as experience, though it need not be a mechanic that in any way resembles Experience in a traditional sense).
Earned experience is calculated in a variety of ways, determined by the Progression's scope. These go from looking up a stored value to performing exceedingly obtuse calculations. This is why we provide live data in DestinyCharacterProgressionComponent.progressions, so you don't have to worry about those.

Mapped to Mobile Manifest Table: Progressions

Type: object

Object Properties

The "Scope" of the progression indicates the source of the progression's live data.
See the DestinyProgressionScope enum for more info: but essentially, a Progression can either be backed by a stored value, or it can be a calculated derivative of other values.

If there's a description of how to earn this progression in the local config, this will be that localized description.

Type: string

steps

Progressions are divided into Steps, which roughly equate to "Levels" in the traditional sense of a Progression. Notably, the last step can be repeated indefinitely if repeatLastStep is true, meaning that the calculation for your level is not as simple as comparing your current progress to the max progress of the steps.
These and more calculations are done for you if you grab live character progression data, such as in the DestinyCharacterProgressionComponent.

If true, the Progression is something worth showing to users.
If false, BNet isn't going to show it. But that doesn't mean you can't. We're all friends here.

Type: boolean

factionHash

NullableMapped to Definition

If the value exists, this is the hash identifier for the Faction that owns this Progression.
This is purely for convenience, if you're looking at a progression and want to know if and who it's related to in terms of Faction Reputation.

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Many Destiny*Definition contracts - the "first order" entities of Destiny that have their own tables in the Manifest Database - also have displayable information. This is the base class for that display information.

Type: object

Object Properties

description

Type: string

name

Type: string

icon

Note that "icon" is sometimes misleading, and should be interpreted in the context of the entity. For instance, in Destiny 1 the DestinyRecordBookDefinition's icon was a big picture of a book.
But usually, it will be a small square image that you can use as... well, an icon.

Object Properties

When progressions show your "experience" gained, that bar has units (i.e. "Experience", "Bad Dudes Snuffed Out", whatever). This is the localized string for that unit of measurement.

Type: string

description

Type: string

name

Type: string

icon

Note that "icon" is sometimes misleading, and should be interpreted in the context of the entity. For instance, in Destiny 1 the DestinyRecordBookDefinition's icon was a big picture of a book.
But usually, it will be a small square image that you can use as... well, an icon.

There are many Progressions in Destiny (think Character Level, or Reputation). These are the various "Scopes" of Progressions, which affect many things: * Where/if they are stored * How they are calculated * Where they can be used in other game logic

Valid Enum Values

This defines a single Step in a progression (which roughly equates to a level. See DestinyProgressionDefinition for caveats).

Type: object

Object Properties

stepName

Very rarely, Progressions will have localized text describing the Level of the progression. This will be that localized text, if it exists. Otherwise, the standard appears to be to simply show the level numerically.

Type: string

displayEffectType

This appears to be, when you "level up", whether a visual effect will display and on what entity. See DestinyProgressionStepDisplayEffect for slightly more info.

The total amount of progression points/"experience" you will need to initially reach this step. If this is the last step and the progression is repeating indefinitely (DestinyProgressionDefinition.repeatLastStep), this will also be the progress needed to level it up further by repeating this step again.

Valid Enum Values

Used in a number of Destiny contracts to return data about an item stack and its quantity. Can optionally return an itemInstanceId if the item is instanced - in which case, the quantity returned will be 1. If it's not... uh, let me know okay? Thanks.

Type: object

Object Properties

itemHash

Mapped to Definition

The hash identifier for the item in question. Use it to look up the item's DestinyInventoryItemDefinition.

So much of what you see in Destiny is actually an Item used in a new and creative way. This is the definition for Items in Destiny, which started off as just entities that could exist in your Inventory but ended up being the backing data for so much more: quests, reward previews, slots, and subclasses.
In practice, you will want to associate this data with "live" item data from a Bungie.Net Platform call: these definitions describe the item in generic, non-instanced terms: but an actual instance of an item can vary widely from these generic definitions.

Object Properties

A secondary icon associated with the item. Currently this is used in very context specific applications, such as Emblem Nameplates.

Type: string

secondaryOverlay

Pulled from the secondary icon, this is the "secondary background" of the secondary icon. Confusing? Sure, that's why I call it "overlay" here: because as far as it's been used thus far, it has been for an optional overlay image. We'll see if that holds up, but at least for now it explains what this image is a bit better.

Type: string

secondarySpecial

Pulled from the Secondary Icon, this is the "special" background for the item. For Emblems, this is the background image used on the Details view: but it need not be limited to that for other types of items.

Type: string

backgroundColor

Sometimes, an item will have a background color. Most notably this occurs with Emblems, who use the Background Color for small character nameplates such as the "friends" view you see in-game. There are almost certainly other items that have background color as well, though I have not bothered to investigate what items have it nor what purposes they serve: use it as you will.

If we were able to acquire an in-game screenshot for the item, the path to that screenshot will be returned here. Note that not all items have screenshots: particularly not any non-equippable items.

Type: string

itemTypeDisplayName

The localized title/name of the item's type. This can be whatever the designers want, and has no guarantee of consistency between items.

Type: string

uiItemDisplayStyle

A string identifier that the game's UI uses to determine how the item should be rendered in inventory screens and the like. This could really be anything - at the moment, we don't have the time to really breakdown and maintain all the possible strings this could be, partly because new ones could be added ad hoc. But if you want to use it to dictate your own UI, or look for items with a certain display style, go for it!

Type: string

itemTypeAndTierDisplayName

It became a common enough pattern in our UI to show Item Type and Tier combined into a single localized string that I'm just going to go ahead and start pre-creating these for items.

Type: string

displaySource

In theory, it is a localized string telling you about how you can find the item. I really wish this was more consistent. Many times, it has nothing. Sometimes, it's instead a more narrative-forward description of the item. Which is cool, and I wish all properties had that data, but it should really be its own property.

Type: string

tooltipStyle

An identifier that the game UI uses to determine what type of tooltip to show for the item. These have no corresponding definitions that BNet can link to: so it'll be up to you to interpret and display your UI differently according to these styles (or ignore it).

Type: string

action

If the item can be "used", this block will be non-null, and will have data related to the action performed when using the item. (Guess what? 99% of the time, this action is "dismantle". Shocker)

If this item is a quest, this block will be non-null. In practice, I wish I had called this the Quest block, but at the time it wasn't clear to me whether it would end up being used for purposes other than quests. It will contain data about the steps in the quest, and mechanics we can use for displaying and tracking the quest.

If the item is an emblem that has a special Objective attached to it - for instance, if the emblem tracks PVP Kills, or what-have-you. This is a bit different from, for example, the Vanguard Kill Tracker mod, which pipes data into the "art channel". When I get some time, I would like to standardize these so you can get at the values they expose without having to care about what they're being used for and how they are wired up, but for now here's the raw data.

Type: uint32

equippingBlock

If this item can be equipped, this block will be non-null and will be populated with the conditions under which it can be equipped.

If this item can be Used or Acquired to gain other items (for instance, how Eververse Boxes can be consumed to get items from the box), this block will be non-null and will give summary information for the items that can be acquired.

If this item can have a level or stats, this block will be non-null and will be populated with default quality (item level, "quality", and infusion) data. See the block for more details, there's often less upfront information in D2 so you'll want to be aware of how you use quality and item level on the definition level now.

If this item has a known source, this block will be non-null and populated with source information. Unfortunately, at this time we are not generating sources: that is some aggressively manual work which we didn't have time for, and I'm hoping to get back to at some point in the future.

If this item has Objectives (extra tasks that can be accomplished related to the item... most frequently when the item is a Quest Step and the Objectives need to be completed to move on to the next Quest Step), this block will be non-null and the objectives defined herein.

If the item has a Talent Grid, this will be non-null and the properties of the grid defined herein. Note that, while many items still have talent grids, the only ones with meaningful Nodes still on them will be Subclass/"Build" items.

If the item has stats, this block will be defined. It has the "raw" investment stats for the item. These investment stats don't take into account the ways that the items can spawn, nor do they take into account any Stat Group transformations. I have retained them for debugging purposes, but I do not know how useful people will find them.

There are times when the game will show you a "summary/vague" version of an item - such as a description of its type represented as a DestinyInventoryItemDefinition - rather than display the item itself.
This happens sometimes when summarizing possible rewards in a tooltip. This is the item displayed instead, if it exists.

The boolean will indicate to us (and you!) whether something *could* happen when you transfer this item from the Postmaster that might be considered a "destructive" action.
It is not feasible currently to tell you (or ourelves!) in a consistent way whether this *will* actually cause a destructive action, so we are playing it safe: if it has the potential to do so, we will not allow it to be transferred from the Postmaster by default. You will need to check for this flag before transferring an item from the Postmaster, or else you'll end up receiving an error.

Type: boolean

nonTransferrable

The intrinsic transferability of an item.
I hate that this boolean is negative - but there's a reason.
Just because an item is intrinsically transferrable doesn't mean that it can be transferred, and we don't want to imply that this is the only source of that transferability.

Type: boolean

itemCategoryHashes

Mapped to Definition

BNet attempts to make a more formal definition of item "Categories", as defined by DestinyItemCategoryDefinition. This is a list of all Categories that we were able to algorithmically determine that this item is a member of. (for instance, that it's a "Weapon", that it's an "Auto Rifle", etc...)
The algorithm for these is, unfortunately, volatile. If you believe you see a miscategorized item, please let us know on the Bungie API forums.

In Destiny 1, we identified some items as having particular categories that we'd like to know about for various internal logic purposes. These are defined in SpecialItemType, and while these days the itemCategoryHashes are the preferred way of identifying types, we have retained this enum for its convenience.

A value indicating the "base" the of the item. This enum is a useful but dramatic oversimplification of what it means for an item to have a "Type". Still, it's handy in many situations.
itemCategoryHashes are the preferred way of identifying types, we have retained this enum for its convenience.

A value indicating the "sub-type" of the item. For instance, where an item might have an itemType value "Weapon", this will be something more specific like "Auto Rifle".
itemCategoryHashes are the preferred way of identifying types, we have retained this enum for its convenience.

We run a similarly weak-sauce algorithm to try and determine whether an item is restricted to a specific class. If we find it to be restricted in such a way, we set this classType property to match the class' enumeration value so that users can easily identify class restricted items.
If you see a mis-classed item, please inform the developers in the Bungie API forum.

If true, then you will be allowed to equip the item if you pass its other requirements.
This being false means that you cannot equip the item under any circumstances.

Type: boolean

damageTypeHashes

Mapped to Definition

Theoretically, an item can have many possible damage types. In *practice*, this is not true, but just in case weapons start being made that have multiple (for instance, an item where a socket has reusable plugs for every possible damage type that you can choose from freely), this field will return all of the possible damage types that are available to the weapon by default.

This is the list of all damage types that we know ahead of time the item can take on. Unfortunately, this does not preclude the possibility of something funky happening to give the item a damage type that cannot be predicted beforehand: for example, if some designer decides to create arbitrary non-reusable plugs that cause damage type to change.
This damage type prediction will only use the following to determine potential damage types:
- Intrinsic perks
- Talent Node perks
- Known, reusable plugs for sockets

Similar to defaultDamageType, but represented as the hash identifier for a DestinyDamageTypeDefinition.
I will likely regret leaving in the enumeration versions of these properties, but for now they're very convenient.

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Theoretically, an item could have a localized string for a hint about the location in which the action should be performed. In practice, no items yet have this property.

Type: string

requiredCooldownHash

The identifier hash for the Cooldown associated with this action. We have not pulled this data yet for you to have more data to use for cooldowns.

Type: uint32

deleteOnAction

If true, the item is deleted when the action completes.

Type: boolean

consumeEntireStack

If true, the entire stack is deleted when the action completes.

Type: boolean

useOnAcquire

If true, this action will be performed as soon as you earn this item. Some rewards work this way, providing you a single item to pick up from a reward-granting vendor in-game and then immediately consuming itself to provide you multiple items.

Inventory Items can reward progression when actions are performed on them. A common example of this in Destiny 1 was Bounties, which would reward Experience on your Character and the like when you completed the bounty.
Note that this maps to a DestinyProgressionMappingDefinition, and *not* a DestinyProgressionDefinition directly. This is apparently so that multiple progressions can be granted progression points/experience at the same time.

Type: object

Object Properties

progressionMappingHash

Mapped to Definition

The hash identifier of the DestinyProgressionMappingDefinition that contains the progressions for which experience should be applied.

Object Properties

The localized unit of measurement for progression across the progressions defined in this mapping. Unfortunately, this is very infrequently defined. Defer to the individual progressions' display units.

Type: string

hash

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

If the item can exist in an inventory - the overwhelming majority of them can and do - then this is the basic properties regarding the item's relationship with the inventory.

Type: object

Object Properties

stackUniqueLabel

If this string is populated, you can't have more than one stack with this label in a given inventory. Note that this is different from the equipping block's unique label, which is used for equipping uniqueness.

Type: string

maxStackSize

The maximum quantity of this item that can exist in a stack.

Type: int32

bucketTypeHash

Mapped to Definition

The hash identifier for the DestinyInventoryBucketDefinition to which this item belongs. I should have named this "bucketHash", but too many things refer to it now. Sigh.

If the item is picked up by the lost loot queue, this is the hash identifier for the DestinyInventoryBucketDefinition into which it will be placed. Again, I should have named this recoveryBucketHash instead.

If TRUE, this item is instanced. Otherwise, it is a generic item that merely has a quantity in a stack (like Glimmer).

Type: boolean

tierTypeName

The localized name of the tier type, which is a useful shortcut so you don't have to look up the definition every time. However, it's mostly a holdover from days before we had a DestinyItemTierTypeDefinition to refer to.

Type: string

tierType

The enumeration matching the tier type of the item to known values, again for convenience sake.

Valid Enum Values

An Inventory (be it Character or Profile level) is comprised of many Buckets. An example of a bucket is "Primary Weapons", where all of the primary weapons on a character are gathered together into a single visual element in the UI: a subset of the inventory that has a limited number of slots, and in this case also has an associated Equipment Slot for equipping an item in the bucket.
Item definitions declare what their "default" bucket is (DestinyInventoryItemDefinition.inventory.bucketTypeHash), and Item instances will tell you which bucket they are currently residing in (DestinyItemComponent.bucketHash). You can use this information along with the DestinyInventoryBucketDefinition to show these items grouped by bucket.
You cannot transfer an item to a bucket that is not its Default without going through a Vendor's "accepted items" (DestinyVendorDefinition.acceptedItems). This is how transfer functionality like the Vault is implemented, as a feature of a Vendor. See the vendor's acceptedItems property for more details.

Use this property to provide a quick-and-dirty recommended ordering for buckets in the UI. Most UIs will likely want to forsake this for something more custom and manual.

Type: int32

itemCount

The maximum # of item "slots" in a bucket. A slot is a given combination of item + quantity.
For instance, a Weapon will always take up a single slot, and always have a quantity of 1. But a material could take up only a single slot with hundreds of quantity.

Type: int32

location

Sometimes, inventory buckets represent conceptual "locations" in the game that might not be expected. This value indicates the conceptual location of the bucket, regardless of where it is actually contained on the character/account.
See ItemLocation for details.
Note that location includes the Vault and the Postmaster (both of whom being just inventory buckets with additional actions that can be performed on them through a Vendor)

If TRUE, there is at least one Vendor that can transfer items to/from this bucket. See the DestinyVendorDefinition's acceptedItems property for more information on how transferring works.

Type: boolean

enabled

If True, this bucket is enabled. Disabled buckets may include buckets that were included for test purposes, or that were going to be used but then were abandoned but never removed from content *cough*.

Type: boolean

fifo

if a FIFO bucket fills up, it will delete the oldest item from said bucket when a new item tries to be added to it. If this is FALSE, the bucket will not allow new items to be placed in it until room is made by the user manually deleting items from it. You can see an example of this with the Postmaster's bucket.

Type: boolean

hash

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Object Properties

The default portion of quality that will transfer from the infuser to the infusee item. (InfuserQuality - InfuseeQuality) * baseQualityTransferRatio = base quality transferred.

Type: float

minimumQualityIncrement

As long as InfuserQuality > InfuseeQuality, the amount of quality bestowed is guaranteed to be at least this value, even if the transferRatio would dictate that it should be less. The total amount of quality that ends up in the Infusee cannot exceed the Infuser's quality however (for instance, if you infuse a 300 item with a 301 item and the minimum quality increment is 10, the infused item will not end up with 310 quality)

If true, items in the set can only be added in increasing order, and adding an item will remove any previous item. For Quests, this is by necessity true. Only one quest step is present at a time, and previous steps are removed as you advance in the quest.

Type: boolean

setIsFeatured

If true, the UI should treat this quest as "featured"

Type: boolean

setType

A string identifier we can use to attempt to identify the category of the Quest.

Defines a particular entry in an ItemSet (AKA a particular Quest Step in a Quest)

Type: object

Object Properties

trackingValue

Used for tracking which step a user reached. These values will be populated in the user's internal state, which we expose externally as a more usable DestinyQuestStatus object. If this item has been obtained, this value will be set in trackingUnlockValueHash.

Type: int32

itemHash

Mapped to Definition

This is the hash identifier for a DestinyInventoryItemDefinition representing this quest step.

Information about the item's calculated stats, with as much data as we can find for the stats without having an actual instance of the item.
Note that this means the entire concept of providing these stats is fundamentally insufficient: we cannot predict with 100% accuracy the conditions under which an item can spawn, so we use various heuristics to attempt to simulate the conditions as accurately as possible. Actual stats for items in-game can and will vary, but these should at least be useful base points for comparison and display.
It is also worth noting that some stats, like Magazine size, have further calculations performed on them by scripts in-game and on the game servers that BNet does not have access to. We cannot know how those stats are further transformed, and thus some stats will be inaccurate even on instances of items in BNet vs. how they appear in-game. This is a known limitation of our item statistics, without any planned fix.

Type: object

Object Properties

statGroupHash

NullableMapped to Definition

If the item's stats are meant to be modified by a DestinyStatGroupDefinition, this will be the identifier for that definition.
If you are using live data or precomputed stats data on the DestinyInventoryItemDefinition.stats.stats property, you don't have to worry about statGroupHash and how it alters stats: the already altered stats are provided to you. But if you want to see how the sausage gets made, or perform computations yourself, this is valuable information.

If you are looking for precomputed values for the stats on a weapon, this is where they are stored. Technically these are the "Display" stat values. Please see DestinyStatsDefinition for what Display Stat Values means, it's a very long story... but essentially these are the closest values BNet can get to the item stats that you see in-game.
These stats are keyed by the DestinyStatDefinition's hash identifier for the stat that's found on the item.

A quick and lazy way to determine whether any stat other than the "primary" stat is actually visible on the item. Items often have stats that we return in case people find them useful, but they're not part of the "Stat Group" and thus we wouldn't display them in our UI. If this is False, then we're not going to display any of these stats other than the primary one.

Type: boolean

primaryBaseStatHash

Mapped to Definition

This stat is determined to be the "primary" stat, and can be looked up in the stats or any other stat collection related to the item.
Use this hash to look up the stat's value using DestinyInventoryItemDefinition.stats.stats, and the renderable data for the primary stat in the related DestinyStatDefinition.

Defines a specific stat value on an item, and the minimum/maximum range that we could compute for the item based on our heuristics for how the item might be generated.
Not guaranteed to match real-world instances of the item, but should hopefully at least be close. If it's not close, let us know on the Bungie API forums.

Type: object

Object Properties

This value represents the stat value assuming the minimum possible roll but accounting for any mandatory bonuses that should be applied to the stat on item creation.
In Destiny 1, this was different from the "minimum" value because there were certain conditions where an item could be theoretically lower level/value than the initial roll.
In Destiny 2, this is not possible unless Talent Grids begin to be used again for these purposes or some other system change occurs... thus in practice, value and minimum should be the same in Destiny 2. Good riddance.

Type: int32

minimum

The minimum possible value for this stat that we think the item can roll.

Type: int32

maximum

The maximum possible value for this stat that we think the item can roll.

This represents a stat that's applied to a character or an item (such as a weapon, piece of armor, or a vehicle).
An example of a stat might be Attack Power on a weapon.
Stats go through a complex set of transformations before they end up being shown to the user as a number or a progress bar, and those transformations are fundamentally intertwined with the concept of a "Stat Group" (DestinyStatGroupDefinition). Items have both Stats and a reference to a Stat Group, and it is the Stat Group that takes the raw stat information and gives it both rendering metadata (such as whether to show it as a number or a progress bar) and the final transformation data (interpolation tables to turn the raw investment stat into a display stat). Please see DestinyStatGroupDefinition for more information on that transformational process.
Stats are segregated from Stat Groups because different items and types of items can refer to the same stat, but have different "scales" for the stat while still having the same underlying value. For example, both a Shotgun and an Auto Rifle may have a "raw" impact stat of 50, but the Auto Rifle's Stat Group will scale that 50 down so that, when it is displayed, it is a smaller value relative to the shotgun. (this is a totally made up example, don't assume shotguns have naturally higher impact than auto rifles because of this)
A final caveat is that some stats, even after this "final" transformation, go through yet another set of transformations directly in the game as a result of dynamic, stateful scripts that get run. BNet has no access to these scripts, nor any way to know which scripts get executed. As a result, the stats for an item that you see in-game - particularly for stats that are often impacted by Perks, like Magazine Size - can change dramatically from what we return on Bungie.Net. This is a known issue with no fix coming down the pipeline. Take these stats with a grain of salt.
Stats actually go through four transformations, for those interested:
1) "Sandbox" stat, the "most raw" form. These are pretty much useless without transformations applied, and thus are not currently returned in the API. If you really want these, we can provide them. Maybe someone could do something cool with it?
2) "Investment" stat (the stat's value after DestinyStatDefinition's interpolation tables and aggregation logic is applied to the "Sandbox" stat value)
3) "Display" stat (the stat's base UI-visible value after DestinyStatGroupDefinition's interpolation tables are applied to the Investment Stat value. For most stats, this is what is displayed.)
4) Underlying in-game stat (the stat's actual value according to the game, after the game runs dynamic scripts based on the game and character's state. This is the final transformation that BNet does not have access to. For most stats, this is not actually displayed to the user, with the exception of Magazine Size which is then piped back to the UI for display in-game, but not to BNet.)

True if the stat is computed rather than being delivered as a raw value on items.
For instance, the Light stat in Destiny 1 was a computed stat.

Type: boolean

hash

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

When a Stat (DestinyStatDefinition) is aggregated, this is the rules used for determining the level and formula used for aggregation.
* CharacterAverage = apply a weighted average using the related DestinyStatGroupDefinition on the DestinyInventoryItemDefinition across the character's equipped items. See both of those definitions for details. * Character = don't aggregate: the stat should be located and used directly on the character. * Item = don't aggregate: the stat should be located and used directly on the item.

Type: int32

Valid Enum Values

When an inventory item (DestinyInventoryItemDefinition) has Stats (such as Attack Power), the item will refer to a Stat Group. This definition enumerates the properties used to transform the item's "Investment" stats into "Display" stats.
See DestinyStatDefinition's documentation for information about the transformation of Stats, and the meaning of an Investment vs. a Display stat.
If you don't want to do these calculations on your own, fear not: pulling live data from the BNet endpoints will return display stat values pre-computed and ready for you to use. I highly recommend this approach, saves a lot of time and also accounts for certain stat modifiers that can't easily be accounted for without live data (such as stat modifiers on Talent Grids and Socket Plugs)

Mapped to Mobile Manifest Table: StatGroups

Type: object

Object Properties

maximumValue

The maximum possible value that any stat in this group can be transformed into.
This is used by stats that *don't* have scaledStats entries below, but that still need to be displayed as a progress bar, in which case this is used as the upper bound for said progress bar. (the lower bound is always 0)

Type: int32

uiPosition

This apparently indicates the position of the stats in the UI? I've returned it in case anyone can use it, but it's not of any use to us on BNet. Something's being lost in translation with this value.

Type: int32

scaledStats

Any stat that requires scaling to be transformed from an "Investment" stat to a "Display" stat will have an entry in this list. For more information on what those types of stats mean and the transformation process, see DestinyStatDefinition.
In retrospect, I wouldn't mind if this was a dictionary keyed by the stat hash instead. But I'm going to leave it be because [[After Apple Picking]].

The game has the ability to override, based on the stat group, what the localized text is that is displayed for Stats being shown on the item.
Mercifully, no Stat Groups use this feature currently. If they start using them, we'll all need to start using them (and those of you who are more prudent than I am can go ahead and start pre-checking for this.)

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Describes the way that an Item Stat (see DestinyStatDefinition) is transformed using the DestinyStatGroupDefinition related to that item. See both of the aforementioned definitions for more information about the stages of stat transformation.
This represents the transformation of a stat into a "Display" stat (the closest value that BNet can get to the in-game display value of the stat)

Type: object

Object Properties

statHash

Mapped to Definition

The hash identifier for the stat being transformed into a Display stat.
Use it to look up the DestinyStatDefinition, or key into a DestinyInventoryItemDefinition's stats property.

Regardless of the output of interpolation, this is the maximum possible value that the stat can be. It should also be used as the upper bound for displaying the stat as a progress bar (the minimum always being 0)

Type: int32

displayAsNumeric

If this is true, the stat should be displayed as a number. Otherwise, display it as a progress bar. Or, you know, do whatever you want. There's no displayAsNumeric police.

Type: boolean

displayInterpolation

The interpolation table representing how the Investment Stat is transformed into a Display Stat.
See DestinyStatDefinition for a description of the stages of stat transformation.

Object Properties

Stat Groups (DestinyStatGroupDefinition) has the ability to override the localized text associated with stats that are to be shown on the items with which they are associated.
This defines a specific overridden stat. You could theoretically check these before rendering your stat UI, and for each stat that has an override show these displayProperties instead of those on the DestinyStatDefinition.
Or you could be like us, and skip that for now because the game has yet to actually use this feature. But know that it's here, waiting for a resilliant young designer to take up the mantle and make us all look foolish by showing the wrong name for stats.
Note that, if this gets used, the override will apply only to items using the overriding Stat Group. Other items will still show the default stat's name/description.

Type: object

Object Properties

statHash

Mapped to Definition

The hash identifier of the stat whose display properties are being overridden.

If defined, this is the label used to check if the item has other items of matching types already equipped.
For instance, when you aren't allowed to equip more than one Exotic Weapon, that's because all exotic weapons have identical uniqueLabels and the game checks the to-be-equipped item's uniqueLabel vs. all other already equipped items (other than the item in the slot that's about to be occupied).

Type: string

uniqueLabelHash

The hash of that unique label. Does not point to a specific definition.

Type: uint32

equipmentSlotTypeHash

Mapped to Definition

An equipped item *must* be equipped in an Equipment Slot. This is the hash identifier of the DestinyEquipmentSlotDefinition into which it must be equipped.

Valid Enum Values

Characters can not only have Inventory buckets (containers of items that are generally matched by their type or functionality), they can also have Equipment Slots.
The Equipment Slot is an indicator that the related bucket can have instanced items equipped on the character. For instance, the Primary Weapon bucket has an Equipment Slot that determines whether you can equip primary weapons, and holds the association between its slot and the inventory bucket from which it can have items equipped.
An Equipment Slot must have a related Inventory Bucket, but not all inventory buckets must have Equipment Slots.

Mapped to Mobile Manifest Table: EquipmentSlots

Type: object

Object Properties

These technically point to "Equipment Category Definitions". But don't get excited. There's nothing of significant value in those definitions, so I didn't bother to expose them. You can use the hash here to group equipment slots by common functionality, which serves the same purpose as if we had the Equipment Category definitions exposed.

If True, equipped items should have their custom art dyes applied when rendering the item. Otherwise, custom art dyes on an item should be ignored if the item is equipped in this slot.

Type: boolean

hash

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Object Properties

Items like Sacks or Boxes can have items that it shows in-game when you view details that represent the items you can obtain if you use or acquire the item.
This defines those categories, and gives some insights into that data's source.

Type: object

Object Properties

previewVendorHash

Mapped to Definition

If the preview data is derived from a fake "Preview" Vendor, this will be the hash identifier for the DestinyVendorDefinition of that fake vendor.

A shortcut for the fact that some items have a "Preview Vendor" - See DestinyInventoryItemDefinition.preview.previewVendorHash - that is intended to be used to show what items you can get as a result of acquiring or using this item.
A common example of this in Destiny 1 was Eververse "Boxes," which could have many possible items. This "Preview Vendor" is not a vendor you can actually see in the game, but it defines categories and sale items for all of the possible items you could get from the Box so that the game can show them to you. We summarize that info here so that you don't have to do that Vendor lookup and aggregation manually.

Type: object

Object Properties

categoryDescription

The localized string for the category title. This will be something describing the items you can get as a group, or your likelihood/the quantity you'll get.

Type: string

items

This is the list of all of the items for this category and the basic properties we'll know about them.

This is a reference to, and summary data for, a specific item that you can get as a result of Using or Acquiring some other Item (For example, this could be summary information for an Emote that you can get by opening an an Eververse Box) See DestinyDerivedItemCategoryDefinition for more information.

Type: object

Object Properties

itemHash

Nullable

The hash for the DestinyInventoryItemDefinition of this derived item, if there is one. Sometimes we are given this information as a manual override, in which case there won't be an actual DestinyInventoryItemDefinition for what we display, but you can still show the strings from this object itself.

Type: uint32

itemName

The name of the derived item.

Type: string

itemDetail

Additional details about the derived item, in addition to the description.

Type: string

itemDescription

A brief description of the item.

Type: string

iconPath

An icon for the item.

Type: string

vendorItemIndex

If the item was derived from a "Preview Vendor", this will be an index into the DestinyVendorDefinition's itemList property. Otherwise, -1.

These are the definitions for Vendors.
In Destiny, a Vendor can be a lot of things - some things that you wouldn't expect, and some things that you don't even see directly in the game. Vendors are the Dolly Levi of the Destiny universe.
- Traditional Vendors as you see in game: people who you come up to and who give you quests, rewards, or who you can buy things from.
- Kiosks/Collections, which are really just Vendors that don't charge currency (or charge some pittance of a currency) and whose gating for purchases revolves more around your character's state.
- Previews for rewards or the contents of sacks. These are implemented as Vendors, where you can't actually purchase from them but the items that they have for sale and the categories of sale items reflect the rewards or contents of the sack. This is so that the game could reuse the existing Vendor display UI for rewards and save a bunch of wheel reinvention.
- Item Transfer capabilities, like the Vault and Postmaster. Vendors can have "acceptedItem" buckets that determine the source and destination buckets for transfers. When you interact with such a vendor, these buckets are what gets shown in the UI instead of any items that the Vendor would have for sale. Yep, the Vault is a vendor.
It is pretty much guaranteed that they'll be used for even more features in the future. They have come to be seen more as generic categorized containers for items than "vendors" in a traditional sense, for better or worse.
Where possible and time allows, we'll attempt to split those out into their own more digestible derived "Definitions": but often time does not allow that, as you can see from the above ways that vendors are used which we never split off from Vendor Definitions externally.
Since Vendors are so many things to so many parts of the game, the definition is understandably complex. You will want to combine this data with live Vendor information from the API when it is available.

Object Properties

If the vendor has a custom localized string describing the "buy" action, that is returned here.

Type: string

sellString

Ditto for selling. Not that you can sell items to a vendor anymore. Will it come back? Who knows. The string's still there.

Type: string

displayItemHash

Mapped to Definition

If the vendor has an item that should be displayed as the "featured" item, this is the hash identifier for that DestinyVendorItemDefinition.
Apparently this is usually a related currency, like a reputation token. But it need not be restricted to that.

If this is true, you aren't allowed to buy whatever the vendor is selling.

Type: boolean

inhibitSelling

If this is true, you're not allowed to sell whatever the vendor is buying.

Type: boolean

factionHash

Mapped to Definition

If the Vendor has a faction, this hash will be valid and point to a DestinyFactionDefinition.
The game UI and BNet often mine the faction definition for additional elements and details to place on the screen, such as the faction's Progression status (aka "Reputation").

A number used for calculating the frequency of a vendor's inventory resetting/refreshing.
Don't worry about calculating this - we do it on the server side and send you the next refresh date with the live data.

Type: int32

resetOffsetMinutes

Again, used for reset/refreshing of inventory. Don't worry too much about it. Unless you want to.

Type: int32

failureStrings

If an item can't be purchased from the vendor, there may be many "custom"/game state specific reasons why not.
This is a list of localized strings with messages for those custom failures. The live BNet data will return a failureIndexes property for items that can't be purchased: using those values to index into this array, you can show the user the appropriate failure message for the item that can't be bought.

Type: array

Array Contents:
string

unlockRanges

If we were able to predict the dates when this Vendor will be visible/available, this will be the list of those date ranges. Sadly, we're not able to predict this very frequently, so this will often be useless data.

The internal identifier for the Vendor. A holdover from the old days of Vendors, but we don't have time to refactor it away.

Type: string

vendorPortrait

A portrait of the Vendor's smiling mug. Or frothing tentacles.

Type: string

vendorBanner

If the vendor has a custom banner image, that can be found here.

Type: string

enabled

If a vendor is not enabled, we won't even save the vendor's definition, and we won't return any items or info about them. It's as if they don't exist.

Type: boolean

visible

If a vendor is not visible, we still have and will give vendor definition info, but we won't use them for things like Advisors or UI.

Type: boolean

vendorCategoryIdentifier

The identifier of the VendorCategoryDefinition for this vendor.

Type: string

vendorSubcategoryIdentifier

The identifier of the VendorCategoryDefinition for this vendor's subcategory.

Type: string

consolidateCategories

If TRUE, consolidate categories that only differ by trivial properties (such as having minor differences in name)

Type: boolean

actions

Describes "actions" that can be performed on a vendor. Currently, none of these exist. But theoretically a Vendor could let you interact with it by performing actions. We'll see what these end up looking like if they ever get used.

These are the headers for sections of items that the vendor is selling. When you see items organized by category in the header, it is these categories that it is showing.
Well, technically not *exactly* these. On BNet, it doesn't make sense to have categories be "paged" as we do in Destiny, so we run some heuristics to attempt to aggregate pages of categories together.
These are the categories post-concatenation, if the vendor had concatenation applied. If you want the pre-aggregated category data, use originalCategories.

Display Categories are different from "categories" in that these are specifically for visual grouping and display of categories in Vendor UI.
The "categories" structure is for validation of the contained items, and can be categorized entirely separately from "Display Categories", there need be and often will be no meaningful relationship between the two.

If the vendor sells items (or merely has a list of items to show like the "Sack" vendors do), this is the list of those items that the vendor can sell. From this list, only a subset will be available from the vendor at any given time, selected randomly and reset on the vendor's refresh interval.
Note that a vendor can sell the same item multiple ways: for instance, nothing stops a vendor from selling you some specific weapon but using two different currencies, or the same weapon at multiple "item levels".

As many of you know, Vendor data has historically been pretty brutal on the BNet servers. In an effort to reduce this workload, only Vendors with this flag set will be returned on Vendor requests. This allows us to filter out Vendors that don't dynamic data that's particularly useful: things like "Preview/Sack" vendors, for example, that you can usually suss out the details for using just the definitions themselves.

Type: boolean

hash

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Object Properties

I regret calling this a "large icon". It's more like a medium-sized image with a picture of the vendor's mug on it, trying their best to look cool. Not what one would call an icon.

Type: string

subtitle

Type: string

originalIcon

If we replaced the icon with something more glitzy, this is the original icon that the vendor had according to the game's content. It may be more lame and/or have less razzle-dazzle. But who am I to tell you which icon to use.

Type: string

requirementsDisplay

Vendors, in addition to expected display property data, may also show some "common requirements" as statically defined definition data. This might be when a vendor accepts a single type of currency, or when the currency is unique to the vendor and the designers wanted to show that currency when you interact with the vendor.

Note that "icon" is sometimes misleading, and should be interpreted in the context of the entity. For instance, in Destiny 1 the DestinyRecordBookDefinition's icon was a big picture of a book.
But usually, it will be a small square image that you can use as... well, an icon.

Object Properties

Object Properties

If a vendor can ever end up performing actions, these are the properties that will be related to those actions. I'm not going to bother documenting this yet, as it is unused and unclear if it will ever be used... but in case it is ever populated and someone finds it useful, it is defined here.

This is the definition for a single Vendor Category, into which Sale Items are grouped.

Type: object

Object Properties

categoryIndex

The index of the category in the original category definitions for the vendor.

Type: int32

categoryId

The string identifier of the category.

Type: string

categoryHash

The hashed identifier for the category. (note that this is NOT pointing to a DestinyVendorCategoryDefinition, it's confusing but this is a sale item category in a vendor, not a categorization of vendors themselves)

Type: uint32

quantityAvailable

The amount of items that will be available when this category is shown.

Type: int32

showUnavailableItems

If items aren't up for sale in this category, should we still show them (greyed out)?

Type: boolean

hideIfNoCurrency

If you don't have the currency required to buy items from this category, should the items be hidden?

Type: boolean

hideFromRegularPurchase

True if this category doesn't allow purchases.

Type: boolean

buyStringOverride

The localized string for making purchases from this category, if it is different from the vendor's string for purchasing.

Type: string

disabledDescription

If the category is disabled, this is the localized description to show.

Type: string

displayTitle

The localized title of the category.

Type: string

overlay

If this category has an overlay prompt that should appear, this contains the details of that prompt.

Object Properties

Display Categories are different from "categories" in that these are specifically for visual grouping and display of categories in Vendor UI. The "categories" structure is for validation of the contained items, and can be categorized entirely separately from "Display Categories", there need be and often will be no meaningful relationship between the two.

Object Properties

If >= 0, this is the category of sale items to show along with this interaction dialog.

Type: int32

questlineItemHash

Mapped to Definition

If this interaction dialog is about a quest, this is the questline related to the interaction. You can use this to show the quest overview, or even the character's status with the quest if you use it to find the character's current Quest Step by checking their inventory against this questlineItemHash's DestinyInventoryItemDefinition.setData.

A UI hint for the behavior of the interaction screen. This is useful to determine what type of interaction is occurring, such as a prompt to receive a rank up reward or a prompt to choose a reward for completing a quest. The hash isn't as useful as the Enum in retrospect, well what can you do. Try using interactionType instead.

Type: uint32

interactionType

The enumerated version of the possible UI hints for vendor interactions, which is a little easier to grok than the hash found in uiInteractionType.

When the interaction is replied to, Reward sites will fire and items potentially selected based on whether the given unlock expression is TRUE.
You can potentially choose one from multiple replies when replying to an interaction: this is how you get either/or rewards from vendors.

Valid Enum Values

Object Properties

vendorItemIndex

The index into the DestinyVendorDefinition.saleList. This is what we use to refer to items being sold throughout live and definition data.

Type: int32

itemHash

Mapped to Definition

The hash identifier of the item being sold (DestinyInventoryItemDefinition).
Note that a vendor can sell the same item in multiple ways, so don't assume that itemHash is a unique identifier for this entity.

The amount you will recieve of the item described in itemHash if you make the purchase.

Type: int32

failureIndexes

An list of indexes into the DestinyVendorDefinition.failureStrings array, indicating the possible failure strings that can be relevant for this item.

Type: array

Array Contents:
int32

currencies

This is a pre-compiled aggregation of item value and priceOverrideList, so that we have one place to check for what the purchaser must pay for the item. Use this instead of trying to piece together the price separately.
JUST KIDDING HA this never got populated, who's the idiot now? Hint: Me. Now they'll actually be populated [amola, 2017-11-12]

The amount of time before refundability of the newly purchased item will expire.

Type: int32

creationLevels

The Default level at which the item will spawn. Almost always driven by an adjusto these days. Ideally should be singular. It's a long story how this ended up as a list, but there is always either going to be 0:1 of these entities.

This is an index specifically into the display category, as opposed to the server-side Categories (which do not need to match or pair with each other in any way: server side categories are really just structures for common validation. Display Category will let us more easily categorize items visually)

Type: int32

categoryIndex

The index into the DestinyVendorDefinition.categories array, so you can find the category associated with this item.

Type: int32

originalCategoryIndex

Same as above, but for the original category indexes.

Type: int32

minimumLevel

The minimum character level at which this item is available for sale.

Type: int32

maximumLevel

The maximum character level at which this item is available for sale.

Type: int32

action

The action to be performed when purchasing the item, if it's not just "buy".

The inventory bucket into which this item will be placed upon purchase.

Type: uint32

visibilityScope

The most restrictive scope that determines whether the item is available in the Vendor's inventory. See DestinyGatingScope's documentation for more information.
This can be determined by Unlock gating, or by whether or not the item has purchase level requirements (minimumLevel and maximumLevel properties).

Similar to visibilityScope, it represents the most restrictive scope that determines whether the item can be purchased. It will at least be as restrictive as visibilityScope, but could be more restrictive if the item has additional purchase requirements beyond whether it is merely visible or not.
See DestinyGatingScope's documentation for more information.

Object Properties

This enumeration represents the most restrictive type of gating that is being performed by an entity. This is useful as a shortcut to avoid a lot of lookups when determining whether the gating on an Entity applies to everyone equally, or to their specific Profile or Character states.
None = There is no gating on this item. Global = The gating on this item is based entirely on global game state. It will be gated the same for everyone. Clan = The gating on this item is at the Clan level. For instance, if you're gated by Clan level this will be the case. Profile = The gating includes Profile-specific checks, but not on the Profile's characters. An example of this might be when you acquire an Emblem: the Emblem will be available in your Kiosk for all characters in your Profile from that point onward. Character = The gating includes Character-specific checks, including character level restrictions. An example of this might be an item that you can't purchase from a Vendor until you reach a specific Character Level. Item = The gating includes item-specific checks. For BNet, this generally implies that we'll show this data only on a character level or deeper. AssumedWorstCase = The unlocks and checks being used for this calculation are of an unknown type and are used for unknown purposes. For instance, if some great person decided that an unlock value should be globally scoped, but then the game changes it using character-specific data in a way that BNet doesn't know about. Because of the open-ended potential for this to occur, many unlock checks for "globally" scoped unlock data may be assumed as the worst case unless it has been specifically whitelisted as otherwise. That sucks, but them's the breaks.

Object Properties

If you ever wondered how the Vault works, here it is.
The Vault is merely a set of inventory buckets that exist on your Profile/Account level. When you transfer items in the Vault, the game is using the Vault Vendor's DestinyVendorAcceptedItemDefinitions to see where the appropriate destination bucket is for the source bucket from whence your item is moving. If it finds such an entry, it transfers the item to the other bucket.
The mechanics for Postmaster works similarly, which is also a vendor. All driven by Accepted Items.

Type: object

Object Properties

acceptedInventoryBucketHash

Mapped to Definition

The "source" bucket for a transfer. When a user wants to transfer an item, the appropriate DestinyVendorDefinition's acceptedItems property is evaluated, looking for an entry where acceptedInventoryBucketHash matches the bucket that the item being transferred is currently located. If it exists, the item will be transferred into whatever bucket is defined by destinationInventoryBucketHash.

These definitions represent Factions in the game. Factions have ended up unilaterally being related to Vendors that represent them, but that need not necessarily be the case.
A Faction is really just an entity that has a related progression for which a character can gain experience. In Destiny 1, Dead Orbit was an example of a Faction: there happens to be a Vendor that represents Dead Orbit (and indeed, DestinyVendorDefinition.factionHash defines to this relationship), but Dead Orbit could theoretically exist without the Vendor that provides rewards.

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

On to one of the more confusing subjects of the API. What is a Destination, and what is the relationship between it, Activities, Locations, and Places?
A "Destination" is a specific region/city/area of a larger "Place". For instance, a Place might be Earth where a Destination might be Bellevue, Washington. (Please, pick a more interesting destination if you come to visit Earth).

If the Destination has default Activity Graphs (i.e. "Map") that should be shown in the director, this is the list of those Graphs. At most, only one should be active at any given time for a Destination: these would represent, for example, different variants on a Map if the Destination is changing on a macro level based on game state.

A Destination may have many "Bubbles" zones with human readable properties.
We don't get as much info as I'd like about them - I'd love to return info like where on the map they are located - but at least this gives you the name of those bubbles. bubbleSettings and bubbles both have the identical number of entries, and you should match up their indexes to provide matching bubble and bubbleSettings data.

This provides the unique identifiers for every bubble in the destination (only guaranteed unique within the destination), and any intrinsic properties of the bubble.
bubbleSettings and bubbles both have the identical number of entries, and you should match up their indexes to provide matching bubble and bubbleSettings data.

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

Destinations and Activities may have default Activity Graphs that should be shown when you bring up the Director and are playing in either.
This contract defines the graph referred to and the gating for when it is relevant.

Type: object

Object Properties

activityGraphHash

Mapped to Definition

The hash identifier of the DestinyActivityGraphDefinition that should be shown when opening the director.

Represents a Map View in the director: be them overview views, destination views, or other.
They have nodes which map to activities, and other various visual elements that we (or others) may or may not be able to use.
Activity graphs, most importantly, have nodes which can have activities in various states of playability.
Unfortunately, activity graphs are combined at runtime with Game UI-only assets such as fragments of map images, various in-game special effects, decals etc... that we don't get in these definitions.
If we end up having time, we may end up trying to manually populate those here: but the last time we tried that, before the lead-up to D1, it proved to be unmaintainable as the game's content changed. So don't bet the farm on us providing that content in this definition.

Mapped to Mobile Manifest Table: ActivityGraphs

Type: object

Object Properties

nodes

These represent the visual "nodes" on the map's view. These are the activities you can click on in the map.

Objectives can display on maps, and this is supposedly metadata for that. I have not had the time to analyze the details of what is useful within however: we could be missing important data to make this work. Expect this property to be expanded on later if possible.

Progressions can also display on maps, but similarly to displayObjectives we appear to lack some required information and context right now. We will have to look into it later and add more data if possible.

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!

This is the position and other data related to nodes in the activity graph that you can click to launch activities. An Activity Graph node will only have one active Activity at a time, which will determine the activity to be launched (and, unless overrideDisplay information is provided, will also determine the tooltip and other UI related to the node)

Type: object

Object Properties

nodeId

An identifier for the Activity Graph Node, only guaranteed to be unique within its parent Activity Graph.

Type: uint32

overrideDisplay

The node *may* have display properties that override the active Activity's display properties.

The node may have various visual accents placed on it, or styles applied. These are the list of possible styles that the Node can have. The game iterates through each, looking for the first one that passes a check of the required game/character/account state in order to show that style, and then renders the node in that style.

Object Properties

Nodes can have different visual states. This object represents a single visual state ("highlight type") that a node can be in, and the unlock expression condition to determine whether it should be set.

Type: object

Object Properties

highlightType

The node can be highlighted in a variety of ways - the game iterates through these and finds the first FeaturingState that is valid at the present moment given the Game, Account, and Character state, and renders the node in that state. See the ActivityGraphNodeHighlightType enum for possible values.

The various known UI styles in which an item can be highlighted. It'll be up to you to determine what you want to show based on this highlighting, BNet doesn't have any assets that correspond to these states. And yeah, RiseOfIron and Comet have their own special highlight states. Don't ask me, I can't imagine they're still used.

Type: int32

Valid Enum Values

The actual activity to be redirected to when you click on the node. Note that a node can have many Activities attached to it: but only one will be active at any given time. The list of Node Activities will be traversed, and the first one found to be active will be displayed. This way, a node can layer multiple variants of an activity on top of each other. For instance, one node can control the weekly Crucible Playlist. There are multiple possible playlists, but only one is active for the week.

Type: object

Object Properties

nodeActivityId

An identifier for this node activity. It is only guaranteed to be unique within the Activity Graph.

Type: uint32

activityHash

Mapped to Definition

The activity that will be activated if the user clicks on this node. Controls all activity-related information displayed on the node if it is active (the text shown in the tooltip etc)

The static data about Activities in Destiny 2.
Note that an Activity must be combined with an ActivityMode to know - from a Gameplay perspective - what the user is "Playing".
In most PvE activities, this is fairly straightforward. A Story Activity can only be played in the Story Activity Mode.
However, in PvP activities, the Activity alone only tells you the map being played, or the Playlist that the user chose to enter. You'll need to know the Activity Mode they're playing to know that they're playing Mode X on Map Y.
Activity Definitions tell a great deal of information about what *could* be relevant to a user: what rewards they can earn, what challenges could be performed, what modifiers could be applied. To figure out which of these properties is actually live, you'll need to combine the definition with "Live" data from one of the Destiny endpoints.
Activities also have Activity Types, but unfortunately in Destiny 2 these are even less reliable of a source of information than they were in Destiny 1. I will be looking into ways to provide more reliable sources for type information as time goes on, but for now we're going to have to deal with the limitations. See DestinyActivityTypeDefinition for more information.

Object Properties

If the activity has an icon associated with a specific release (such as a DLC), this is the path to that release's icon.

Type: string

releaseTime

If the activity will not be visible until a specific and known time, this will be the seconds since the Epoch when it will become visible.

Type: int32

activityLevel

The difficulty level of the activity.

Type: int32

activityLightLevel

The recommended light level for this activity.

Type: int32

destinationHash

Mapped to Definition

The hash identifier for the Destination on which this Activity is played. Use it to look up the DestinyDestinationDefinition for human readable info about the destination. A Destination can be thought of as a more specific location than a "Place". For instance, if the "Place" is Earth, the "Destination" would be a specific city or region on Earth.

The hash identifier for the "Place" on which this Activity is played. Use it to look up the DestinyPlaceDefinition for human readable info about the Place. A Place is the largest-scoped concept for location information. For instance, if the "Place" is Earth, the "Destination" would be a specific city or region on Earth.

The hash identifier for the Activity Type of this Activity. You may use it to look up the DestinyActivityTypeDefinition for human readable info, but be forewarned: Playlists and many PVP Map Activities will map to generic Activity Types. You'll have to use your knowledge of the Activity Mode being played to get more specific information about what the user is playing.

When Activities are completed, we generate a "Post-Game Carnage Report", or PGCR, with details about what happened in that activity (how many kills someone got, which team won, etc...) We use this image as the background when displaying PGCR information, and often use it when we refer to the Activity in general.

Type: string

rewards

The expected possible rewards for the activity. These rewards may or may not be accessible for an individual player based on their character state, the account state, and even the game's state overall. But it is a useful reference for possible rewards you can earn in the activity. These match up to rewards displayed when you hover over the Activity in the in-game Director, and often refer to Placeholder or "Dummy" items: items that tell you what you can earn in vague terms rather than what you'll specifically be earning (partly because the game doesn't even know what you'll earn specifically until you roll for it at the end)

Activities can have Modifiers, as defined in DestinyActivityModifierDefinition. These are references to the modifiers that *can* be applied to that activity, along with data that we use to determine if that modifier is actually active at any given point in time.

If True, this Activity is actually a Playlist that refers to multiple possible specific Activities and Activity Modes. For instance, a Crucible Playlist may have references to multiple Activities (Maps) with multiple Activity Modes (specific PvP gameplay modes). If this is true, refer to the playlistItems property for the specific entries in the playlist.

Type: boolean

challenges

An activity can have many Challenges, of which any subset of them may be active for play at any given period of time. This gives the information about the challenges and data that we use to understand when they're active and what rewards they provide. Sadly, at the moment there's no central definition for challenges: much like "Skulls" were in Destiny 1, these are defined on individual activities and there can be many duplicates/near duplicates across the Destiny 2 ecosystem. I have it in mind to centralize these in a future revision of the API, but we are out of time.

If there are status strings related to the activity and based on internal state of the game, account, or character, then this will be the definition of those strings and the states needed in order for the strings to be shown.

If the activity had an activity mode directly defined on it, this will be the enum value of that mode.

Type: int32

Valid Enum Values

None: 0

Story: 2

Strike: 3

Raid: 4

AllPvP: 5

Patrol: 6

AllPvE: 7

Reserved9: 9

Control: 10

Reserved11: 11

Clash: 12

Clash -> Destiny's name for Team Deathmatch. 4v4 combat, the team with the highest kills at the end of time wins.

Reserved13: 13

CrimsonDoubles: 15

Nightfall: 16

HeroicNightfall: 17

AllStrikes: 18

IronBanner: 19

Reserved20: 20

Reserved21: 21

Reserved22: 22

Reserved24: 24

Reserved25: 25

Reserved26: 26

Reserved27: 27

Reserved28: 28

Reserved29: 29

Reserved30: 30

Supremacy: 31

Reserved32: 32

Survival: 37

Countdown: 38

TrialsOfTheNine: 39

Social: 40

TrialsCountdown: 41

TrialsSurvival: 42

IronBannerControl: 43

IronBannerClash: 44

IronBannerSupremacy: 45

activityModeHashes

Mapped to Definition

The hash identifiers for Activity Modes relevant to this activity. Note that if this is a playlist, the specific playlist entry chosen will determine the actual activity modes that end up being relevant.

The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally.
When entities refer to each other in Destiny content, it is this hash that they are referring to.

Type: uint32

index

The index of the entity as it was found in the investment tables.

Type: int32

redacted

If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!