Skip to main content

Run your storefront

The storefront template includes boxes, a customer vault, sell-backs, shipping, secondary marketplace and P2P trading. This guide sets it up with your own Privy login and card and Abstract USDC box checkout. Marketplace and trade cash settle from the customer's Abstract USDC wallet. Custom box checkouts can accept other crypto too.

Still building? Your own UI can use mock data without a key, or the Read API with a free Read key. This template's live catalog uses Commerce endpoints, so it needs a Commerce key even in demo mode. Read keys cannot call Commerce.

1. Register your app​

Open Create an API key with your DYLI Pro account and choose:

  • Commerce API and a website/storefront.
  • Use your own Privy app for a new storefront.
  • DYLI-hosted checkout and balance for payments.

Enter your company, use case and HTTPS storefront domain. A temporary Vercel URL you control is fine; the site needn't be finished. Update your domains in Commerce setup before launch. Save the Commerce key; it identifies the app automatically.

Create a dedicated Privy app for your storefront and register its allowed domains. Keep its server secret private. You do not need DYLI's Privy app or your own Stripe account.

Already have login? Choose “Use your own login” and connect the client/server adapters. For “DYLI-managed login,” contact us to activate. We set up a separate Privy app for your storefront, not shared DYLI sign-in.

2. Set up the repo​

Use Node 24 or newer:

git clone https://github.com/doyoulikeit/dyli-commerce-example.git
cd dyli-commerce-example
npm ci
cp .env.example .env.local

If you already have .env.local, edit it instead of overwriting it. Add your Commerce key and Privy settings:

DYLI_API_KEY=YOUR_COMMERCE_API_KEY
NEXT_PUBLIC_PRIVY_APP_ID=YOUR_PRIVY_APP_ID
PRIVY_SECRET_KEY=YOUR_PRIVY_SERVER_SECRET
STOREFRONT_ORIGIN=https://your-storefront.example
NEXT_PUBLIC_DEMO_MODE=false

Replace the placeholders. Use the HTTPS origin registered with DYLI and Privy, with no path or trailing slash. Keep the env file out of Git.

No API URLs or slug setting are needed. Commerce calls default to https://www.dyli.io/api/commerce/v1; catalog enrichment uses https://www.dyli.io/api/public/v1. Both use the server-side key.

With NEXT_PUBLIC_DEMO_MODE=false, purchases use real money and inventory, including on localhost. Set it to true to try the interface without making payments; demo mode doesn't use Privy.

3. Check and run​

npm run doctor
npm run dev

Open localhost:3000. The doctor command checks your connection and settings without making purchases. Fix any reported issues before trying checkout.

Allow localhost in Privy to test locally. Card checkout returns to the page you started from, including localhost or 127.0.0.1. Remote return domains must be registered with DYLI. Localhost still uses real production payments and inventory by default.

4. Choose your boxes and fees​

Customize boxes and fees​

Add these optional settings to .env.local or your hosting provider:

INCLUDED_IDS=12997,12998
FLAT_FEE=2
# OR: PERCENT_FEE=5
  • INCLUDED_IDS: show only these boxes. Omit for all boxes permitted by your app.
  • FLAT_FEE=2: add $2 per box. Two $35 boxes: Items $70, Your fee $2 × 2 = $4, total $74 before card processing.
  • PERCENT_FEE=5: alternatively, add 5% of subtotal. Choose one fee setting. Use 0 for no added fee; omit both to inherit saved app fees (zero by default).

Restart locally or redeploy after changing these settings. Keep them server-side. DYLI includes your fee in the card or balance checkout total, so you don't need to collect it separately.

Commerce earnings​

The key owner, not the customer, earns 10% of settled profit: base box sales minus cash buybacks and the cost of items kept, with losses offsetting gains. A bought-back item is not also charged as an item cost. Your fee is separate. Test and unfinished purchases earn nothing.

Creating a Commerce key adds Profile → Storefront → Commerce with orders, quantities, buybacks and earnings. Withdraw available funds through the normal Claim tab. Key rotation preserves history. Accounting and app-wide config →

5. Try the full experience​

For marketplace and trading, choose whether to include DYLI listings and collectors. The example has a configuration command, so you don't need extra credentials or a custom admin screen.

Sign in, open a box, then vault an item or accept a buyback. From the vault, select an eligible item to ship, confirm the address and choose a delivery rate.

Use the launch checklist to test payments, recovery and shipping before inviting customers. The doctor command checks the connection; it doesn't complete those flows for you.