Dukkan

A shop that AI agents buy from. A seller talks a product into existence in any language; AI writes the listing; agents find it and pay with PayPal.

Comment

Inspiration

Agentic commerce is arriving from the buyer's side. Perplexity, Copilot and ChatGPT can already shop, and PayPal's Agent Ready lets them pay. But every one of those agents needs a merchant with a structured catalogue and a PayPal account behind it, and the merchants being wired up first are the ones who already have Shopify stores.

The people we had in mind are nothing like that. Salma makes cushions at home. She is on a phone, her first language is Arabic, and she is never going to build a website. If the next wave of buyers is AI agents, she has no shop for them to walk into.

Dukkan (Arabic for "small shop") is that shop. It supplies the merchant side of agentic commerce: a one-person store that AI agents can read, search and pay, with PayPal doing the money.

What it does

For the seller. Salma names her shop, picks her language and connects her own PayPal account with Log in with PayPal. To add a product she takes a photo and records a voice note in whatever language she speaks. Gemini transcribes it, Claude writes the English listing, and anything the AI inferred is kept separate under "Added by AI" so she can check it. One question about stock, and the product is in her shop. A seller assistant on the home screen answers questions about her orders and agent searches, in her language, from real data.

For agents. The shop exposes a small public API, described in OpenAPI at /openapi.yaml: search the catalogue, fetch a product, turn a cart into a PayPal order. Every search is logged with the agent's name, so Salma sees what agents wanted, including the things she does not sell yet. Agentic commerce is arriving from the buyer's side. Perplexity, Copilot and ChatGPT can already shop, and PayPal's Agent Ready lets them pay. But every one of those agents needs a merchant with a structured catalogue and a PayPal account behind it, and the merchants being wired up first are the ones who already have Shopify stores.

The people we had in mind are nothing like that. Salma makes cushions at home. She is on a phone, her first language is Arabic, and she is never going to build a website. If the next wave of buyers is AI agents, she has no shop for them to walk into.

Dukkan (Arabic for "small shop") is that shop. It supplies the merchant side of agentic commerce: a onecan read, search and pay, with PayPal doing the money.

What it does

For the seller. Salma names her shop, picks her language and connects her own PayPal account with Logduct she takes a photo and records a voice note in whatever language she speaks. Gemini transcribes it,Claude writes the English listing, and anything the AI inferred is kept separate under "Added by AI" so she can check it. One question about stock, and the product is in her shop. A seller assistant on the home screen answers questions about her orders and agent searches, in her language, from real data.

For agents. The shop exposes a small public API, described in OpenAPI at /openapi.yaml: search the catalogue, fetch a product, turn a cart into a PayPal order. Every search is logged with the agent's name, so Salma sees what agents wanted, including the things she does not sell yet.

For the money. Checkout creates a PayPal order with Salma's account as payee. The agent never pays by itself; it hands the buyer a pay link where the PayPal button does the approval. Capture is idempotent, buyer name and shipping are recorded, stock is decremented, and the order lands on Salma's home screen within seconds. She adds a tra to PayPal. If something goes wrong before shipping, one tap does a full PayPal refund and restocks theitem.

Nothing is mocked. The hosted app runs against the PayPal sandbox, Supabase, Claude and Gemini, and the demo agent at /agent talks to Dukkan only over the same public API any other agent would use.

How we built it

  • Next.js 16 (App Router), TypeScript, Tailwind v4, Motion, hosted on Vercel. The browser never talksI providers directly; everything goes through route handlers.
  • PayPal: the official PayPal Server SDK for Orders v2 (create, capture, tracking) and the Payments API (refunds); the PayPal JS SDK v6 button on the pay page; Log in with PayPal for seller onboarding, so Dukkan never sees a PayPal password.
  • AI: Claude (claude-opus-5-5) writes listings with structured output and runs both agents with tool use, streamed over SSE. Gemini (gemini-3.8-flash) transcribes the voice notes in Arabic, Hebrew or English.
  • Data: Supabase Postgres with row-level security on and only the service role allowed in.
  • The 3D shop on the home screen is pure CSS transforms, no WebGL. The little agents standing outside it are the real count of agents active in the shop.

With the APIMatic Context Plugin for PayPal. The PayPal integration was written in Claude Code with APIMatic's Context Plugin for the PayPal Server SDK loaded. We started on hand-written REST calls and moved the whole integration onto the SDK with the plugin's TypeScript skills guiding client setup, controllers, models and error handling,ture, idempotent re-capture, tracking and refunds in the sandbox. The plugin flagged three SDK defaultsthat would have bitten us in production, which we now override deliberately: the request timeout defaults to never, retries are off by default (we enable them for GET only), and a rejected OAuth token promise is cached for the life of the client, so one failed token fetch would replay on every later call until restart. We would not have found the third one without the plugin pointing us at the SDK source.

Challenges we ran into

  • Digital silence is not silent to a speech model. Gemini invented Arabic sentences from an empty recording even when told not to. We put an RMS meter on the recorder so a silent note never reaches the model.
  • Who can be the seller. The sandbox account that owns the PayPal app cannot use Log in with PayPal as a merchant: it receives a first-party token with no identity, and user info answers 400. The seller has to be a separate sandbox business account. That took a day to understand.
  • Log in with PayPal only returns to an https URL, so the seller connect flow can only be exercised on the hosted app, never on localhost.
  • Idempotency everywhere. Agents retry. Create and capture carry a PayPal-Request-Id, ORDER_ALREADY_CAPTURED is handled by re-reading the order, and refunds are idempotent per capture.
  • Agents write text that the seller's assistant reads. Search queries and agent names come from outsitruncate and strip them before the model sees them, and the model can only propose actions; the sellerconfirms.

Accomplishments that we're proud of

  • The whole loop is real and runs end to end on the hosted app: voice note to published listing, agent search to PayPal order, buyer approval to capture, order on the seller's screen, tracking pushed to PayPal, and a one-tap refund. No part of the demo is staged.
  • A seller who reads no English and has never seen a web form can open a shop that AI agents buy from in about two minutes, and only ever has to confirm what the AI proposes.
  • Payment stays with the human. The agent builds the cart and hands over a link; the buyer approves on PayPal's own button. That boundary answered every trust question we asked ourselves.
  • A public agent API with an OpenAPI spec that any agent, not just our demo one, can use today.
  • Three production-grade PayPal SDK settings caught and fixed before launch rather than after, thanks to building with the APIMatic Context Plugin.

What we learned

The hard part of agentic commerce for a small seller is not the agent, it is the catalogue and the payment rail. Once a voice note can become a structured listing and a PayPal account is the payee, a shop that agents can buy from is a small public API away. We also learned that the seller-facing AI has to be conservative: keep what it inferred visibly separate from what the seller said, and never let it change state on its own.

What's next for Dukkan

Multi-seller hosting, PayPal partner onboarding so refunds and tracking work for any connected seller witegistering the catalogue with PayPal's Store Sync so real shopping agents, not just our demo one, can findSalma's shop.

Built With

Share this project:

Updates

Submission history