> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API resources

> Key resources and their relationships in the DVM APIs

This page summarizes the core concepts in the Digital Vending Machine® (DVM™) API data model and how they relate to each other.

## Summary table

<table>
  <colgroup>
    <col width="145" />

    <col width="564" />
  </colgroup>

  <thead>
    <tr>
      <th>Concept</th>
      <th>Definition</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Offer**</td>
      <td>A promotable product or bundle in your catalog. Has a name, availability window, one or more products (with tiers and content provider), and an optional plan.</td>
    </tr>

    <tr>
      <td>**Product**</td>
      <td>Content provider goods or services in the catalog. Has a name, one or more product tiers, and a content provider.</td>
    </tr>

    <tr>
      <td>**Product Tier**</td>
      <td>A tier within a product. Contains the provisioning key (`productTierKey`) used downstream for entitlement creation.</td>
    </tr>

    <tr>
      <td>**Offer Plan**</td>
      <td>The pricing and phase structure for an offer. Defines plan type (e.g. SUBSCRIPTION), currency, lifecycle triggers, and billing phases.</td>
    </tr>

    <tr>
      <td>**Plan Phase**</td>
      <td>A billing phase within a plan. Defines price type (FREE, DISCOUNT, FULL\_PRICE), renewal frequency, duration, amount, and billing description.</td>
    </tr>

    <tr>
      <td>**Consumer Offer**</td>
      <td>An instantiated purchase of an offer for a specific consumer. Links the offer to the consumer identifier and tracks status and lifecycle.</td>
    </tr>

    <tr>
      <td>**Entitlement**</td>
      <td>A consumer's access right to a product tier. Links to provisioning keys, content provider, and tracks status, activation, and lifecycle.</td>
    </tr>
  </tbody>
</table>

## Entity relationship diagram

The diagram below shows how these concepts relate. An Offer packages one or more Products; each Product has Product Tiers. An Offer is priced by an Offer Plan, which has one or more Plan Phases. When a consumer purchases an Offer, a Consumer Offer is created, which grants one or more Entitlements for the Product Tiers.

```mermaid theme={null}
erDiagram
  %% =========================
  %% Core data model concepts
  %% =========================

  OFFER {
    string offerId "Offer Catalog ID (uuid in catalog APIs)"
    datetime availableFromTs
    datetime availableToTs
    string name
  }

  PRODUCT {
    string productId "Catalog Product ID (uuid)"
    string name
    string contentProviderId
    string merchantAccountKey
  }

  PRODUCT_TIER {
    string productTierId "Catalog Product Tier ID (uuid)"
    string productTierKey "Provisioning key used downstream"
    string name
  }

  OFFER_PLAN {
    string planId
    string type "SUBSCRIPTION (current)"
    string currency
    int currencyAssetScale
    string lifecycleStartTrigger "Created vs Activated"
  }

  PLAN_PHASE {
    int sequence
    string priceType "FREE | DISCOUNT | FULL_PRICE"
    string renewalFrequency "ISO-8601 duration (e.g., P1M)"
    string duration "ISO-8601 duration (optional)"
    int amount "minor units"
    string displayAmount
    string billingDescription
  }

  CONSUMER_OFFER {
    string consumerOfferId "Consumer Offers ID (uuid)"
    string offerId "References OFFER.offerId"
    string consumerIdentifier "Partner/Reseller consumer key"
    string status
    datetime createdTs
  }

  ENTITLEMENT {
    string entitlementId "Entitlements/Consumer Offers ID (uuid)"
    string sharedCustomerId "Bango shared identity"
    string productTierKey "Links to PRODUCT_TIER.productTierKey"
    string productKey "Provisioning key (not in catalog)"
    string offerKey "Provisioning key (not in catalog)"
    string merchantAccountKey
    string bundleId "Source/marketing attribution"
    string status
  }

  %% =========================
  %% Relationships (cardinality)
  %% =========================

  %% An Offer includes one or more Products (current consumer-offers constraints may be 1, but modeled generally)
  OFFER }o--o{ PRODUCT : "packages"

  %% Each Product can have multiple tiers
  PRODUCT ||--o{ PRODUCT_TIER : "has"

  %% Each Offer has exactly one plan; plan has 1..n phases
  OFFER ||--|| OFFER_PLAN : "priced_by"
  OFFER_PLAN ||--o{ PLAN_PHASE : "has_phases"

  %% A Consumer Offer is an instantiated purchase of one Offer
  OFFER ||--o{ CONSUMER_OFFER : "instantiated_as"

  %% A Consumer Offer results in one or more Entitlements (access rights) for product tiers
  CONSUMER_OFFER ||--o{ ENTITLEMENT : "grants"

  %% Entitlements correspond to specific product tiers (via productTierKey)
  PRODUCT_TIER ||--o{ ENTITLEMENT : "entitles"
```