/ 
WWW-Picnic-0.100
River stage zero No dependents
/ WWW::Picnic

NAME

WWW::Picnic - Library to access Picnic Supermarket API

VERSION

version 0.100

SYNOPSIS

use WWW::Picnic;

my $picnic = WWW::Picnic->new(
    user => 'user@universe.org',
    pass => 'alohahey',
    country => 'de',
);

# Explicit login with 2FA support
my $login = $picnic->login;
if ($login->requires_2fa) {
    $picnic->generate_2fa_code;
    print "Enter SMS code: ";
    my $code = <STDIN>;
    chomp $code;
    $picnic->verify_2fa_code($code);
}

# Search for products
my $results = $picnic->search('apple');

# Get your cart
my $cart = $picnic->get_cart;

# Get available delivery slots
my $slots = $picnic->get_delivery_slots;

DESCRIPTION

WORK IN PROGRESS

This module provides a Perl interface to the Picnic Supermarket API. It handles authentication and provides methods to search for products, manage your cart, and check delivery slots.

Note: The module will eventually get classes for the results. If you use this now, please be aware that the return values will change.

user

Login email address for your Picnic account. Required.

pass

Password for your Picnic account. Required.

client_id

Client identifier for API requests. Defaults to 30100 (Android app).

api_version

Picnic API version number. Must be 15 or higher. Defaults to 15.

country

Two-letter country code for your Picnic account. Supported values are de (Germany) and nl (Netherlands). Defaults to de.

http_agent

LWP::UserAgent instance used for making HTTP requests to the Picnic API. Automatically created with the User-Agent string from "http_agent_name".

http_agent_name

User-Agent string sent with HTTP requests. Defaults to okhttp/3.12.2 to mimic the Picnic mobile app.

picnic_agent

Picnic agent identifier string. Defaults to Android app version.

picnic_did

Picnic device identifier. Auto-generated random hex string if not provided.

login

my $login = $picnic->login;
if ($login->requires_2fa) {
    # Handle 2FA
}

Authenticates with the Picnic API. Returns a WWW::Picnic::Result::Login object that indicates whether two-factor authentication is required.

If 2FA is not required, the auth token is cached automatically.

generate_2fa_code

$picnic->generate_2fa_code;
$picnic->generate_2fa_code('SMS');  # explicit channel

Request a 2FA code to be sent via SMS (default) or another channel. Call this after "login" returns a result requiring 2FA.

verify_2fa_code

$picnic->verify_2fa_code('123456');

Verify the 2FA code received via SMS. On success, the auth token is cached and you can proceed with API calls.

picnic_auth

my $token = $picnic->picnic_auth;

Authenticates with the Picnic API using the provided "user" and "pass". Returns the authentication token (X-Picnic-Auth header value). The token is cached after the first successful authentication.

Note: If 2FA is required, this method will croak. Use "login" instead and handle the 2FA flow manually.

This method is called automatically by "request", so you typically don't need to call it directly.

request

my $result = $picnic->request($method, $path, $data, %params);

Makes an authenticated HTTP request to the Picnic API. Returns the decoded JSON response.

Parameters:

  • $method - HTTP method (GET, POST, PUT, etc.)

  • $path - API endpoint path (relative to api_endpoint)

  • $data - Optional hashref/arrayref to send as JSON body

  • %params - Optional query parameters

This is a low-level method used internally by other methods. You typically won't need to call it directly unless accessing undocumented API endpoints.

get_user

my $user = $picnic->get_user;
say $user->firstname, " ", $user->lastname;

Returns a WWW::Picnic::Result::User object with your account details.

get_cart

my $cart = $picnic->get_cart;
say "Items: ", $cart->total_count;
say "Total: ", $cart->total_price / 100, " EUR";

Returns a WWW::Picnic::Result::Cart object with your shopping cart contents.

clear_cart

my $cart = $picnic->clear_cart;

Removes all items from your shopping cart. Returns the updated WWW::Picnic::Result::Cart object.

get_delivery_slots

my $slots = $picnic->get_delivery_slots;
for my $slot ($slots->available_slots) {
    say $slot->window_start, " - ", $slot->window_end;
}

Returns a WWW::Picnic::Result::DeliverySlots object with available delivery time slots for your current cart.

my $results = $picnic->search('haribo');
for my $item ($results->all_items) {
    say $item->name, " - ", $item->display_price;
}

Search for products by name or term. Returns a WWW::Picnic::Result::Search object containing the results.

get_article

my $article = $picnic->get_article($product_id);
say $article->name;
say $article->description;

Get detailed information about a specific product. Returns a WWW::Picnic::Result::Article object.

add_to_cart

my $cart = $picnic->add_to_cart($product_id);
my $cart = $picnic->add_to_cart($product_id, 3);  # add 3 items

Add a product to your shopping cart. Optionally specify quantity (default: 1). Returns the updated WWW::Picnic::Result::Cart object.

remove_from_cart

my $cart = $picnic->remove_from_cart($product_id);
my $cart = $picnic->remove_from_cart($product_id, 2);  # remove 2 items

Remove a product from your shopping cart. Optionally specify quantity (default: 1). Returns the updated WWW::Picnic::Result::Cart object.

set_delivery_slot

my $cart = $picnic->set_delivery_slot($slot_id);

Select a delivery slot for your order. Returns the updated WWW::Picnic::Result::Cart object.

get_categories

my $categories = $picnic->get_categories;
my $categories = $picnic->get_categories(2);  # with depth

Get product categories. Optionally specify depth for nested categories. Returns raw API response (categories structure varies).

get_suggestions

my $suggestions = $picnic->get_suggestions('app');

Get search suggestions for a partial search term. Returns raw API response.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-picnic/issues.

IRC

You can reach Getty on irc.perl.org for questions and support.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.