Executive Summary: The Beauty API offers the same beauty product catalogue in two forms. The hosted API is a subscription service: your app sends a request, we return one answer, and you may display what you receive and cache it; when the subscription ends, API access, image hosting and data updates stop, and a permanent copy of the whole catalogue is only ever licensed through the Archive. The Complete Archive is a one-time purchase: you download the entire catalogue as files (CSV, JSONL, SQLite and the image archive) and keep it permanently. If you want an always-current data source without hosting anything, choose the API. If you want the whole dataset on your own machines for good, whether for a catalogue, a recommender or a machine learning model, choose the Archive.
Since we launched the hosted REST API alongside the dataset, "which license do I need?" has become the most common question we get before a purchase. The short answer depends on one thing: whether you need to query beauty product data as you go, or hold the entire catalogue yourself. This guide explains the difference between the API and the Complete Archive, what each license allows you to keep, and which one fits your project.
The basic difference: a service you query vs files you download
A dataset is a set of files. When you buy the Complete Archive you download the full catalogue and load it into whatever you like: a spreadsheet, a database, a data pipeline, a training job. Every product and every ingredient is on your disk, and you can read, join, filter and export all of it at once.
An API is a service. The data stays on our servers, and your application asks for what it needs, one request at a time, over HTTPS. Ask "search for niacinamide serums" and you get a page of 20 matches; ask for one product by ID and you get that product's full record; ask for up to 50 products by ID and you get those 50. You never receive the catalogue as a file, and you cannot pull the whole thing down through the API, either technically or under the license. What you get in return is that we host the data, keep it current, and scale it for you.
That single difference drives everything else in this article: what you can keep, how fresh the data is, how you pay, and what fits your project.
What you get with each
Hosted API. A REST API at api.thebeautyapi.com with product search, filtering by category, brand, free-from flags and ingredient, single-product and batch lookups, ingredient records, and barcode lookup on barcode-enabled plans. Every product record includes its full ingredient list in label order, with each ingredient's INCI name, functions and safety ratings, plus a hosted product image. It always serves the newest data release. Plans are billed monthly, with a free Sandbox tier of 100 calls for evaluation and paid plans from $40 a month with 10,000 included calls. Endpoint reference: API documentation.
The Complete Archive. A one-time license to the full catalogue: 180,000 products with label-ordered, INCI-mapped ingredient lists, 22,000 ingredient records with safety data, GTIN barcodes where known, and the 18GB standardized image archive, delivered as CSV, JSONL and SQLite. You receive the release that is current on the day you buy. Details: The Complete Archive.
What you are allowed to keep
This is where the licenses differ most, and it follows directly from the query-vs-download distinction.
With the API, the data you retrieve may be displayed to your users and cached inside your own application. What ends with the subscription is access: the API itself, live image hosting, and every future data update are revoked immediately. A permanent, offline copy of the whole catalogue is licensed only through a dataset purchase, and the Terms of Service prohibit packaging API data as a standalone database, data feed or public API, or using scripts and scrapers to extract data beyond normal application use. If your plan is "pull everything once, cancel, keep it", the API is the wrong product; it is licensed as a service, not as a copy.
Product images come back on every record via image_url and can be cached and served from your own CDN like any other API data; our image hosting ends with the subscription. With the Complete Archive the 18GB image archive is part of the download.
With the Complete Archive, the files and images are yours to keep permanently. You can load them into your systems, build a derived catalogue, train models and serve images from your own infrastructure, with no obligation tied to any ongoing payment. The restrictions are the ones you would expect: no redistributing or reselling the raw files, and no building a competing data product on top of them.
How fresh the data is
The API serves the current release, so new products, corrected ingredient lists and new barcodes appear as soon as a release ships, with no work on your side. The Archive is a snapshot at purchase. Future releases are not automatically included; licensees can request a refresh, billed separately by the volume of updated data points. If your product depends on having this month's launches, the API is the simpler path. If your catalogue is curated and reviewed by hand, a snapshot you control is often preferable, because nothing changes under you without a deliberate refresh. The changelog records what each release changed.
Product IDs are different in the two
The hosted API identifies products and ingredients by UUID (for example 06d9476a-397b-5f61-abc8-640b30a9ae23). The Complete Archive uses sequential integer IDs (1, 2, 3 …) as primary keys in SQLite and as the join key between products, ingredients and product_ingredients. Both are stable within their own product across releases, but there is no public mapping between the two ID spaces, so you cannot join an Archive row to an API record by ID. Pick one as your system of record. If you ever need to reconcile across them, brand plus product name, or a GTIN on barcode-enabled plans, is the practical bridge.
Side by side
| Hosted API | The Complete Archive | |
|---|---|---|
| What it is | A service you query, one request at a time | Files you download, the whole catalogue at once |
| Pricing model | Monthly subscription; free Sandbox tier; paid plans from $40/month | One-time license fee |
| Delivery | REST endpoints, JSON, 20 results per page, batch of up to 50 | CSV, JSONL, SQLite, image archive |
| Data freshness | Always the newest release | Snapshot at purchase; paid refreshes available |
| Cache data in your own application | Yes, while subscribed; access, image hosting and updates stop on cancellation | Yes, permanently |
| Product images | Returned via image_url, cacheable while subscribed | 18GB image archive included |
| Access to the whole catalogue | No | Yes |
| Product IDs | UUID | Integer |
| Barcode lookup | Barcode-enabled plans | product_barcodes table included |
| Train ML models on the data | Not practical, and the license ends with the subscription | Yes, licensed use |
| Refunds | Subscription fees non-refundable, not prorated | All sales final; test with the free sample first |
| Hosting and upkeep | Ours | Yours |
Which one fits your project?
- An app or storefront that shows product and ingredient information on demand: hosted API. Cache what your users look up, serve images from your CDN, and let the subscription handle freshness. Our skincare recommender guide shows the endpoints involved.
- A catalogue that is itself your product, where records must outlive any vendor relationship: Complete Archive. Load the SQLite into your pipeline and keep the integer IDs as your foreign keys.
- Machine learning, analytics or research: Complete Archive. Training and analysis are licensed uses of the dataset, and you need all of it in one place with images.
- Barcode scanning on a budget: a barcode-enabled API plan. Scanned codes resolve to the full product record without you hosting anything.
- Permanence and freshness at the same time: Complete Archive plus periodic refreshes. Mixing Archive rows with API records in one catalogue is impractical in any case, because the two ID spaces do not map to each other and the API has no "new since my snapshot" query.
Frequently asked questions
Is the API the same data as the dataset?
Yes, built from the same source. The API always reflects the newest release; the Archive reflects the release current on your purchase date, so the two diverge as releases ship until you refresh.
Can I download the whole catalogue through the API?
No. The API returns one page or one product per request, a permanent offline copy of the catalogue is licensed only through a dataset purchase, and the Terms prohibit packaging API data as a standalone database or using scrapers beyond normal application use. The Complete Archive exists for that use case.
What happens if I cancel the API?
Your access to the API, to image hosting and to further data updates ends immediately. Your own code, schema, user data and reviews are yours. A permanent copy of the whole catalogue is only licensed through the Complete Archive.
Can I cancel the API and get a refund?
You can cancel at any time, but subscription fees are non-refundable and not prorated for partial months. The free Sandbox plan exists so you can evaluate before paying.
Is there a free way to evaluate before choosing?
Yes, two. The API Sandbox plan gives 100 calls a month at no charge, and the free 1,000-product sample lets you test your pipeline offline against the Archive's file formats.
Where are the exact license terms?
In the Terms of Service, sections 1 (License Grant), 2 (Restrictions), 6 (Payments and Refunds) and 7 (Updates and Refreshes), last updated 29 August 2026. This article summarises them; the Terms govern.
The bottom line
Ask whether you need the whole catalogue or only the products your users touch. If it is the latter, and you want it kept current without hosting anything, the hosted API is cheaper and simpler. If the whole catalogue has to be yours, permanently, with images, for a recommender or a model, the Complete Archive is the license written for that. Still unsure? Tell us what you are building and we will say which one fits.