https://github.com/mrvdh/picnic-api
Unofficial Node.js wrapper for the API of the Picnic online supermarket. Not affiliated with Picnic.
https://github.com/mrvdh/picnic-api
api online picnic supermarket
Last synced: about 1 month ago
JSON representation
Unofficial Node.js wrapper for the API of the Picnic online supermarket. Not affiliated with Picnic.
- Host: GitHub
- URL: https://github.com/mrvdh/picnic-api
- Owner: MRVDH
- License: mit
- Created: 2021-01-06T18:42:50.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-04-20T10:17:02.000Z (2 months ago)
- Last Synced: 2026-04-20T12:42:46.973Z (2 months ago)
- Topics: api, online, picnic, supermarket
- Language: TypeScript
- Homepage:
- Size: 423 KB
- Stars: 92
- Watchers: 5
- Forks: 16
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Picnic-API
[](https://www.npmjs.org/package/picnic-api) [](https://github.com/MRVDH/picnic-api/blob/master/LICENSE) [](https://picnic.app/nl/vriendenkorting/MAAR3267)
Unofficial Node.js wrapper for the API of the [Picnic](https://picnic.app) online supermarket. Not affiliated with Picnic.
## Installation
```bash
npm install picnic-api
```
## Quick start
Import the package and create a client. All configuration options are optional.
```ts
import PicnicClient from "picnic-api";
const picnicClient = new PicnicClient({
countryCode: "NL", // The country code for the API. Options: "NL" (default), "DE" or "FR".
authKey: "...", // An existing auth key to skip the login step.
apiVersion: "15", // The API version (defaults to "15").
url: "...", // A custom base URL (defaults to https://storefront-prod..picnicinternational.com/api/).
deviceId: "...", // Custom device identifier for x-picnic-did header. (defaults to "3C417201548B2E3B")
agent: "...", // Custom agent string for x-picnic-agent header. (defaults to "30100;1.228.1-15480;")
});
```
### Authentication
Most endpoints require authentication. Call `auth.login()` to obtain an auth key, which is automatically stored in the client and sent with subsequent requests. If you already have a key from a previous session, pass it as `authKey` in the constructor instead.
If the login endpoint responds with a 2FA requirement (`second_factor_authentication_required: true`), then call `auth.generate2FACode("SMS")` to generate a 2FA code and pass it to `auth.verify2FA()` to complete the login process.
```ts
await picnicClient.auth.login("email", "password");
// If 2FA is required:
await picnicClient.auth.generate2FACode("SMS");
await picnicClient.auth.verify2FA("123456");
```
### Usage examples
```ts
// Search for products
const results = await picnicClient.catalog.search("Affligem blond");
// Add a product to the cart
await picnicClient.cart.addProductToCart(11295810, 2);
// Bulk add products to the cart
await picnicClient.cart.addProductsToCart([
{ productId: "s11295810", quantity: 2 },
{ productId: "s10000123", quantity: 1 },
]);
// Get available delivery slots
const slots = await picnicClient.cart.getDeliverySlots();
// Get details of a specific delivery
const delivery = await picnicClient.delivery.getDelivery("delivery-id");
```
### Custom requests
For endpoints not yet covered by a domain service, use `sendRequest` directly:
```ts
await picnicClient.sendRequest("GET", "/unknown/route");
await picnicClient.sendRequest("POST", "/invite/friend", { email: "friend@example.com" });
```
## API reference
The client exposes the following domain services, each grouping a set of related endpoints:
| Service | Accessor | Description |
| --- | --- | --- |
| **App** | `client.app` | Bootstrap data, pages, and deeplink resolution. |
| **Auth** | `client.auth` | Login, logout, 2FA, and phone verification. |
| **Cart** | `client.cart` | Cart management, delivery slots and selling units (recipes, meal plans, selling groups). |
| **Catalog** | `client.catalog` | Product search, suggestions, details, and images. |
| **Consent** | `client.consent` | Consent settings and GDPR declarations. |
| **Content** | `client.content` | Static content pages (FAQ, search empty state). |
| **Customer Service** | `client.customerService` | Contact info, messages, reminders, and parcels. |
| **Delivery** | `client.delivery` | Delivery history, live position, ratings, and invoices. |
| **Payment** | `client.payment` | Payment profile and wallet transactions. |
| **Recipe** | `client.recipe` | Recipe browsing and saving. |
| **User** | `client.user` | User details, profile, suggestions, and push tokens. |
| **User Onboarding** | `client.userOnboarding` | Household/business details and push subscriptions. |
Each service method is fully typed — explore the type definitions under `src/domains//types.ts` for request and response shapes.
## Contributing
Contributions are welcome! Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file for guidelines.
If you enjoy this package, consider using the discount code [MAAR3267](https://picnic.app/nl/vriendenkorting/MAAR3267) so we both get a discount on our next order. 😄