GraphQL API

The Fontdue GraphQL API is the public read interface to your store. Every font, license, content page, article, and customer-facing setting your site can show is queryable through it, and a single request returns data shaped exactly the way you asked for it. Your site reads from it to render the catalog into your own HTML – the example template fetches every page’s data this way.

Your public endpoint is your site URL with /graphql appended:

https://your-site.fontdue.com/graphql

The viewer root

Queries start from viewer, your store’s public context. The catalog hangs off it – fontCollections, fontPacks, pages, articles, licenses, settings, and a slug lookup for resolving a single collection or pack by its slug. A query names the fields it wants and gets back those and nothing else:

query {
  viewer {
    fontCollections(first: 10) {
      edges {
        node {
          name
          fontStyles {
            name
            sku {
              price {
                amount
                currency
              }
            }
          }
        }
      }
    }
  }
}

This descends from the store, into its collections, into each collection’s styles, down to the price on each style’s SKU – and returns only those fields. If you need a collection’s description and images instead, you ask for those; the request shape and the response shape match. The GraphQL docs cover the query language itself.

Connections and arrays

Some fields, like fontCollections, resolve to a Connection – the edges → node wrapper in the query above. Connections support pagination, which a catalog needs once it grows past a single page: you request a page with arguments like first: 10 and read each item as edge.node.

Other lists resolve to a plain array rather than a connection – viewer.licenses, or a collection’s fontStyles – for lists that aren’t expected to need paging. Those you read directly, with no edges/node indirection. Which fields are connections and which are arrays is visible in the schema.

Font packs

A Font packFont packA hand-picked set of styles or whole families from anywhere in the catalog, sold together at one price with its own licenses, content, and slug. Unlike a bundle, it isn’t tied to one family or superfamily. is its own type, FontPack, separate from FontCollection – it isn’t a collection and never appears in fontCollections. viewer.fontPacks is a connection with the same first/after paging and tags/excludeTags filters as fontCollections; it includes unlisted packs, so a site building its own pack pages sees every pack it sells – check visibility before offering one in a list of your own. viewer.slug(name:) resolves a pack through fontPack, beside fontCollection, page, article, license and designer:

query {
  viewer {
    slug(name: "anniversary-pack") {
      fontPack {
        name
        shortDescription
        sku {
          price {
            amount
            currency
          }
        }
        totalStyles
        totalStylesPrice {
          amount
        }
        members {
          ... on FontStyle {
            name
          }
          ... on FontCollection {
            name
            fontStyles {
              name
            }
          }
        }
      }
    }
  }
}

A pack’s fields follow a collection’s: name, slug, visibility, tags, sku, shortDescription and description (both taking the format argument), images with tags/excludeTags, featureStyle and pageMetadata. A pack has no url/path of its own – its landing page is yours to build, at whatever address you choose. It implements the Licenseable interface, so licenses lists the licenses the pack is sold under – the pack’s own list, not its member families’. A password-protected pack behaves like a protected collection: slug { fontPack } returns a password_protected error until the visitor unlocks it with accessNode.

Two fields describe the contents. members is the ordered list as authored in the admin – a union of FontStyle and FontCollection, so a whole-family member arrives as the collection and a single style as the style. Query it with inline fragments, as above, when rendering the pack’s page, since the two need different treatment. fontStyles is the flattened view: every style in the pack, with families expanded to their current styles and duplicates removed – the list to use when counting or displaying the fonts inside. totalStyles is its length, and totalStylesPrice is the sum of those styles’ individual prices; set against sku.price it gives the saving the pack represents. Both prices accept the same licenseOptions and orderVariables arguments, so the comparison holds under a chosen license.

Sku.product can resolve to a FontPack as well as a style, collection or bundle, so code that switches on a SKU’s product type – reading an order’s items, say – needs a ... on FontPack case.

Previewing hidden content

By default the endpoint returns only what the public can see – a hidden collection is dropped from fontCollections, and fetching its slug resolves to nothing; a hidden pack is dropped from fontPacks the same way. An unlisted collection or pack is still returned, with visibility: UNLISTED, and fontdue-js leaves it out of the Store Modal’s lists. A request authenticated as an admin can reveal hidden collections too, gated by the fontdue-preview request header:

The header only matters in combination with an authenticated admin; an anonymous or customer request stays on the public view no matter what it sends.¹¹The omitted-header default reveals hidden content to a signed-in admin, which is why the GraphQL Playground – and older clients and the script-tag embed, none of which send the header – surface hidden collections to an admin with no extra wiring. A server-rendered build that wants the strict public view on its cacheable pages sends fontdue-preview: false explicitly. Setting it by hand is rarely necessary: Admin preview wires the header and the admin token into a server-rendered site’s fetches for you.

Exploring the schema

The fastest way to see what’s queryable is the GraphQL Playground built into the admin – an interactive editor running against your own store, with the full schema browsable alongside. Draft and verify a query there, then wire it into your site with typed fetching.