← Back to EcomCentral
SHOPWARE 6 ADMIN API

Shopware 6 Setup Guide

Connect your Shopware 6 shop to EcomCentral using the Admin API with an OAuth2 Integration (client credentials).

Prerequisites

ℹ️ EcomCentral authenticates with the client_credentials grant against /api/oauth/token — a server-to-server flow using an Integration's Access Key ID + Secret Access Key. Tokens are short-lived (~10 min) and refreshed automatically.

Creating an Integration

  1. Log in to the Shopware 6 Administration
  2. Go to Settings → System → Integrations
  3. Click Add integration
  4. Enter a name (e.g. "EcomCentral"). To grant full access enable Administrator, or assign a custom ACL role limited to Orders, Products and Deliveries
  5. Click Save — Shopware reveals the Access Key ID and Secret Access Key once; copy both immediately
  6. In EcomCentral, add a new Shopware 6 connection with:
    base_url = your shop URL  ·  client_id = Access Key ID  ·  client_secret = Secret Access Key
  7. Click ⚡ Test to verify — it confirms auth and returns your product count
⚠️ The Secret Access Key is shown only at creation time. If you lose it, generate a new Integration (or use "Show details" before leaving the page). The key grants API access at the integration's permission level — keep it secret.

Credentials Reference

KeyRequiredDescriptionExample
base_url Required Shop URL (with or without a trailing /api — it's normalized) https://shop.example.com
client_id Required Integration Access Key ID SWIAxxxxxxxx…
client_secret Required Integration Secret Access Key aBcD…
✅ Alternative key names accepted: baseUrl / url for base URL; clientId / access_key for the Access Key ID; clientSecret / secret_key for the Secret Access Key.

API Endpoints Used

OperationMethodEndpoint
AuthenticatePOST/api/oauth/token (client_credentials)
List / detail ordersPOST/api/search/order
List / detail productsPOST/api/search/product
Add tracking codePATCH/api/order-delivery/{id}
Change order statePOST/api/_action/order/{id}/state/{transition}
Update stockPATCH/api/product/{id}
ℹ️ Reads use the Search API (POST /api/search/{entity}) with a body of { page, limit, total-count-mode }, returning { data: [...], total }. Writes are issued by the entity's UUID (resolved from order number / SKU automatically).

Order States

Shopware drives orders through a state machine. EcomCentral exposes the four order states and the transitions between them (process, complete, cancel, reopen).

open
New order, not yet processed
in_progress
Being processed (transition: process)
completed
Fulfilled (transition: complete)
cancelled
Cancelled (transition: cancel)
⚠️ Valid transitions depend on the order's current state — Shopware rejects invalid ones (e.g. you cannot complete an order that hasn't been processed). EcomCentral surfaces the API's error message when a transition isn't allowed.

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Sorted by orderDateTime DESC; exact total count
View order detail✅Billing + shipping address, line items, totals, payment state, tracking codes
Add tracking code✅PATCH the order delivery's trackingCodes
Change order state✅State-machine transition (process / complete / cancel / reopen)
View products (paginated)✅Name, productNumber (SKU), price, stock
Update stock quantity✅Resolves SKU → UUID, then PATCH product stock
Test connection✅OAuth round-trip + product count

Troubleshooting

✕ 401 Unauthorized / invalid_grant

The Access Key ID or Secret Access Key is wrong, or the Integration was deleted. Recreate the Integration under Settings → System → Integrations and update the credentials.

✕ 403 Forbidden on orders/products

The Integration's role lacks permission. Either enable Administrator on the Integration, or grant its ACL role read/write on Orders, Products and Deliveries.

✕ "No delivery found for order"

Tracking codes attach to an order's delivery. Orders that have no delivery yet (e.g. fully digital orders) can't accept a tracking code. Process the order so a delivery exists first.

✕ Transition not allowed

The requested state transition isn't valid from the order's current state. Follow the path open → in_progress → completed; use reopen to return a completed/cancelled order to open.

✕ cURL error / SSL certificate

Your shop must serve a valid HTTPS certificate. Self-signed certs on staging will be rejected. Use a trusted or Let's Encrypt certificate (for dev only you can disable peer verification in Shopware6Client.php).