Class CustomRateCard

java.lang.Object
com.eqixiac.equinix.design.value.ratecard.CustomRateCard
All Implemented Interfaces:
RateCard
public final class CustomRateCard extends Object implements RateCard
A RateCard whose prices are supplied by the caller - e.g. negotiated contract rates - instead of published list pricing or built-in heuristics. It is constructed fluently, mirroring how workloads, sites, and constraints are declared elsewhere in the design API: 
CustomRateCard rates = CustomRateCard.builder()
    .currency("USD")
    .connectionRate(ConnectionType.EVPL_VC, 1_000, new BigDecimal("250.00"))
    .connectionRate(ConnectionType.EVPL_VC, 10_000, new BigDecimal("1800.00"), new BigDecimal("500.00"))
    // a metro- and term-specific override (e.g. a negotiated Singapore 36-month rate):
    .connectionRate(ConnectionType.EVPL_VC, 10_000, MetroCode.SG, Term.MONTH_36,
                    new BigDecimal("1600.00"), new BigDecimal("0.00"))
    .cloudRouterRate("STANDARD", new BigDecimal("285.00"))
    .defaultConnectionRate(new BigDecimal("400.00"))   // fallback for unlisted bandwidths
    .build();

Granularity & resolution order

Rates may be declared at several levels of specificity - with or without a metro, a term, and (for connections) a concrete type. A lookup for a given (type, bandwidth, metro, term) resolves to the most specific declared entry, trying in order:

  1. exact metro and term;
  2. exact metro, any term;
  3. any metro, exact term;
  4. any metro, any term (the metro/term-agnostic connectionRate(type, bandwidth, ...) entry);
  5. a type-agnostic entry (declared with a null type, meaning "any connection type"), probed at the same four levels of metro/term specificity;
  6. the declared default, otherwise Optional.empty() so a layered card can defer.

Cloud-router rates resolve the same way over (packageCode, metro, term), and colocation rates over (item, metro, term). Egress rates are keyed by provider + path only - the region and term lookup parameters are ignored on this card. Declaring the same key twice is last-declaration-wins: the later call silently replaces the earlier rate. Every quote this card returns is tagged PriceSource.CUSTOM.

Beta. multicloudLinkRate(...) and multicloudLinkHourlyRate(...) declare what one provider charges for its side of a native provider-to-provider link, keyed by (provider, bandwidthMbps, pathTier). Bandwidth matches exactly. A lookup tries the entry for the requested path tier, then the tier-agnostic entry. Region, peer provider and term are not axes on this card. A side with no declared entry is left empty, so a layered chain can take it from a later card. The card does not model the AWS free tier: declare a zero rate for the covered size to express it; a request that opts in to the free tier while this card prices the AWS side gets the declared rate and a quote note saying the tier was not applied. The per-GB charge on the link is declared separately with egressRate(provider, EgressPath.MULTICLOUD_INTERCONNECT, perGb); without it, a card used on its own leaves the link's data-transfer cost unknown and the engines report the native path as partially priced.

  • Method Details

    • builder

      public static CustomRateCard.Builder builder()
      Starts a new custom rate card.
      Returns:
      a fresh CustomRateCard.Builder (currency defaults to USD)

    • connection

      public Optional<PriceQuote> connection(ConnectionType type, int bandwidthMbps, MetroCode metro, Term term)
      Description copied from interface: RateCard
      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.

      Specified by:
      connection in interface RateCard
      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

      public Optional<PriceQuote> cloudRouter(String packageCode, MetroCode metro, Term term)
      Description copied from interface: RateCard
      Resolves the price of a single Fabric Cloud Router instance.

      Implementation contract. As with RateCard.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.

      Specified by:
      cloudRouter in interface RateCard
      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

      public Optional<EgressRate> egress(CloudProviderType provider, String region, EgressPath path, Term term)
      Description copied from interface: RateCard
      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.

      Specified by:
      egress in interface RateCard
      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

      public Optional<PriceQuote> colocation(ColocationItem item, MetroCode metro, Term term)
      Description copied from interface: RateCard
      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.
      Specified by:
      colocation in interface RateCard
      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

      public 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.

      Beta. Prices each side from the declared multicloudLinkRate(...) / multicloudLinkHourlyRate(...) entries: exact bandwidth, the requested path tier first, then the tier-agnostic entry. Returns empty when neither side has an entry. The request's region and term are ignored. The free-tier flag does not change the price: when it is set and this card prices the AWS side, the quote carries a note saying the declared rate applies and the free tier was not modelled, so a caller who opted in is not left to assume it was applied.

      Specified by:
      multicloudLink in interface RateCard
      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)

    • currencyCode

      public String currencyCode()
      The ISO 4217 code every amount on this card is in.
      Returns:
      the card's currency code

    • connectionLookup

      public PriceLookup<PriceQuote> connectionLookup(ConnectionType type, int bandwidthMbps, MetroCode metro, Term term)
      Description copied from interface: RateCard
      RateCard.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.
      Specified by:
      connectionLookup in interface RateCard
      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

      public PriceLookup<PriceQuote> cloudRouterLookup(String packageCode, MetroCode metro, Term term)
      Description copied from interface: RateCard
      RateCard.cloudRouter(String, MetroCode, Term) with the reason when it cannot be priced.
      Specified by:
      cloudRouterLookup in interface RateCard
      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

      public PriceLookup<EgressRate> egressLookup(CloudProviderType provider, String region, EgressPath path, Term term)
      Description copied from interface: RateCard
      RateCard.egress(CloudProviderType, String, EgressPath, Term) with the reason when it cannot be priced.
      Specified by:
      egressLookup in interface RateCard
      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

      public PriceLookup<PriceQuote> colocationLookup(ColocationItem item, MetroCode metro, Term term)
      Description copied from interface: RateCard
      RateCard.colocation(ColocationItem, MetroCode, Term) with the reason when it cannot be priced.
      Specified by:
      colocationLookup in interface RateCard
      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

      public PriceSource source()
      Description copied from interface: RateCard
      The dominant provenance of prices this card produces. Aggregating cards report PriceSource.COMPOSITE.
      Specified by:
      source in interface RateCard
      Returns:
      the price source