Home

BareCommerceCore Guides

Welcome to BareCommerceCore — a headless e-commerce backend built for developers.

What is BareCommerce?

BareCommerce is unique: instead of handling payments directly, it integrates with your payment provider (Stripe, PayPal, Square). When customers pay, your payment provider sends a webhook to BareCommerce, and BareCommerce automatically creates orders.

Key principles:

  • Payment provider is source of truth — All payment data comes from Stripe/PayPal/Square
  • Webhook-driven — Orders are created automatically from payment events
  • API-first — Read orders and manage inventory via REST API
  • No order creation API — Orders can only be created via webhooks from payments
  • Stateless — You control the frontend; BareCommerce manages the backend

This architecture ensures payments and orders are always consistent.

Quick Start

1. Set Up Your Store

2. Choose a Payment Provider

  • Stripe — Best for developers
  • PayPal — Best for international
  • Square — Best for retail + online

3. Integrate Payments

4. Manage Orders

Core Concepts

Payment-First Architecture

Traditional e-commerce:

Create order (pending) → Process payment → Update order to paid

BareCommerce:

Process payment → Provider sends webhook → Create order (already paid)

Why? No race conditions, no abandoned unpaid orders, always consistent.

How Orders Are Created

  1. Customer adds items to cart
  2. Your frontend creates a PaymentIntent with order data as metadata
  3. Customer submits payment info
  4. Payment provider (Stripe/PayPal/Square) processes payment
  5. Provider sends webhook to BareCommerce with order metadata
  6. ✅ BareCommerce creates order automatically (status = paid)
  7. Order is available via GET API

No manual API calls needed to create orders!

Reading Orders

Once orders exist, you can query them:

# List all orders
GET /stores/{storeId}/orders
 
# Get specific order
GET /stores/{storeId}/orders/{orderId}
 
# Filter by status
GET /stores/{storeId}/orders?status=paid
 
# Filter by customer
GET /stores/{storeId}/orders?customerId=cust_123

Orders are read-only (you can't POST or PUT them—they're created from webhooks).

Popular Integrations

Stripe

  • Best for: Developers, SaaS, subscriptions
  • Setup time: 10 minutes
  • Guide: Stripe Integration

PayPal

  • Best for: International, consumer trust
  • Setup time: 10 minutes
  • Guide: PayPal Integration

Square

  • Best for: Retail + online, POS integration
  • Setup time: 10 minutes
  • Guide: Square Integration

Documentation

Getting Started

Payments

API Reference

Advanced

Frequently Asked Questions

Q: Can I create orders via API?

A: No. Orders are created automatically when webhooks arrive from payment providers. This ensures orders and payments are always consistent.

Q: Can I update orders via API?

A: No. Orders are read-only after creation. Their status is determined by the payment provider's webhook data.

Q: What if payment processing fails?

A: The payment provider will send a payment_failed webhook. You can log this and notify the customer to retry.

Q: Can I use BareCommerce without a payment provider?

A: Not currently. Orders must be created from payment webhooks. If you want to test, use Stripe's test mode or test cards.

Q: How do I handle refunds?

A: Refunds come from your payment provider (Stripe, PayPal, Square). When you issue a refund in their dashboard, they send a webhook to BareCommerce, and the order status updates to refunded.

Q: What about inventory management?

A: BareCommerce tracks inventory per product (stock, allowBackorder). You can read product inventory via API.

Architecture Overview

┌─────────────────────────────────────────────┐
│ Your Frontend Application                   │
│ (React, Vue, Next.js, etc.)                │
└────────────┬────────────────────────────────┘
             │
             │ 1. Collect order data
             ↓
┌─────────────────────────────────────────────┐
│ Your Backend / BFF                          │
│ (Node, Python, etc.)                       │
└────────────┬────────────────────────────────┘
             │
             │ 2. Create PaymentIntent
             │    (with order metadata)
             ↓
┌─────────────────────────────────────────────┐
│ Payment Provider                            │
│ (Stripe / PayPal / Square)                 │
└────────────┬────────────────────────────────┘
             │
             │ 3. Process payment
             │
             │ 4. Send webhook
             ↓
┌─────────────────────────────────────────────┐
│ BareCommerce                                │
│ (Webhook ingestion)                         │
└────────────┬────────────────────────────────┘
             │
             │ 5. Create order
             │    (extract data from webhook)
             ↓
┌─────────────────────────────────────────────┐
│ BareCommerce Database                       │
│ (Orders, products, customers)              │
└─────────────────────────────────────────────┘

Environment Setup

All guides assume you have these environment variables set:

# Your payment provider keys
STRIPE_SECRET_KEY=sk_live_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
PAYPAL_CLIENT_ID=xxxxx
SQUARE_ACCESS_TOKEN=xxxxx
 
# For local development
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxxxx

Support & Community

Getting Help

  1. Check the docs — Most questions are answered in the guides
  2. See examples — Each payment guide has complete code samples
  3. Test locally — Use test cards to verify your integration
  4. Ask on Discord — Real developers helping real developers

Ready to get started? → Quick Start Guide

Getting Started