API Overview
This document provides a brief overview of the zDirect API, request basics, and common request elements.
The zDirect API is a RESTful API that covers all phases of the partner integration journey, from initially submitting your products to managing price and stock, all the way through to order fulfillment. For an overview of the process of zDirect Platform integration, including a discussion of which APIs are used at which stages, see Stages of Integration.
For complete Swagger/OpenAPI references for all APIs, see our API Reference.
Base URLs
| Environment | Base URL | Description |
|---|---|---|
| Production | https://api.merchants.zalando.com | Production environment; cannot be accessed by sandbox clients. |
| Sandbox | https://api-sandbox.merchants.zalando.com | Testing environment; accessible to sandbox and production clients. For more information, see Sandbox Testing. |
| GraphQL | http://api.merchants.zalando.com/graphql | Used for GraphQL APIs such as the PSR API. |
zDirect APIs and their Main Uses
| API | Path | Main Uses |
|---|---|---|
| Authentication | /auth | Returns access tokens for zDirect Platform access |
| Products | /merchants/{merchant_id}/products | Used during product submission to check if products already exist in the Zalando Catalog and, if so, to map your product identifiers to their EANs |
| Product Attributes | /merchants/{merchant_id}/outlines /merchants/{merchant_id}/attribute-types |
Returns attribute data necessary for onboarding new products to the Zalando Catalog |
| Product Submissions | /merchants/{merchant_id}/product-submissions | Submits a new product to the Zalando Catalog |
| Prices | /merchants/{merchant_id}/prices | Submits products' regular and promotional prices to be validated and updated |
| Price Reporting | OPTIONAL - /merchants/{merchant_id}/price-attempts | Get validation results of price updates |
| Stocks | /merchants/{merchant_id}/stocks | Sets stock quantities for existing products |
| Offer Blocking | /merchants/{merchant_id}/offer-blocker | Block / unblock product offers |
| Orders | /merchants/{merchant_id}/orders | Reports the status in processing customer orders to Zalando (Partner Fulfillment), or returns order processing status from Zalando (ZFS) |
| Item Quantities (ZFS) | /zfs/item-quantities | Returns quantities of stock at Zalando warehouses |
| Shipping Notices (ZFS) | /zfs/shipping-notices | Creates and updates shipping notices, used to notify Zalando warehouses about partner stock shipments |
| Stock Movements (ZFS) | /zfs/received-items/{merchant_id} | Updates stock information, tracks receive and return processes |
| Stock Movements (ZFS) | /zfs/liquidated-items/{merchant_id} | Returns the liquidated items for a merchant |
| Stock Locations (ZFS) | /zfs/stock-locations | Returns the list of Fulfillment, Return and Inbound Distribution Centers |
| Stock Locations (ZFS) | /zfs/stock-locations/{id} | Returns the details of Fulfillment, Return or Inbound Distribution Center by Stock Location ID |
| Product Status Report | Uses GraphQL Base URL | Get product data per Merchant ID such as status, price, or stock |
| Shipping Documents (ZSS) | /zss/shipping-documents?order_id={zalando_order_uuid} | Get shipping documents (Outbound label, Return label and Delivery Slip) for ZSS orders. |
Common Request Elements
This section highlights frequently-used elements of zDirect API requests.
Access Tokens
The zDirect API uses OAuth 2.0 for authentication. All API requests must include Zalando-issued access tokens in HTTP authentication headers. For more information, see our Authentication Guide.
Merchant Identifier (Merchant ID, BPID)
Many endpoints require your unique Merchant Identifier, also called a Merchant ID or Business Partner ID (BPID).
To view the Merchant ID for any Merchant associated with your Fashion Partner, go to the "Applications" section of the zDirect Portal. Select your app, and scroll down to "Access Control." In the Merchants pulldown menu, you will see each Merchant and its Merchant ID.
To request your Merchant ID programmatically, use the /auth/me endpoint. For a tutorial explaining how to request your Merchant ID, see the Quick Start Guide.
Sales Channels
Sales channels are regions where Zalando products are offered for sale through Zalando Fashion Stores (such as zalando.de, zalando.co.uk). Many zDirect API calls require that you specify the sales channel. For example, if you wish to update a Product price with the Prices API, you must set it for a specific sales channel.
Sales channels must be referred to programmatically by code.
To get a list of your available sales channels and their codes, use the Sales Channels API. For more information, see Sales Channels.
API Request Basics
In normal use, calls are made to the zDirect API by software clients that you create and manage in the zDirect Portal. For more information, see Creating and Managing Apps.
All zDirect APIs support sandbox testing. The sandbox environment is accessed by setting your application to Sandbox Mode in the zDirect Platform and changing the base URL. For more information, see Sandbox Testing.
During setup and development, we strongly recommend sending test requests to the sandbox API using httpie or similar tools. For information on doing so, see Testing with httpie.
Contact Support