Guide for AI agents

This page is written for AI coding agents (Lovable, Cursor, Claude, ChatGPT, Copilot…) that build a storefront or integration on top of OpenShopy.

Machine-readable entry points

Every documentation page also has Copy as Markdown and Copy for AI buttons.

Rules to follow

1. Base URL is https://your-openshopy-domain/api/public/v1. All requests and responses are JSON.
2. Authenticate with Authorization: Bearer <key>. Use the secret key (os_sk_…) only on a server; use the publishable key (os_pk_…) in browser code.
3. Money is integer minor units. 12999 with PLN means 129.99 zł. Never send floats.
4. Responses are { "data": … } with optional meta for pagination; errors are { "error": { "code", "message", "details"? } }.
5. Pagination: ?page= (from 1) and ?limit= (default 25, max 100); read meta.total and meta.total_pages.
6. Respect rate limits: on 429, wait for Retry-After seconds.
7. Do not build payment-provider integrations. Payment is bank transfer: after checkout redirect the customer to payment.page_url from the order (or render the bank details from GET /store yourself and call POST /payments/:token/mark-sent when the customer says they paid).
8. Do not calculate prices, taxes, shipping or discounts on the client. Use the cart endpoints; they return authoritative totals.
9. Customer accounts use /customer-auth/* endpoints and an opaque customer token sent as X-Customer-Token.
10. Images: pass images: [{ url, alt }] when creating a product, or upload a file (multipart/form-data, field file) or a URL to POST /products/:id/images. Returned image URLs are public and cacheable.
11. Retries are not deduplicated. There is no idempotency key support; before retrying a failed POST, check whether the resource was created.

Prompt you can paste into your agent

Build a storefront for my shop using the OpenShopy API.
Read the full documentation first: https://your-openshopy-domain/llms-full.txt
- Use the publishable key in the browser and the secret key only in server code.
- Money values are integers in minor units.
- Use carts + checkout endpoints, then redirect to the order's payment.page_url for bank transfer payment.
- Send analytics events (page_view, product_view, add_to_cart, checkout_started, purchase).
- Implement customer accounts (register, login, password reset, order history) with /customer-auth.

Typical integration checklist

• Catalog pages: GET /products, GET /products/:idOrSlug, GET /collections
• Cart drawer: POST /carts, POST /carts/:token/items, DELETE /carts/:token/items/:variantId, PATCH /carts/:token (to change quantities send the full items array)
• Checkout: PATCH /carts/:token with email + address → pick from quote.shipping_options → PATCH shipping_rate_id → POST /carts/:token/checkout
• Order confirmation page that links to payment.page_url
• Customer account area: register, login, reset password, orders, addresses
• Order tracking page: GET /orders/track?number=&email=, GET /customer-auth/me/orders/:id or the hosted payment page
• Analytics events
• Back-office sync jobs (server only): products, stock, orders, shipments