Getting Started

Welcome to CouchPOS! Follow these steps to set up your shop:

POS Terminal

Making a Sale

1. Open a POS session (you'll be prompted if one isn't open)
2. Search for products by name, barcode, or equipment compatibility
3. Click a product to add it to the cart, adjust quantity with +/- buttons
4. (Optional) Search and attach a customer — credit balance is shown if any
5. Apply discounts if needed (percentage or fixed amount)
6. Click Pay (F8), select payment method, enter amount
7. Receipt prints automatically and can be shared via WhatsApp

Customer Selection

Type a name or phone in the customer field at the top of the cart. Live results show their credit balance — pick one to attach the sale. The × button reverts to walk-in.

Tax in Cart

If your shop has taxes configured (Settings → Manage Taxes), each tax line appears in the cart totals so the cashier sees the breakdown live before payment.

Defect Sales

Click the Defect Items button in the product area to see items marked as defective. These sell at reduced prices set when the defect was reported.

Offline Mode

If you lose internet, the POS continues working. Sales are queued and automatically synced when connection is restored.

Mall Mode (Scan-to-Add) Pro+

Built for supermarket / mall lanes where the cashier rings 30+ items per checkout. In Mall Mode, scanning a barcode adds the item to the cart instantly — no click required. Normal Mode (the default for every shop) keeps the usual search-and-click flow, which is right for a workshop or small shop where the operator picks items deliberately.

Setting your default mode

There are three places to set the mode, and they apply in this order — most-specific wins:

1. Per-session (the badge in the POS top bar) — flips the mode for the currently open lane only. Cleared when the session closes.
2. Per-location — Settings → Locations → Edit → POS Mode. Pick Normal, Mall, or Inherit shop default. Useful for a multi-location tenant who runs a mall branch and a workshop on the same account — set the mall branch to Mall and the workshop to Normal, then cashiers never have to remember to flip the badge.
3. Shop-wide — Settings → Shop Settings → POS Mode. The fallback every location and session inherits when not set above.

Switching mode mid-session

Click the Normal / Mall badge in the POS top bar to flip the mode for the current session (it mirrors the existing Retail / Wholesale toggle). Useful when one mall has both a fast lane and a service desk on the same database — each lane picks the mode it needs.

How it behaves in Mall Mode

• The product grid is hidden and the scan input is enlarged so it stays in focus.
• Scan a barcode → the item is added immediately. Scan it again → quantity increments by one.
• Type-to-search fallback: if a barcode is damaged or won't scan, just type a few characters of the product name. The grid reappears with matches — click one to add. As soon as you scan again, the grid hides again.
• Unknown barcode → a brief toast ("No product with barcode XXX") appears and the cart is unchanged.
• Out of stock at this location → a toast informs you and the cart is unchanged.

Works alongside Retail / Wholesale

The two toggles are orthogonal. If your shop uses wholesale, both badges (Retail / Wholesale + Normal / Mall) show in the POS top bar at once, and each picks independently.

Hold Sales Pro+

Pause a sale to serve another customer, then resume it later. The cart, customer, discount, and sale mode are all preserved.

1. With items in the cart, click the pause icon in the cart header (or press F4)
2. Optionally tag it with a label (e.g. customer name)
3. The cart clears — you're ready for the next customer
4. Click the collection icon to view held sales — a red badge shows the count
5. Click Resume to load it back, or Discard to remove

Held sales never decrement stock — only completion does.

Retail / Wholesale Mode Pro+

Switch the entire POS terminal between retail and wholesale prices. Only the shop owner can toggle the mode.

• Set Wholesale Price and MOQ (Minimum Order Quantity) on each product
• Owner toggles Retail / Wholesale in the POS top bar
• In wholesale mode: only products with a wholesale price appear; quantities respect MOQ
• The mode is recorded on the sale and shown on the invoice + receipt

Sale Returns

Process partial or full returns against any sale. Stock is automatically restored.

1. Go to Sales → Invoices
2. Click the yellow ↻ icon on the row of the sale being returned
3. Set the return quantity for each item (capped to "Available", which excludes already-returned items)
4. Choose a refund method:
   • Cash — refund as cash from the till
   • Credit Note — reduce the customer's outstanding credit balance (or create store credit if zero)
   • Original Method — back to the original payment instrument
5. Add a reason and click Process Return

If the original sale was on credit, you must use Credit Note. The system tracks all returns under Sale Returns in the sidebar.

Products & Inventory

Adding Products

Go to Products → Add Product. Fill in name, prices (cost / selling / wholesale / MOQ), category, and stock quantity. Barcodes are auto-generated if not provided.

Bulk Import from Excel Pro+

Go to Products → Import Excel. Download the sample template, fill in your products, and upload. The system auto-detects column headers (Name, Quantity, Cost, Selling Price, Wholesale, MOQ, SKU, Expiry Date). Each Excel sheet becomes a product category.

Stock Management

• Stock Adjustments — Manual adjustments for inventory counts, damage, etc.
• Stock Movements — Full audit trail of every stock change (sales, returns, adjustments, transfers)
• Low Stock Alerts — Products below minimum stock level appear on the dashboard

Equipment & Parts Compatibility Pro+

Define equipment (vehicles, machinery, printers, appliances — anything) under Equipment & Parts. When adding a product, select which equipment it's compatible with. Customers can then search by equipment to find matching parts.

Demand Forecast Pro+

The forecast page analyzes historical sales to predict future stock needs and recommend reorder quantities, helping you avoid stockouts.

Stock Transfers Enterprise

Move stock between branches or warehouses. Both stock counts update in one transaction with a full audit trail.

1. Go to Stock Transfers → New Transfer
2. Pick the source and destination locations
3. Search and add products with quantities (capped to what's actually available at source)
4. Add an optional note and submit
5. Stock decrements at source, increments at destination, and two stock movements (transfer_out + transfer_in) are recorded

Add additional locations under Settings → Locations.

Customers & Credit Book

Manage your customer database with contact info, credit limits, and purchase history.

Credit Sales

At POS checkout, choose Credit Sale as payment. The total is added to the customer's outstanding balance.

Credit Book Dashboard

Go to Customers → Credit Book to see every customer with an outstanding balance, days overdue, total receivables, and aging breakdown. Each row has a green $ button to record a payment, and a WhatsApp icon to send a reminder.

Recording a Payment

1. Click the Record Payment button on the customer profile or in the credit book
2. Enter date, amount (capped at the outstanding balance), payment method, and an optional reference / note
3. Click "Pay full balance" to auto-fill the exact amount
4. The system reduces the customer's credit balance and logs the payment in their history

Each customer's profile has a Payment History tab showing every payment received with method, reference, and who recorded it.

Bulk Import Pro+

Import customers from Excel (name, phone, email, address, city, company).

Expense Tracking Pro+

Record day-to-day shop expenses without the complexity of full accounting.

1. Go to Expenses → Record Expense
2. Pick a category (Rent, Utilities, Salaries, Fuel, Supplies, Repairs, Marketing, etc.)
3. Enter date, amount, payment method (cash / card / momo / bank), reference, description
4. Submit — the expense is logged with the user who recorded it

The Expenses dashboard shows totals by date range and a breakdown by category, so you can see where your money goes at a glance.

Suppliers & Purchasing

Purchase Orders

1. Go to Purchase Orders > Create
2. Select supplier, add line items (product, quantity, unit price)
3. Submit the PO
4. When goods arrive, go to the PO and click Receive Goods
5. Stock is automatically updated and an accounting entry is created

Accounting

CouchPOS uses double-entry bookkeeping. Most entries are created automatically from sales and purchases. You can also record manual entries.

Available Reports

• Chart of Accounts — All your accounts with balances. Add custom accounts here.
• Profit & Loss — Revenue vs expenses for any date range.
• Balance Sheet — Assets = Liabilities + Equity as of any date.
• Trial Balance — Verify all debits equal all credits.
• General Ledger — Drill into any account's transactions with running balance.
• Income & Expenses — Simple form to log daily expenses (rent, fuel, utilities) and other income.
• Financial KPIs — Current ratio, debt-to-equity, profit margin, and more.
• Year-End Closing — Transfer net profit to retained earnings at year end.

Recording Daily Expenses

Go to Accounting > Income & Expenses > New Entry. Select Expense or Income, pick a category (Rent, Utilities, Fuel, etc.), enter the amount and date. The system creates the proper journal entry automatically.

Reports & Export

• Sales Report — All sales with date filter. Shows tax collected.
• Inventory Report — Current stock levels and values.
• Financial Report Pro+ — Revenue, COGS, tax collected, and gross profit.

Export

• CSV Export Pro+ — Download report data as CSV.
• PDF Export Enterprise — Generate a printable PDF report.

Taxes

Go to Settings > Manage Taxes to configure your tax rates. Default Ghana taxes are pre-loaded:

• NHIL — 2.5% (on subtotal)
• GETFund — 2.5% (on subtotal)
• COVID-19 Levy — 1% (on subtotal)
• VAT — 15% (compound: on subtotal + levies)

Enable/disable tax in Settings > Shop Settings. Tax breakdown is shown on all receipts.

Defects & Expiry

Reporting a Defect

1. Go to Defects > Report Defect
2. Select the product, quantity, defect type, and reason
3. Optionally set a reduced defect price if it can still be sold
4. Stock is automatically deducted from main inventory
5. Defects with a price appear in the POS under "Defect Items"

Expiry Tracking

When adding or editing a product, check "Expirable Product" and set the expiry date. The Expiry Tracker page shows products expiring in 7, 14, and 30 days, plus already expired items.

Settings

• Shop Settings — Business name, phone, address, currency, tax toggle, receipt footer, SMS alerts.
• Users & Roles — Add staff with specific permissions (cashier, manager, inventory manager, accountant).
• Locations — Multi-location support for stock tracking.
• Language — Switch between English, French, Spanish, and Chinese using the globe icon in the top bar.
• Dark Mode — Toggle the moon/sun icon in the top bar.
• Factory Reset — Erase all shop data (owner only). Preserves your account and settings.

Payment Options & Currency

Manage what payment options appear at your POS and choose your working currency. Available at Settings → Payment Options & Currency.

Country sets the pool

Your country (picked at registration) determines which payment options are available to you. The CouchPOS team curates the gateway and method pool per country — Ghana shops see Paystack / Hubtel / QwickPay / ExpressPay, Nigerian shops see Paystack / OPay / Flutterwave, etc. You pick the subset that you actually want to use.

Sale-time methods All plans

Always available for your POS payment screen:

• Cash, Card, Mobile Money, Bank Transfer, Credit (in-house)

These are tenders — the cashier picks one when ringing up a sale. The actual money movement happens however you've already arranged it (separate card terminal, MoMo prompt, cash drawer). CouchPOS records which method was used.

Online gateways Pro+

Online payment providers like Paystack, Hubtel, Flutterwave, etc. Each shop enters their own merchant credentials — CouchPOS doesn't process or hold the money on your behalf.

1. On the Pro or Enterprise plan, enable a gateway from your country's pool.
2. Click Configure next to the gateway → enter your API keys.
3. Click Visit website (↗) to open the provider's dashboard for your account.
4. The Active toggle controls whether the gateway is operational at checkout — you can keep credentials saved but disable temporarily.

Credentials are encrypted at rest. Even other admins on your account can't read the saved keys; the system only decrypts them at the moment of use.

Working currency Enterprise

By default, your shop runs in your country's local currency (GHS for Ghana, NGN for Nigeria, etc.). On the Enterprise plan you can switch to any currency from the catalog (USD, EUR, GBP, KES, ZAR, and more).

• The selected currency's symbol replaces the default everywhere — POS, reports, accounting, receipts.
• Historical numbers are NOT reconverted. A sale recorded yesterday in GHS still represents that GHS amount; only the displayed symbol flips. Don't use this as a quick-fix for retroactive currency conversion.
• Subscription billing to CouchPOS itself stays in GHS regardless of your working currency.

Support Tickets

Built-in ticketing system to report issues directly to the CouchPOS team. Available to every user on every plan.

1. Click Support in the sidebar
2. Click New Ticket
3. Pick a category (Bug, Feature Request, Billing, Technical, Other) and priority
4. Describe the issue clearly — include what you did, what you expected, and what happened
5. Submit. You'll get a ticket number (TKT-…) and the admin team will respond

Your tickets show a chat-style conversation. Replying to a resolved ticket reopens it. Click Close Ticket when your issue is fully resolved.

Subscription & Plans

Plans at a Glance

Three tiers, paid monthly or yearly. Higher tiers add features; everything from a lower tier carries up.

Payment Methods (for paying CouchPOS)

• Pay Online (Paystack) — Card or mobile money. Subscription activates instantly after payment.
• Manual Payment — MoMo, bank transfer, or cash. Submit your reference and the admin verifies before activation.

Invoices

Go to Settings → Subscription → View Invoices to see and print your subscription payment invoices.

Affiliate Program

Earn commission for every shop that signs up through your referral link.

How it works

1. Sign up at /affiliate/register with your name, email, and payout details (Mobile Money or Bank).
2. You get a unique referral code (e.g. AFF-XXXXXXXX) and a short share link https://www.couchpos.com/r/<your-code>.
3. When someone clicks your link, a 30-day cookie is set in their browser. If they sign up and pay for a plan within that window, you earn commission on their first paid subscription.
4. Default commission rate is 10% of the first paid subscription. Super admins can adjust per-affiliate.
5. Once your balance reaches the minimum payout (default GH₵ 100), request a payout from the affiliate dashboard.

Tracking your earnings

• Dashboard — quick stats, share link, recent referrals, earnings chart.
• Referrals — every shop that signed up with your code, with their current subscription status.
• Commissions — full ledger: pending, approved, reversed.
• Payouts — request payouts and see history (requested, approved, paid, rejected).

Rules

• First payment only — You earn once per referred shop, on their first paid subscription. Renewals don't repeat the commission.
• No self-referral — If the affiliate's email matches the new tenant's email, the referral is ignored.
• Refunds reverse commissions — If a super admin reverses a payment, your commission for it is reversed too.
• Inactive affiliates — A deactivated affiliate's link returns 404; existing earned commissions remain valid.

Keyboard Shortcuts (POS)

API for Developers Pro+

CouchPOS exposes a JSON API for external integrations — mobile apps, custom dashboards, scripts. This walks through one full request cycle: get a token, call an endpoint, handle errors.

1. Quick start

1. Make sure your plan has the api_access feature (Pro or Enterprise).
2. POST /api/auth/login with email + password → receive a JWT bearer token.
3. Send Authorization: Bearer <token> on every /api/v1/* call.
4. Stay under the rate limit: 60 requests / minute per IP.
5. Errors come back as { "error": true, "message": "…" } with standard HTTP status codes.

2. Authentication flow

Tokens are issued per-login. There's no separate API key — your user's email + password gets a JWT scoped to their tenant + role.

Get a token:

curl -X POST https://www.couchpos.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"YourPassword!"}'

Response:

{
  "error": false,
  "message": "Login successful",
  "data": {
    "token": "eyJ0eXAiOiJKV1Qi…",
    "user": { "id": 12, "name": "Owner", "email": "...", "role": "owner" },
    "tenant": { "id": 4, "name": "My Shop", "slug": "my-shop" }
  }
}

The token expires per JWT_EXPIRY (24 hours by default). Re-login to refresh.

Use the token:

curl https://www.couchpos.com/api/v1/products?q=widget \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi…"

3. Available endpoints

Two surfaces:

• /api/v1/* — JWT-authenticated; for external callers; rate-limited; gated by api_access plan feature.
• /api/* (no v1) — session-authenticated; used by the in-app POS browser client. Not designed for external use.

More /api/v1/* endpoints (sales, customers, reports) will land as integrations are demanded. Reach out via Support → New Ticket with your use case.

4. Rate limiting

/api/v1/* endpoints are throttled at 60 requests per minute per IP address. Going over returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": true, "message": "Too many requests. Please try again later." }

The Retry-After header tells you how many seconds to wait. Back off, then retry.

5. Webhooks

CouchPOS receives webhooks from Paystack only. The endpoint is POST /api/paystack/webhook.

• Signature header: X-Paystack-Signature — HMAC SHA-512 of the raw request body using your webhook secret.
• Handled events: charge.success (subscription activation, affiliate commission, receipt email).
• Idempotency: duplicate deliveries are detected via the payment reference; the second call is a no-op and logs the duplicate.
• Acknowledgement: a 200 response means "received" — Paystack will retry on any non-2xx.

6. Plan gating

The login endpoint refuses to issue a token if the tenant's plan lacks api_access. You'll get:

HTTP/1.1 403 Forbidden
{ "error": true, "message": "API access requires a paid plan." }

Upgrade at Settings → Subscription → View Plans.

7. Error format

All errors share the same JSON shape:

{ "error": true, "message": "human-readable description" }

8. Multi-tenant scoping

Every API response is automatically scoped to your tenant. There's no way to read another tenant's data — the JWT carries your tenant id and the query layer enforces it everywhere. Don't bother trying to spoof tenant_id in the body; it's ignored.

FAQ