Interface RateCard

All Known Implementing Classes:
AwsPriceListRateCard, AzureRetailPricesRateCard, ConvertingRateCard, CustomRateCard, EquinixRateCard, GcpBillingCatalogRateCard, OracleCloudPriceListRateCard, ReferenceRateCard
public interface RateCard
A source of unit prices for the design-time cost, savings, and TCO models.

A rate card resolves the price of an individual planned resource - a Fabric connection or a Cloud Router - for a given bandwidth, metro, and commitment Term. Lookups return an Optional: an empty result means this card cannot price that item, which is distinct from a zero price. That distinction lets callers fall back to another source rather than silently treating "unknown" as "free."

Implementations differ by provenance (see PriceSource):

  • CustomRateCard - caller-supplied rates (e.g. negotiated contract pricing), built fluently.
  • EquinixRateCard - live fabric.prices() lookups (authoritative).
  • ReferenceRateCard - bundled, dated reference figures (indicative).
  • the design.value.ratecard.provider adapters - live cloud-egress rates from the public provider pricing APIs (AzureRetailPricesRateCard, AwsPriceListRateCard, GcpBillingCatalogRateCard, OracleCloudPriceListRateCard), tagged PriceSource.PROVIDER_API.

Use layered(RateCard...) to combine several cards into a precedence chain - the first card that can price an item wins.

multicloudLink(MulticloudLinkRequest) prices a native provider-to-provider multicloud link, which has no Equinix component. It exists so the TCO and savings models can compare the Equinix path against the alternative that does not use Equinix. Beta.

  • Method Details

    • connection

      Optional<PriceQuote> connection(ConnectionType type, int bandwidthMbps, MetroCode metro, Term term)
      Resolves the price of a single Fabric connection / virtual connection.

      Implementation contract. The matching strategy is implementation-specific, and a card whose data lacks an axis (metro, term, type) still returns its best figure - or empty - rather than failing; callers must not assume every card is sensitive to every parameter. Of the bundled cards: CustomRateCard resolves the most specific declared entry (exact metro+term down to metro/term-agnostic, then a declared default); EquinixRateCard matches bandwidth and type against the live catalogue, honours a requested metro strictly (a wrong-metro row is never returned), and prefers a term-matched row - a different-term row is only ever returned with a note naming the substitution; ReferenceRateCard matches on bandwidth alone (smallest tabulated tier at or above the request, linearly extrapolated with an EXTRAPOLATED note above the top tier) and ignores type, metro, and term entirely.

      Parameters:
      type - the connection type (e.g. EVPL_VC); may be null for any type
      bandwidthMbps - the provisioned bandwidth in Mbps
      metro - the metro the connection originates in (may be null if metro-agnostic)
      term - the commitment term (may be null if term-agnostic)
      Returns:
      the resolved quote, or Optional.empty() if this card cannot price the connection

    • cloudRouter

      Optional<PriceQuote> cloudRouter(String packageCode, MetroCode metro, Term term)
      Resolves the price of a single Fabric Cloud Router instance.

      Implementation contract. As with connection(ConnectionType, int, MetroCode, Term), matching is implementation-specific and cards without a metro/term axis return their best figure regardless. Of the bundled cards: CustomRateCard resolves the most specific declared (packageCode, metro, term) entry; EquinixRateCard matches the package code and metro structurally against the row's own descriptor (exact package equality, the row's own metro code) and prefers a term-matched row, labelling any term substitution; ReferenceRateCard ignores metro and term, and substitutes its STANDARD figure for an unlisted package with a note naming the substitution.

      Parameters:
      packageCode - the router package / tier code (e.g. "STANDARD"); may be null for any
      metro - the metro the router is deployed in (may be null if metro-agnostic)
      term - the commitment term (may be null if term-agnostic)
      Returns:
      the resolved quote, or Optional.empty() if this card cannot price the router

    • egress

      default Optional<EgressRate> egress(CloudProviderType provider, String region, EgressPath path, Term term)
      Resolves the per-GB data-egress rate for a cloud provider over a given path.

      Equinix does not sell cloud egress, so EquinixRateCard returns Optional.empty() here (the default); egress rates come from a CustomRateCard (your figures), a ReferenceRateCard (bundled indicative figures), or a provider-pricing-API card. The default returns empty so cards that do not model egress need not override it. Cards whose data has no region or term axis ignore those parameters - the custom and reference cards match on provider + path alone; only the provider-API adapters are region-sensitive.

      Parameters:
      provider - the cloud provider the data is leaving
      region - the provider region (may be null for a provider-wide rate)
      path - internet vs. private interconnect
      term - the commitment term (may be null; ignored by term-agnostic cards)
      Returns:
      the resolved egress rate, or Optional.empty() if this card cannot price it

    • colocation

      default Optional<PriceQuote> colocation(ColocationItem item, MetroCode metro, Term term)
      Resolves the price of an Equinix colocation primitive - a cabinet, a kW of power, or a cross-connect (see ColocationItem for the per-unit semantics). This lets the cost models incorporate the physical-infrastructure side of a colocation-vs-cloud comparison with the caller's real figures, not just the interconnection. Cards that do not model colocation return Optional.empty() (the default); CustomRateCard prices whatever the caller declares.
      Parameters:
      item - the colocation primitive to price
      metro - the metro (may be null if metro-agnostic)
      term - the commitment term
      Returns:
      the resolved per-unit monthly quote, or Optional.empty() if not priced

    • multicloudLink

      default Optional<MulticloudLinkQuote> multicloudLink(MulticloudLinkRequest request)
      Resolves the two-sided price of a native provider-to-provider multicloud link (for example AWS Interconnect - multicloud paired with a Google Partner Cross-Cloud Interconnect transport). No Equinix resource is part of such a link. Each provider bills its own side, so the result is a MulticloudLinkQuote with one PriceQuote per side rather than a single figure.

      Beta: the products this models reached general availability in 2026 and their public price lists are incomplete.

      Implementation contract. The default returns Optional.empty(), so a card that does not model native links needs no change. An empty result means the card has no data for the provider pair. A present result may still have one or both sides unpriced: a side is priced only from a figure the card holds, and is otherwise left empty with a reason; callers must check MulticloudLinkQuote.isFullyPriced() before treating the quote as a link price. Cards convert hourly rates to monthly at MulticloudLinkQuote.HOURS_PER_MONTH hours and state the conversion in the side's note. The per-GB charge on the link is a separate lookup: egress(provider, region, EgressPath.MULTICLOUD_INTERCONNECT, term).

      Of the bundled cards: ReferenceRateCard prices only the figures published on the providers' pricing pages (each note carries the source URL and retrieval date) and applies the AWS free tier only when the request opts in; CustomRateCard prices the sides the caller declared; a RateCard.layered(...) chain resolves each side independently, the earliest card that prices a side winning; EquinixRateCard and the provider-API adapters return empty.

      Parameters:
      request - the link to price: both providers and regions, bandwidth in Mbps, the AWS path tier (1-5), the term, and the AWS free-tier opt-in
      Returns:
      the two-sided quote, or Optional.empty() if this card has no data for the provider pair (or request is null)

    • cardName

      default String cardName()
      A short name for this card in provenance trails and unpriced reasons; the simple class name by default.
      Returns:
      the card's name

    • connectionLookup

      default PriceLookup<PriceQuote> connectionLookup(ConnectionType type, int bandwidthMbps, MetroCode metro, Term term)
      connection(ConnectionType, int, MetroCode, Term) with the reason when it cannot be priced. Cards override this to say exactly why (no metro, no live row, no declared rate); the default states that this card holds no figure.
      Parameters:
      type - the connection type; may be null
      bandwidthMbps - the bandwidth in Mbps
      metro - the metro; may be null
      term - the term; may be null
      Returns:
      the figure, or the reason there is none

    • cloudRouterLookup

      default PriceLookup<PriceQuote> cloudRouterLookup(String packageCode, MetroCode metro, Term term)
      cloudRouter(String, MetroCode, Term) with the reason when it cannot be priced.
      Parameters:
      packageCode - the router package; may be null
      metro - the metro; may be null
      term - the term; may be null
      Returns:
      the figure, or the reason there is none

    • egressLookup

      default PriceLookup<EgressRate> egressLookup(CloudProviderType provider, String region, EgressPath path, Term term)
      egress(CloudProviderType, String, EgressPath, Term) with the reason when it cannot be priced.
      Parameters:
      provider - the provider; may be null
      region - the region; may be null
      path - the path; may be null
      term - the term; may be null
      Returns:
      the rate, or the reason there is none

    • colocationLookup

      default PriceLookup<PriceQuote> colocationLookup(ColocationItem item, MetroCode metro, Term term)
      colocation(ColocationItem, MetroCode, Term) with the reason when it cannot be priced.
      Parameters:
      item - the colocation primitive
      metro - the metro; may be null
      term - the term; may be null
      Returns:
      the figure, or the reason there is none

    • source

      PriceSource source()
      The dominant provenance of prices this card produces. Aggregating cards report PriceSource.COMPOSITE.
      Returns:
      the price source

    • layered

      static RateCard layered(RateCard... cards)
      Combines several rate cards into a single card that consults each in order and returns the first non-empty quote. Earlier cards take precedence, so the conventional ordering is most-trusted first: custom -> Equinix live -> reference.
      Parameters:
      cards - the cards to chain, in priority order
      Returns:
      a composing rate card

    • standardChain

      static RateCard standardChain(FabricGateway fabric)
      The canonical egress-capable default chain for the value-realization models: live Equinix Fabric pricing first, then the bundled reference figures (which also supply the cloud-egress rates). This is the default used by the savings calculator, TCO comparison, and plan value realization when no rate card is supplied.
      Parameters:
      fabric - the Fabric client (or any FabricGateway) for live pricing
      Returns:
      a layered rate card: EquinixRateCard -> ReferenceRateCard