Skip to main content
Responses are private to your account. Cache them only for as long as the windows below allow. Where the endpoint supports it, the response also includes an ETag tied to your account.

Catalogue data

Fragrances, brands, perfumers, notes, and accords, including list and batch endpoints, can be cached for as long as your plan allows: Image links are for showing images in your app or site, not for downloading or storing them on a server. The only exception is an Enterprise Embedded Data License. Use each link exactly as returned, including its exp and sig parameters, and load it in a page or app view. A signed link looks like this:
Each link expires when your plan’s catalogue window above ends (on Enterprise, the window in your contract, or 30 days if it does not say). To keep showing an image, fetch the record again and use the new link. Links stay the same for every call made on the same UTC day, so browsers can cache the images. Embeds on your own pages keep working until the link expires.

Data that changes often

These windows are the same on every plan: When a cached response reaches the end of its window, delete it or revalidate it.

Revalidating with an ETag

Send the ETag you saved in an If-None-Match header. If nothing changed, you get 304 Not Modified with no body, at half the list price. If the 304 is paid from your prepaid balance, your plan’s discount applies on top: 55% off on Starter, 65% on Growth, and 75% on Scale. The total discount never goes above 90%. Search is not eligible for a 304.

Keeping data longer

On self-serve plans, cache only within these windows. You can keep bare id and slug values in your own records for as long as you like. Keeping catalogue data permanently, for example to seed your own product database or run your own search over Noteboxd fields, needs an Enterprise Embedded Data License. Email api@noteboxd.com.