OpenShopy
Przewodnik

Getting started

OpenShopy is a headless commerce back office. You run your own storefront (any framework, any host) and connect it to OpenShopy through the REST API. Everything else — products, orders, payments by bank transfer, invoices, shipping, taxes, customers, discounts, notifications, analytics and audit logs — is managed here.

For AI agents: every page of this documentation is available as raw Markdown. Fetch https://your-openshopy-domain/llms.txt for the index or https://your-openshopy-domain/llms-full.txt for the entire documentation in one file. Each page is also served at https://your-openshopy-domain/api/public/docs/<slug>.md.

1. Get access

Access is invite-only. A store owner or admin creates an invite code in Team → Invite, and you register at https://your-openshopy-domain/auth with that code. The very first account on a fresh installation becomes the platform administrator.

2. Create a store

One account can own or belong to many stores. Each store has its own:

  • base currency (PLN, EUR or USD) and default language (pl or en)
  • products, customers, orders, invoices and settings
  • team members and roles
  • API keys and request logs

New stores are pre-seeded with EU VAT rates, default shipping zones and rates, common carriers (InPost, DPD, DHL, GLS, Poczta Polska, ORLEN Paczka, UPS, FedEx) and Polish/English notification templates.

3. Fill in store settings

Open Settings and complete:

SectionWhy it matters
Company & addressPrinted as the seller on invoices and on the payment page
Bank account (holder, bank, IBAN, SWIFT)Shown to customers on the bank-transfer payment page and inside notification emails
Transfer title templatePayment reference customers put in the transfer title, e.g. Order {order_number}
Payment deadlineDays customers have to pay before an order is flagged overdue
Invoice numberingFormats such as FV/{YYYY}/{MM}/{NNNN}
Storefront URLUsed in links sent to customers
Exchange ratesUsed to display totals in other currencies and to price multi-currency carts

4. Create an API key

Open API keys → Create key. Choose:

  • Secret key (os_sk_…) — server-to-server only. Can read and write everything its scopes allow. Never ship it to a browser.
  • Publishable key (os_pk_…) — safe in browser code. Limited to storefront scopes such as reading the catalog, carts/checkout, customer accounts and analytics events.

The full key is shown once. OpenShopy stores only a SHA-256 hash and the prefix.

5. Make your first request

bash
curl https://your-openshopy-domain/api/public/v1/store \
  -H "Authorization: Bearer os_sk_your_key"
ts
const res = await fetch("https://your-openshopy-domain/api/public/v1/products?limit=20", {
  headers: { Authorization: `Bearer ${process.env.OPENSHOPY_SECRET_KEY}` },
});
const { data, meta } = await res.json();

6. Typical storefront flow

  1. List products and collections (GET /products, GET /collections).
  2. Create a cart and add items (POST /carts, POST /carts/:token/items).
  3. Set the email and shipping address (PATCH /carts/:token). The cart response includes a live quote with shipping_options; save the chosen one with PATCH /carts/:token and shipping_rate_id.
  4. Complete checkout (POST /carts/:token/checkout). The response is the order; payment.page_url is the hosted payment page.
  5. Redirect the customer to payment.page_url. It shows your bank details, amount, transfer title and QR codes.
  6. The customer transfers money and clicks I have paid. Your team gets an alert, checks the bank account and confirms the payment in the dashboard (or via POST /orders/:id/confirm-payment).
  7. Ship the order, add the tracking number, and the customer is notified.

See Bank transfer payments and Carts & checkout for exact request bodies.