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
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