Pepesto Grocery Shopping API
Pepesto’s API connects recipes and meal plans directly to real supermarket products, so users can add the right ingredients to their cart and check out in just a few clicks. Our product-matching engine ensures every ingredient maps to the best store item.
Who It’s For?
Offer one-tap grocery fulfillment to increase retention and everyday engagement.
Recipe creators & food bloggers can use our separate, lightweight no-code integration to make their recipes shoppable without touching this API. Details are available on our Pepesto Creators page.
If you are looking for permanent access to high-quality licensed recipes, please refer to this section.
Use the /catalog to track prices across supermarkets and countries and build engaging reports.
Why Partner with Pepesto?
Deliver a seamless meal-to-cart journey.
You can increase revenue via referrals - you profit each time your user does shopping.
An easy-to-implement API that starts adding value to your platform right away.
Built, tested, and optimized to drive real conversions for food and grocery platforms.
Setup & Authentication
Pepesto API uses a pay-as-you-go model with pre-paid credits assigned to an API key.
Purchase API credits via Stripe here.note: If you are building a new product and would like to explore our API, reach out to us and describe your use case. Eligible new customers can receive a promo code for 70% discount on first purchase.note: By using the alias field in the payment form, you can create multiple API keys associated with the same Stripe email address.
After the first purchase, get an API key, by making a call to /link endpoint (unauthenticated).
Include your API key in the Authorization header as a Bearer token in all API requests:
curl -X POST https://s.pepesto.com/api/$ENDPOINT \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '$REQUEST_JSON'Endpoints
/parse, /products, and /session separately to create the checkout session.
Then use /checkout to add the items to the basket.You provide recipe URLs, free-form shopping list text, and/or an image via
content_urls, content_text, content_image, and supermarket domain. Pepesto uses these
inputs to build a complete shopping cart.
A redirect_url that will open the Pepesto checkout UI for the given supermarket and
products.
Internally, Pepesto runs the equivalent of /parse, /products, and /session, selecting
the best product for each generic item according to Pepesto’s heuristics (user preferences, price, waste
minimization, quality, etc.).
Then, if the user proceeds to checkout, Pepesto uses /checkout to add the items to the basket.
0.05 € for each input (text, URL, or image).
/oneshot protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/oneshot \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content_urls":["https://www.bbcgoodfood.com/recipes/pizza-margherita-4-easy-steps"],"content_text":"also add milk, bananas, and kitchen towel"}'A recipe provided as free text, a publicly crawlable URL, or an image. Optional fields let you specify locale and whether to generate a shareable image.
Structured recipe data (title, ingredients, nutrition, and more) plus a KgToken that you
can pass to the /products endpoint to build a fully itemized shopping cart with concrete products,
quantities, and images.
Recipe parsing (URL): 0.05 € when recipe_url is set.
Recipe parsing (text): 0.05 € when recipe_text is set.
Image generation: additional 0.05 € when generate_image is true.
Translation: additional 0.05 € when locale is non-English.
/parse protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/parse \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"recipe_url":"https://example.com/recipe","locale":"en-GB","generate_image":true}'You can display the recipes in your app or website without attribution, but the license is only valid for 24 hours.
If you want permanent access to high-quality licensed recipes, please refer to this section.
Explicit user query and optional preferences and constraints for meal planning, such as ingredients to include or avoid, cuisine, dietary tags, time constraints, and number of servings. The endpoint uses these criteria to search Pepesto’s recipe graph.
A list of suggested recipes from Pepesto’s recipe database (1M+ recipes), in the same format returned
by /parse. Each recipe includes rich metadata (title, ingredients, nutrition, instructions,
etc.) and a KgToken that can be passed to the /products endpoint to build a
fully itemized shopping cart.
0.05 € per request.
/suggest protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/suggest \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Find me a vegan pasta recipe"}'One or more recipe KgToken values from the /parse or /suggest endpoints,
an optional manual shopping list as free text, and the target supermarket (e.g. domain or ID). The service
uses these inputs to build a combined cart for all requested recipes.
A fully itemized shopping cart with concrete products, recent prices, quantities, images, and other metadata. Items are merged across recipes to reduce waste and cost, and for each generic ingredient (e.g. “tomatoes”) multiple matching products are returned so the user or client app can choose the best option.
0.01 € per request.
Additional 0.05 € when a manual shopping list is provided as text.
/products protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/products \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"recipe_kg_tokens":["rec123"],"supermarket_domain":"coop.ch"}'A list of concrete products selected from the /products response (each wrapped in a
TokenAndSuggestedQuantity), along with the target supermarket_domain and
user_locale. The list represents the final basket the user intends to purchase.
The session_token for each item is obtained from the /products call.
A shopping session object that encapsulates the user’s final basket for the chosen supermarket,
including a session_id that can be passed to the /checkout endpoint, plus
summary information about the cart.
Base fee (Pepesto): 1.00 € per request.
Plus 0.03 € for each item in the input list.
These amounts can either be paid using your API key credits, or passed on to the end user when you
enable user billing for this endpoint.
Example: a list with 20 items costs 1.00 € + 20 × 0.03 € = 1.60 €
(Pepesto’s fee). When charging the end user, you may optionally add an extra markup amount that is
credited back (after taxes and PSP fees) to your API key as referral revenue.
/session protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/session \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"supermarket_domain":"coop.ch","skus":[{"session_token":"eyJwcm9kdWN0X2lkIjogImh0dHBzOi8vY29vcC5jaC9wYXN0YS8xMjMifQ==","num_units_to_buy":1},{"session_token":"eyJwcm9kdWN0X2lkIjogImh0dHBzOi8vY29vcC5jaC90b21hdG9lcy80NTYifQ==","num_units_to_buy":2}]}'/session)
and repeatedly calls /checkout with that value as
continue_session_id. Each call advances the same session by one
“turn”, optionally including the previous turn’s JS result
(prev_turn_response) and/or a page screenshot.
Each /checkout response returns a
NextCheckoutIterationResponse with exactly one instruction.❗ By following the instructions provided by Pepesto's AI agent, the client app would be able to authenticate the user to the website of the grocery supermarket, and add all necessary products to the shopping cart. However, we do not automate the payment flow - user is still required to verify the shopping cart and checkout manually.
A continue_session_id referencing an existing checkout-driving session, plus optional
prev_turn_response (JavaScript execution result) and screenshot payload from the
previous turn. Each call advances the same session one step further.
A NextCheckoutIterationResponse containing the current session_id, exactly one
instruction to execute (e.g. load_page, await_element, run_js,
prompt_user_action, await_js_out_change, or done), and an optional
attach_screenshot_on_next_turn flag telling the client to send a screenshot on the next call.
Free for sessions that have already been created via Pepesto.
Advancing a checkout session with additional /checkout calls does not incur extra per-request
charges.
/checkout protocol (Go)▶ Show protocol definition
A supermarket_domain identifying the retailer whose catalog you want to fetch (e.g.
"coop.ch"). Optionally, you can also provide a webhook_url that Pepesto will
call whenever the supermarket’s product catalog is re-indexed.
A list of all indexed products for the given supermarket in Pepesto’s database, including names, prices,
images, identifiers, and other metadata required to build storefronts, comparison tools, or custom
experiences. If a webhook_url is provided, Pepesto will also send incremental updates to that
URL each time the catalog is re-indexed.
10.00 € per /catalog request.
/catalog protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/catalog \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"supermarket_domain":"coop.ch"}'This endpoint is used to create an API key by linking it to a previously completed payment.
Expected flow:
- Purchase API credits via Stripe here.
- Get an API key by calling this endpoint and passing the email address you used for the Stripe payment.
- The API key is returned in the response. Note: the API key is returned only once, so make sure to store it safely.
The email address that you used in the payment form. If you used the alias field in the payment form, pass the alias in addition to the email address.
Your API key. Note: the API key is returned only once, so make sure to store it safely.
free
/link protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/link \
\
-H "Content-Type: application/json" \
-d '{"email":"nobody@nobody.com"}'n/a (empty)
free
/credits protocol (Go)▶ Show protocol definition
curl -X POST https://s.pepesto.com/api/credits \
-H "Authorization: Bearer $PEPESTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Live Demo
Want to see Pepesto’s grocery shopping API in action? Explore our interactive demo, try out the
/oneshot endpoint, and inspect real responses in the browser:
Demo.
Supported Supermarkets
Below is an overview of supported supermarkets by country:
Please reach out and contact us if you would like to onboard more supermarkets relevant to your use-case.
Licensed Recipes
Pepesto maintains a growing database of high-quality licensed recipes. These are available via the /suggest API endpoint for serving live traffic. However, the license for recipes retrieved via the /suggest endpoint is only valid for 24 hours.
We also offer permanent licenses to our recipes at €1.50 per recipe. Volume discounts apply.
Permanently licensed recipes include:
- Recipe title
- Detailed cooking instructions
- Full ingredient lists
- Enhanced images generated with state-of-the-art image models
- Nutritional information
- Structured metadata suitable for retrieval and search
Permanently licensed recipes go through an additional round of curation and are typically higher quality than those returned by the /suggest endpoint.
Please contact us if you are interested in purchasing licensed recipes from a particular domain (e.g., keto, Mediterranean, etc.).
Let's Build Together
Your food app or AI agent can go beyond planning — it can shop, too. Pepesto gives you the tools to make that happen across real European supermarkets, with zero infrastructure work
Whether you're building a personal AI assistant, a nutrition platform, or a recipe-based shopping app, Pepesto’s API can bring your user journey full circle — from recipe to real-world checkout.
Start integrating today. We’ll handle the groceries.
Interested in early access or co-developing features? Contact us to become a design partner and enable grocery shopping in your app or agent.
