Store API

This documentation describes the current API surface of a single shop instance. The shop has a public integration API for external systems and a separate internal admin API used by the store panel.

Base URL

Default API base:

https://your-shop.syls.eu/api/v1

Public integration endpoints of the Shop plugin are available under:

/api/v1/shop

Admin panel endpoints are available under /api/v1/shop/admin. They are used by the store panel and are not intended as the stable contract for external integrations.

API Types

The API is split into two use cases:

  • /shop - public API for external integrations, protected with separate store tokens and scopes;
  • /shop/admin - seller and employee panel API, used by the store interface after sign-in.

Authentication

Public API requests use a bearer token:

Authorization: Bearer ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The token can also be passed with:

X-Shop-API-Token: ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are created per integration. A seller can manage them in the store panel when the API key interface is enabled. Technical CLI commands are also available for maintenance:

php bin/shop-api-token list
php bin/shop-api-token create --name="ERP" --scopes=products:read,orders:read,customers:read
php bin/shop-api-token revoke --id=erp

Available scopes:

  • products:read;
  • products:write;
  • orders:read;
  • orders:write;
  • customers:read.

The admin API uses a SYLS Admin session or a SYLS admin API token if the installation has that option enabled.

Response Format

Responses are JSON. A typical success response returns data in a data object:

{
  "data": {
    "status": "ok"
  }
}

Errors should be handled by HTTP status and by the message, detail or title fields, depending on the layer that returned the error.

The OpenAPI contract for the public API is available at:

/api/v1/platform/openapi/shop

Admin State

GET /shop/admin/state

Returns the initial state of the store panel:

  • active package and capabilities;
  • permissions of the signed-in user;
  • team members;
  • settings;
  • operations;
  • compliance;
  • demo data;
  • transfers;
  • dictionaries and UI metadata.

GET /shop/admin/dashboard

Returns dashboard data:

  • order counts;
  • payment and fulfilment statuses;
  • low-stock products;
  • personalization tasks;
  • reviews;
  • basic sales metrics.

Products

GET /shop/admin/products

Returns products for the panel grid. Data includes route, title, SKU, visibility, sales activity, stock, variants, product type and fulfilment partner.

Typical uses:

  • product list in the panel;
  • catalogue filtering;
  • quick stock checks;
  • operational export preparation.

PATCH /shop/admin/products

Updates one product from the grid.

Example payload:

{
  "route": "/produkty/kubki/klasyczne/kubek-0011",
  "enabled": true,
  "visible": true,
  "stock": 24,
  "low_stock_threshold": 5
}

PATCH /shop/admin/products/batch

Updates many products at once. It is used for publishing, hiding, enabling or disabling sales and saving bulk product grid changes.

Inventory

GET /shop/admin/inventory/state

Returns stock for a product or variant.

Parameters:

  • route;
  • sku.

POST /shop/admin/inventory/adjust

Changes product or variant stock. The operation should include a reason or note. The change writes an inventory movement and an audit log entry.

Orders

GET /shop/admin/orders/{orderId}

Returns order details:

  • customer;
  • billing and shipping addresses;
  • items;
  • payment;
  • shipping;
  • documents;
  • fulfilment;
  • personalization;
  • history;
  • tracking;
  • available workflow actions.

POST /shop/admin/orders/{orderId}/actions/{action}

Runs an order workflow action. Available actions depend on status and permissions. Examples:

  • mark as processing;
  • mark as shipped;
  • mark as completed;
  • cancel;
  • mark payment status.

POST /shop/admin/orders/{orderId}/tracking

Stores order tracking.

Example payload:

{
  "tracking_number": "123456789",
  "tracking_url": "https://tracking.example/123456789",
  "carrier": "Carrier",
  "notify_customer": true,
  "mark_shipped": true
}

GET /shop/admin/orders/{orderId}/invoice/{token}

Downloads invoice PDF from private storage.

GET /shop/admin/orders/{orderId}/order-pdf

Generates or downloads order PDF.

GET /shop/admin/orders/{orderId}/wz-pdf

Generates or downloads a warehouse release document.

GET /shop/admin/orders/{orderId}/personalization-files/{token}

Downloads a private personalization file attached to an order.

POST /shop/admin/orders/{orderId}/items/{itemIndex}/personalization-approval

Sends a design for customer approval or stores the next design version. This applies to personalization workflows in the PRO package.

PRO Fulfilment

Fulfilment endpoints support order fulfilment split between partners.

POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/status
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/notes
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/tracking
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/issue
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/notify

Typical fulfilment statuses:

  • waiting;
  • in progress;
  • issue;
  • completed.

PRO Partner Portal

A fulfilment partner sees only assigned fulfilments and required files.

GET  /shop/admin/partner/fulfillments
POST /shop/admin/partner/fulfillments/{fulfillmentId}/status
POST /shop/admin/partner/fulfillments/{fulfillmentId}/tracking
POST /shop/admin/partner/fulfillments/{fulfillmentId}/issue
GET  /shop/admin/partner/fulfillments/{fulfillmentId}/personalization-files/{token}
POST /shop/admin/partner/fulfillments/{fulfillmentId}/items/{itemIndex}/personalization-approval

Team And 2FA

POST   /shop/admin/team
PATCH  /shop/admin/team/{username}
DELETE /shop/admin/team/{username}
PATCH  /shop/admin/security
POST   /shop/admin/security/current-user/setup
POST   /shop/admin/security/current-user/confirm
POST   /shop/admin/security/current-user/disable

Uses:

  • create employee accounts;
  • update role and permissions;
  • remove or deactivate employees;
  • enable and enforce 2FA;
  • configure 2FA for the current user.

Settings

PATCH /shop/admin/settings

Stores shop settings:

  • appearance and storefront;
  • home page;
  • channels and routes;
  • page and e-mail content;
  • shipping;
  • payments;
  • currency;
  • invoices;
  • SEO, sitemap and merchant feed;
  • analytics and cookie consent;
  • product types;
  • manufacturers;
  • fulfilment partners in PRO;
  • safe performance settings.

Uploads

POST /shop/admin/settings/logo
POST /shop/admin/settings/favicon
POST /shop/admin/settings/theme-image
POST /shop/admin/settings/manufacturer-logo

Uploads are intended for the panel. External integrations should not use them without a separate contract.

Compliance

GET /shop/admin/compliance/state

Returns checklists and statuses:

  • SEO;
  • sitemap;
  • schema.org;
  • form labels;
  • ARIA and accessibility;
  • analytics;
  • cookies;
  • rate limiting;
  • audit log.

GROWTH Operations

GET  /shop/admin/operations/state
GET  /shop/admin/operations/report
POST /shop/admin/operations/orders-export
POST /shop/admin/operations/fulfillments-export
POST /shop/admin/operations/data-export
GET  /shop/admin/operations/download/{token}

Report filters:

  • from, to;
  • status;
  • payment_status;
  • fulfillment_status;
  • channel;
  • q.

Exports may include orders, fulfilments or a store data package.

Demo

GET  /shop/admin/demo/state
POST /shop/admin/demo/install
POST /shop/admin/demo/clear

Demo installation adds sample data. Clearing demo should not remove accounts, secrets, payment settings, Mail configuration or real orders.

Channels And Languages

POST   /shop/admin/channels
DELETE /shop/admin/channels/{channelCode}

A language channel can have separate routes, currency, page content and e-mail texts. Channel deletion is blocked when products or dependent data exist.

GROWTH Product Transfers

POST /shop/admin/transfers/template
POST /shop/admin/transfers/export
POST /shop/admin/transfers/upload
POST /shop/admin/transfers/preview
POST /shop/admin/transfers/import
GET  /shop/admin/transfers/{jobId}/download/{token}

Import process:

  1. Download the template.
  2. Fill in products and media.
  3. Upload the file.
  4. Run preview.
  5. Fix validation errors.
  6. Run import only after checking the preview.

Public Feeds

These are not /api/v1 endpoints, but they matter for integrations:

/sitemap.xml
/sitemap-{channel}.xml
/merchant.xml
/merchant-{channel}.xml

Sitemap is for search engines. The merchant feed is for product catalogues and advertising systems.

Public Integration API

The public API is a separate contract for external integrations. It is independent from the panel API and uses tokens per shop and per integration.

Every public request:

  • requires Authorization: Bearer ...;
  • verifies scope;
  • goes through rate limiting;
  • writes an audit log entry;
  • returns only data needed by the integration, without document tokens or panel internals.

Products

GET /api/v1/shop/products
GET /api/v1/shop/products/{sku}
PATCH /api/v1/shop/products/{sku}
GET /api/v1/shop/products/{sku}/inventory
PATCH /api/v1/shop/products/{sku}/inventory

Required scopes:

  • read: products:read;
  • write: products:write.

Use cases:

  • ERP synchronization;
  • stock updates;
  • catalogue download;
  • enabling or disabling sales;
  • publishing or hiding products.

Orders

GET /api/v1/shop/orders
GET /api/v1/shop/orders/{id}
PATCH /api/v1/shop/orders/{id}/status
PATCH /api/v1/shop/orders/{id}/tracking

Required scopes:

  • read: orders:read;
  • status and tracking write: orders:write.

Use cases:

  • downloading new orders to a warehouse system;
  • updating fulfilment status;
  • sending tracking numbers;
  • synchronizing payment references.

Customers

GET /api/v1/shop/customers
GET /api/v1/shop/customers/{id}
GET /api/v1/shop/customers/{id}/orders

Required scopes:

  • customer data: customers:read;
  • customer orders: orders:read.

Use cases:

  • customer reporting;
  • CRM integrations;
  • purchase history.

Outbound Webhooks

Outbound webhooks are not part of the base public API yet. They should remain a separate integration module enabled when a customer needs push notifications instead of periodic polling.

Possible future events:

  • order.created;
  • order.paid;
  • order.shipped;
  • order.canceled;
  • fulfillment.issue;
  • review.created;
  • product.low_stock.

Secure Access Rules

Public API access should be enabled only for specific integrations. The security standard includes:

  • separate token for every integration;
  • limited scopes, for example order read-only access or inventory-only writes;
  • request limits to protect the store from overloaded external systems;
  • audit log showing who used the API and when;
  • token rotation and revocation;
  • no sharing of seller panel accounts with external systems;
  • no public access to private customer files without a controlled token;
  • minimal data returned by each endpoint.