Build with Pico

Quickstart

1. 1
   Start the API

   Run the API on http://localhost:8000 and seed it with php artisan migrate --seed.

2. 2
   Open the sandbox

   Use the sandbox or call the widget endpoints directly.

3. 3
   Sign in as a merchant

   Dashboard at http://localhost:3000 with owner@pico.test / password.

The public widget flow uses three calls:

# 1. Fetch widget configuration (public, no auth)
curl http://localhost:8000/api/v1/widget/config/pw_sandbox_demo_widget_001

# 2. Start a shopper session
curl -X POST http://localhost:8000/api/v1/widget/sessions \
  -H "Content-Type: application/json" \
  -d '{"public_widget_id":"pw_sandbox_demo_widget_001","locale":"en"}'

# 3. Send a message
curl -X POST http://localhost:8000/api/v1/widget/sessions/<session_id>/messages \
  -H "Content-Type: application/json" \
  -d '{"message":"Waterproof hiking boots under 150"}'

Embed the widget

<script type="module" src="https://cdn.example.com/pico-widget.js"
  data-public-widget-id="pw_sandbox_demo_widget_001"
  data-api-url="http://localhost:8000/api/v1"></script>

The widget renders inside a Shadow DOM so your site styles can’t break it. Add-to-cart is only shown when the connected store reports the add_to_cart capability.

Sandbox guide

The sandbox is a clearly labeled, non-production environment backed by a mock store with sample outdoor gear.

• Anonymous: enter the demo widget ID pw_sandbox_demo_widget_001 and chat.
• Signed in: the sandbox loads your own sandbox store via GET /sandbox/config.
• Every request and response is shown as JSON so you can see exactly what the API returns.
• Nothing here touches real orders, payments, or production catalogs.

Error format

Every error uses an HTTP status and one consistent JSON body. Always log request_id when reporting an issue.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request could not be validated.",
    "details": { "message": ["The message field is required."] },
    "request_id": "req_01HXYZ..."
  }
}

details details may contain field errors, and never contains secrets or stack traces.

Integration guides

Connect Pico to your commerce platform. Guides cover credentials, sync, and storefront embed.