@goldenhippo/hippo-shop-types

TypeScript type definitions for the Hippo Shop public API. Zero runtime dependencies — install in your project for IntelliSense and compile-time safety against the live API contract.

New to Hippo Shop? See About this version in the root README for what v4 does and the three things worth knowing before you integrate.

Runtime SDK: @goldenhippo/hippo-shop-sdk

Installation

npm install --save-dev @goldenhippo/hippo-shop-types
# or
pnpm add -D @goldenhippo/hippo-shop-types

Usage

Import the DTOs you need:

import type {
  HippoShopFunnelDTO,
  HippoShopDestinationDTO,
  HippoShopProductDTO,
  HippoShopProductVariantDTO,
  HippoShopProductVariantsByQuantityDTO,
  HippoShopErrorDTO,
} from '@goldenhippo/hippo-shop-types';

Most pages use the SDK's auto-fetching declarative bindings — see @goldenhippo/hippo-shop-sdk. For SSR, edge functions, or custom rendering, call the API directly with a typed fetch:

const res = await fetch(
  'https://api-prod.goldenhippo.io/public/v1/product/multi-vitamin',
  {
    headers: {
      'X-GH-Key': 'gh_pk_yourbrand_xxxxxx',
      'X-GH-Brand': 'Sample Co',
    },
  },
);
const product: HippoShopProductDTO = await res.json();

Three DTOs

| DTO | Route | Scenario | |-----|-------|----------| | HippoShopFunnelDTO | GET /public/v1/funnel/:slugOrId | Render or link a Golden Hippo funnel. | | HippoShopDestinationDTO | GET /public/v1/destination/:slugOrId | Resolve an offer to a funnel + price. | | HippoShopProductDTO | GET /public/v1/product/:slugOrId | Display live pricing and availability. |

Example responses

What the API actually returns. All examples use a fictional product (multi-vitamin) and brand (Sample Co) — substitute your own slugs.

HippoShopFunnelDTO

{
  "id": "a0F0m000002Fnl1EAC",
  "slug": "multi-vitamin-funnel",
  "name": "Daily Multi-Vitamin — Main",
  "active": true,
  "steps": [
    { "id": "a0P0m000002Stp1EAC", "stepNumber": 1, "slug": "vsl", "name": "Video Sales Letter", "kind": "landing" },
    { "id": "a0P0m000002Stp2EAC", "stepNumber": 2, "slug": "checkout", "name": "Order Form", "kind": "order-form" },
    { "id": "a0P0m000002Stp3EAC", "stepNumber": 3, "slug": "discount-bump", "name": "10% Off Bump", "kind": "bump" },
    { "id": "a0P0m000002Stp4EAC", "stepNumber": 4, "slug": "upsell-3mo", "name": "3-Month Upsell", "kind": "upsell" },
    { "id": "a0P0m000002Stp5EAC", "stepNumber": 5, "slug": "thank-you", "name": "Thank You", "kind": "thank-you" }
  ]
}

Both id fields here are Salesforce IDs, and both are required. HippoShopFunnelDTO.id is the funnel's own record id — the value a funnel event carries as funnelSTFId / mainFunnelId, and the reason a page that names its funnel by slug alone can still emit one. HippoShopFunnelStepDTO.id is the step's, carried as funnelSTPId; a consumer matches a step by slug and reads id off it. Prefer slug for anything addressable: these two ids exist to stamp funnel events, not to fetch with.

HippoShopDestinationDTO

{
  "id": "a0D0m000002Dst1EAC",
  "slug": "multi-vitamin-3pack-sub",
  "name": "3-Pack Subscription",
  "description": "3 bottles delivered every 90 days. Cancel anytime.",
  "funnelId": "a0F0m000002Fnl1EAC",
  "funnelSlug": "multi-vitamin-funnel",
  "url": "https://www.example.com/multi-vitamin-3pack-sub",
  "pricing": {
    "familyOrBundleId": "a8r000000000DEF",
    "orderFormId": "01t000000000ABC",
    "sku": "MV-SUB-3",
    "packageQuantity": 3,
    "purchaseType": "subscription",
    "frequency": {
      "interval": 3, "scale": "month",
      "publicInterval": 3, "publicScale": "month",
      "value": "90-day", "label": "Every 90 Days"
    },
    "price": { "amount": 89.95, "currency": "USD", "savings": 30 },
    "rebillPrice": { "amount": 89.95, "currency": "USD", "savings": null },
    "outOfStock": false,
    "restrictedCountryCodes": [],
    "shipping": { "domestic": 0, "international": 12.95, "freeShippingThreshold": null },
    "bumpOffers": [
      {
        "familyOrBundleId": "a8r000000000GHI",
        "orderFormId": "01t000000000JKL",
        "sku": "MV-BUMP-1",
        "productName": "Vitamin D Booster",
        "unitOfMeasure": "Bottle",
        "quantity": 1,
        "price": { "amount": 14.95, "currency": "USD", "savings": 5 },
        "outOfStock": false,
        "restrictedCountryCodes": []
      }
    ],
    "checkoutOverrideUrl": null
  }
}

Four keys on this DTO exist because the SDK cannot derive them:

| Field | Type | What it is | |-------|------|------------| | id | string | Salesforce ID of the destination. | | funnelId | string | Salesforce ID of the funnel this destination resolves to — the same funnel funnelSlug names. | | url | string \| null | Absolute landing URL for the destination. null when Salesforce has none; callers then fall back to their own configured checkout base. | | pricing.checkoutOverrideUrl | string \| null | Per-destination override for the checkout base URL. Takes precedence over the destination's own url and over the brand-level data-checkout-base. null for the normal case — the key is still required. |

Everything else in the public contract is slug-keyed. The first three are the deliberate exception: they carry record identity a page cannot derive from a slug — id is what a funnel-event payload sends as destinationId, out of a destination fetch the page is already making. funnelId names the funnel this destination sends the visitor into; it is not where a funnel event's funnelSTFId / mainFunnelId come from — those come from HippoShopFunnelDTO.id, the funnel the current page view itself belongs to. checkoutOverrideUrl is a different case — it is the first source in the SDK's checkout-base ladder, ahead of url and the brand-level data-checkout-base. All four are required on the DTO — url and checkoutOverrideUrl are nullable, but the keys are always present.

HippoShopProductDTO

The variant tree is the largest part of the product response. Each price-level branch (subscription.standardList, subscription.myAccountList, oneTime.standardList, oneTime.myAccountList) is paired with a …ByQuantity record keyed by stringified quantity for direct lookup.

{
  "id": "p_01ABCDEFGHJK",
  "slug": "multi-vitamin",
  "name": "Daily Multi-Vitamin",
  "packaging": { "singular": "Bottle", "plural": "Bottles" },
  "image": "https://cdn.example.com/products/multi-vitamin.png",
  "reviews": { "count": 1842, "average": 4.6, "globalFiveStarReviews": 12450 },
  "outOfStock": false,
  "variants": {
    "subscription": {
      "standardList": [
        {
          "productId": "p_01ABCDEFGHJK",
          "variantId": "v_01ABCDE001",
          "sku": "MV-SUB-1",
          "price": 34.95,
          "rebillPrice": 34.95,
          "quantity": 1,
          "packageType": "bottle",
          "savings": null,
          "alternatePurchaseTypePrice": 39.95,
          "defaultFrequency": {
            "interval": 1, "scale": "month",
            "publicInterval": 1, "publicScale": "month",
            "value": "30-day", "label": "Every 30 Days"
          }
        },
        {
          "productId": "p_01ABCDEFGHJK",
          "variantId": "v_01ABCDE003",
          "sku": "MV-SUB-3",
          "price": 89.95,
          "rebillPrice": 89.95,
          "quantity": 3,
          "packageType": "bottle",
          "savings": 24.90,
          "alternatePurchaseTypePrice": 104.85,
          "defaultFrequency": {
            "interval": 3, "scale": "month",
            "publicInterval": 3, "publicScale": "month",
            "value": "90-day", "label": "Every 90 Days"
          }
        },
        {
          "productId": "p_01ABCDEFGHJK",
          "variantId": "v_01ABCDE006",
          "sku": "MV-SUB-6",
          "price": 169.95,
          "rebillPrice": 169.95,
          "quantity": 6,
          "packageType": "bottle",
          "savings": 79.75,
          "alternatePurchaseTypePrice": 199.70,
          "defaultFrequency": {
            "interval": 6, "scale": "month",
            "publicInterval": 6, "publicScale": "month",
            "value": "180-day", "label": "Every 180 Days"
          }
        }
      ],
      "standardByQuantity": {
        "1": { /* same shape as standardList[0] */ },
        "3": { /* same shape as standardList[1] */ },
        "6": { /* same shape as standardList[2] */ }
      },
      "myAccountList": [],
      "myAccountByQuantity": {}
    },
    "oneTime": {
      "standardList": [
        {
          "productId": "p_01ABCDEFGHJK",
          "variantId": "v_01ABCDE101",
          "sku": "MV-OT-1",
          "price": 39.95,
          "rebillPrice": null,
          "quantity": 1,
          "packageType": "bottle",
          "savings": null,
          "alternatePurchaseTypePrice": 34.95,
          "defaultFrequency": null
        },
        {
          "productId": "p_01ABCDEFGHJK",
          "variantId": "v_01ABCDE103",
          "sku": "MV-OT-3",
          "price": 104.85,
          "rebillPrice": null,
          "quantity": 3,
          "packageType": "bottle",
          "savings": null,
          "alternatePurchaseTypePrice": 89.95,
          "defaultFrequency": null
        }
      ],
      "standardByQuantity": {
        "1": { /* same shape as standardList[0] */ },
        "3": { /* same shape as standardList[1] */ }
      },
      "myAccountList": [],
      "myAccountByQuantity": {}
    }
  }
}

The /* … */ comments inside the JSON above are illustrative — the real response includes the full object at each entry; they're elided here to keep the example readable. The myAccount tier is empty in this sample because the product isn't enrolled in the My Account tier program; most products show empty arrays and an empty record there.

Versioning

Semver. Major versions track breaking changes to the public API contract. Minor and patch versions are additive only.

No runtime validation

These are types only — no runtime validation. If you need to validate response bodies at the network boundary, use a runtime schema library like Zod or io-ts.

Provenance

Published with SLSA provenance attestation via npm Trusted Publishers + GitHub Actions OIDC.

License

MIT. See LICENSE.