Zalando Adapter
NexusCommerce integration with the Zalando Partner API for fashion and lifestyle selling across Europe.
Overview
The Zalando adapter connects NexusCommerce to the Zalando Partner API, enabling fashion and lifestyle brands to manage their Zalando ZFS (Zalando Fulfillment Solutions) and zSeller catalog, sync orders, and update inventory across Zalando's European marketplace network.
Zalando operates in 25 European markets. Access to the Partner API requires approval from Zalando's partner onboarding team. The adapter targets the Zalando Partner API v1 and uses OAuth 2.0 client credentials for authentication.
Key Concepts
Partner Program — Zalando operates two seller programs:
- zSeller (Partner Program) — You ship directly to customers. You manage your own logistics.
- ZFS (Zalando Fulfillment Solutions) — Zalando warehouses and ships your products. Similar to Amazon FBA.
NexusCommerce supports both programs. ZFS inventory is read-only from the API.
Article — Zalando's term for a product variant (combination of product + size + color). Each article has a unique articleId assigned by Zalando. Your EAN maps to a Zalando article.
Simple Article vs. Configurable Article — Simple articles have no variations. Configurable articles are the parent product grouping size variants (e.g., T-shirt in S/M/L/XL). NexusCommerce creates configurable articles for products with size/color variants.
Silhouette — Zalando's category taxonomy term. Products must be mapped to a valid silhouette (e.g., SHIRT, TROUSERS, SNEAKERS). Incorrect silhouette mapping causes article rejection.
Getting Started
Prerequisites
- Active Zalando partner account (zSeller or ZFS)
- API credentials issued by Zalando's partner onboarding team
- Products with valid EANs for all size variants
- Zalando-compliant product images (minimum 762 × 1100 px, white background)
Required Credentials
| Field | Description |
|---|---|
| Client ID | OAuth 2.0 client ID issued by Zalando |
| Client Secret | OAuth 2.0 client secret issued by Zalando |
| Partner ID | Your Zalando partner identifier |
Contact your Zalando partner manager to obtain API credentials. Self-service credential generation is not available.
Authentication
The adapter uses the OAuth 2.0 client credentials flow against Zalando's authorization server:
POST https://auth.zalando.com/oauth2/access_token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<client_id>
&client_secret=<client_secret>
&realm=servicesAccess tokens expire after 1 hour. The adapter refreshes automatically before expiry.
API Base URL
Zalando's Partner API is environment-specific:
| Environment | Base URL |
|---|---|
| Production | https://api.merchants.zalando.com |
| Sandbox | https://sandbox.api.merchants.zalando.com |
Set the environment in the connection config. Use the sandbox for initial integration testing.
Synced Data
| Data Type | Direction | Zalando API Endpoint | Notes |
|---|---|---|---|
| Articles (Products) | Read / Write | /articles | Configurable and simple articles |
| Article Images | Write | /articles/{id}/images | Zalando-compliant image upload |
| Inventory (zSeller) | Read / Write | /inventory | Seller-managed stock levels |
| Inventory (ZFS) | Read | /zfs/inventory | ZFS warehouse stock (read-only) |
| Orders | Read | /orders | All order statuses |
| Shipment Labels | Read | /orders/{id}/shipment-labels | Pre-paid return labels for zSeller |
| Shipment Confirmation | Write | /orders/{id}/shipments | Required for zSeller order completion |
| Returns | Read | /returns | Return requests and items |
| Price | Write | /prices | Regular and sale prices per article |
Configuration Options
| Key | Type | Default | Description |
|---|---|---|---|
partner_id | string | required | Zalando partner identifier |
environment | string | production | production or sandbox |
fulfillment_type | string | zSeller | zSeller or ZFS |
sync_interval_minutes | integer | 60 | Polling frequency |
order_lookback_days | integer | 30 | Historical order window |
default_silhouette | string | — | Fallback silhouette if not mapped per product |
price_sync_enabled | boolean | true | Push price updates to Zalando |
image_sync_enabled | boolean | true | Upload product images to Zalando CDN |
Supported Features
| Feature | Supported | Notes |
|---|---|---|
| Article creation | Yes | Simple and configurable articles |
| Image upload | Yes | Zalando CDN upload with compliance check |
| Inventory sync (zSeller) | Yes | Per-EAN stock levels |
| Inventory sync (ZFS) | Partial | Read-only |
| Order sync | Yes | Polling only |
| Shipment confirmation | Yes | Required for zSeller |
| Return management | Yes | View and process returns |
| Pricing updates | Yes | Including sale prices |
| Silhouette mapping | Yes | Via product attribute mapping |
| Webhooks | No | Polling only |
| Zalando Plus pricing | No | Managed by Zalando |
| Multi-market pricing | No | Single price applies across all markets |
Zalando-Specific Product Requirements
Zalando enforces strict content standards. Products that fail validation are rejected and do not appear in the catalog.
Required product attributes:
| Attribute | Notes |
|---|---|
| EAN | One per size variant; must be a valid EAN-13 |
| Silhouette | Must match a valid Zalando silhouette code |
| Brand | Must be an approved brand in your partner account |
| Gender target | MALE, FEMALE, UNISEX, or KIDS |
| Age group | ADULT or KIDS |
| Color | From Zalando's approved color list |
| Season | SS (Spring/Summer) or AW (Autumn/Winter) + year |
NexusCommerce maps your product attributes to Zalando's taxonomy via the attribute mapping tool in Settings > Marketplace > Zalando.
Rate Limits & Quotas
Zalando does not publish official rate limits but enforces fair-use policies. Observed limits in practice:
| Operation | Safe Rate |
|---|---|
| Article reads | 10 req/s |
| Article writes | 2 req/s |
| Inventory updates | 5 req/s |
| Order reads | 5 req/s |
The adapter uses conservative rates and applies exponential backoff on 429 responses. For bulk article creation, NexusCommerce batches requests to 50 articles per minute.
Troubleshooting
Articles rejected with VALIDATION_ERROR
Check the article response body for the validationErrors array. Common causes: invalid EAN, unrecognized silhouette, missing required attribute, image dimensions not meeting Zalando's specification (minimum 762 × 1100 px, white or light gray background).
403 Forbidden on all requests
The Partner ID in the connection config does not match the partner associated with the OAuth credentials. Verify both values with your Zalando partner manager.
Inventory not updating on Zalando
ZFS inventory is managed by Zalando and cannot be updated via API. For zSeller accounts, ensure the fulfillment_type config is set to zSeller. Inventory updates for ZFS articles will return a METHOD_NOT_ALLOWED error.
Orders not appearing after a certain date
Zalando's order API returns orders from the last 90 days by default. Increase order_lookback_days to retrieve older orders, but be aware that Zalando may not return orders beyond 180 days.
Images not appearing on product page
Zalando processes uploaded images asynchronously. Allow up to 24 hours for images to appear on the live catalog. Check the image upload response for processingStatus — a status of REJECTED indicates a compliance issue with the image.