Try Live
Add Docs
Rankings
Pricing
Docs
Install
Theme
Install
Docs
Pricing
More...
More...
Try Live
Rankings
Enterprise
Create API Key
Add Docs
Spryker
https://github.com/spryker/spryker-docs
Admin
Spryker is a composable commerce platform that provides a flexible and scalable foundation for
...
Tokens:
2,790,068
Snippets:
16,111
Trust Score:
8
Update:
1 month ago
Context
Skills
Chat
Benchmark
62.2
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# Spryker Commerce OS Documentation Spryker Commerce OS is a modular, enterprise-grade e-commerce platform designed for B2B, B2C, and marketplace scenarios. The platform provides comprehensive APIs for building headless commerce experiences, integrating with enterprise systems (ERP, CRM, PIM), and enabling omnichannel retail strategies. The documentation covers two primary API applications: the Storefront API for customer-facing touchpoints and the Backend API for administrative operations and system-to-system integrations. The platform follows a modular architecture with Product Business Components (PBCs) that can be installed and configured independently. Key capabilities include cart management, checkout workflows, order management with state machines, product information management, pricing, inventory, and marketplace features. The APIs follow JSON:API conventions for the Storefront API and support flexible conventions for the Backend API, enabling developers to build custom commerce experiences while leveraging Spryker's robust business logic layer. ## Authentication - Obtain Access Token Customer authentication uses OAuth 2.0 to obtain access tokens for accessing protected Storefront API resources. The access token must be included in the Authorization header for all authenticated requests. ```bash # Authenticate as a customer and obtain access token curl -X POST "https://glue.mysprykershop.com/access-tokens" \ -H "Content-Type: application/vnd.api+json" \ -d '{ "data": { "type": "access-tokens", "attributes": { "username": "spencor.hopkin@spryker.com", "password": "change123" } } }' # Response contains access_token and refresh_token # { # "data": { # "type": "access-tokens", # "attributes": { # "tokenType": "Bearer", # "expiresIn": 28800, # "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", # "refreshToken": "def50200..." # } # } # } # Use the token in subsequent requests curl -X GET "https://glue.mysprykershop.com/orders" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." ``` ## Backend API - API Key Authorization Backend API supports API key-based authentication for system-to-system integrations. API keys are generated in the Back Office and can be passed via header or URL parameter. ```bash # Using X-Api-Key header (recommended) curl -X GET "https://glue-backend.mysprykershop.com/dynamic-entity/countries" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Api-Key: 6264714260f980fe38c6be2439b0a8e9" # Using api_key URL parameter curl -X GET "https://glue-backend.mysprykershop.com/dynamic-entity/countries?api_key=6264714260f980fe38c6be2439b0a8e9" \ -H "Content-Type: application/json" \ -H "Accept: application/json" ``` ## Backend API - Token Authentication Backend API also supports token-based authentication using Back Office user credentials for administrative access to protected resources. ```bash # Obtain Backend API token curl -X POST "https://glue-backend.mysprykershop.com/token/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Accept: application/json" \ -d "grant_type=password&username=admin@spryker.com&password=change123" # Use token for Backend API requests curl -X GET "https://glue-backend.mysprykershop.com/dynamic-entity/countries" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer {your_token}" ``` ## Catalog Search with Filtering The catalog search endpoint provides powerful product discovery with faceted navigation, filtering by multiple attributes, price ranges, ratings, and pagination support. ```bash # Basic search with query curl -X GET "https://glue.mysprykershop.com/catalog-search?q=Sony" \ -H "Content-Type: application/vnd.api+json" # Advanced search with multiple filters curl -X GET "https://glue.mysprykershop.com/catalog-search?q=Sony&brand=Sony&color[]=Black&color[]=White&price[min]=50&price[max]=200&label[]=SALE%20%25&rating[min]=3&rating[max]=5&sort=price_asc&page[offset]=0&page[limit]=12" \ -H "Content-Type: application/vnd.api+json" # Response includes products, facets, and pagination # { # "data": [{ # "type": "catalog-search", # "attributes": { # "abstractProducts": [{ # "abstractSku": "077", # "abstractName": "Sony Xperia Z3 Compact", # "price": 14554, # "prices": [{"priceTypeName": "DEFAULT", "grossAmount": 14554, "currency": {"code": "EUR"}}] # }], # "valueFacets": [{"name": "brand", "values": [{"value": "Sony", "doc_count": 42}]}], # "rangeFacets": [{"name": "price", "min": 3000, "max": 345699}], # "pagination": {"numFound": 42, "currentPage": 1, "maxPage": 4} # } # }] # } ``` ## Cart Management - Add Items to Cart The cart API supports adding various product types including standard products, configurable products, products with options, merchant products, and product offers for marketplace scenarios. ```bash # Add standard product to cart curl -X POST "https://glue.mysprykershop.com/carts/{cartId}/items" \ -H "Content-Type: application/vnd.api+json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "data": { "type": "items", "attributes": { "sku": "123_456789", "quantity": 2 } } }' # Add configurable product with configuration data curl -X POST "https://glue.mysprykershop.com/carts/{cartId}/items?include=items" \ -H "Content-Type: application/vnd.api+json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "data": { "type": "items", "attributes": { "sku": "configurable-product-sku", "quantity": 3, "productConfigurationInstance": { "displayData": "{\"Preferred time of the day\":\"Afternoon\",\"Date\":\"09.09.2050\"}", "configuration": "{\"time_of_day\":\"4\"}", "configuratorKey": "DATE_TIME_CONFIGURATOR", "isComplete": true, "quantity": 3, "prices": [{"priceTypeName": "DEFAULT", "netAmount": 23434, "grossAmount": 42502, "currency": {"code": "EUR"}}] } } } }' # Add product with options curl -X POST "https://glue.mysprykershop.com/carts/{cartId}/items?include=items" \ -H "Content-Type: application/vnd.api+json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "data": { "type": "items", "attributes": { "sku": "product-with-options-sku", "quantity": 1, "productOptions": [{"sku": "option-1-sku"}, {"sku": "option-2-sku"}] } } }' # Add marketplace product offer curl -X POST "https://glue.mysprykershop.com/carts/{cartId}/items" \ -H "Content-Type: application/vnd.api+json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "data": { "type": "items", "attributes": { "sku": "005_30663301", "quantity": 2, "productOfferReference": "offer53" } } }' ``` ## Checkout - Place Order The checkout endpoint finalizes the purchase by placing an order with customer, billing, shipping, and payment information. Supports split shipments for different delivery addresses. ```bash # Place order with single shipment curl -X POST "https://glue.mysprykershop.com/checkout?include=orders,order-shipments" \ -H "Content-Type: application/vnd.api+json" \ -H "Authorization: Bearer {access_token}" \ -d '{ "data": { "type": "checkout", "attributes": { "customer": { "salutation": "Mr", "email": "spencor.hopkin@spryker.com", "firstName": "Spencor", "lastName": "Hopkin" }, "idCart": "033ee1ad-c3e9-5d2e-816f-23ff38a58d6d", "billingAddress": { "salutation": "Mr", "firstName": "Spencor", "lastName": "Hopkin", "address1": "Julie-Wolfthorn-Straße", "address2": "1", "zipCode": "10115", "city": "Berlin", "iso2Code": "DE", "company": "spryker", "phone": "+49 (30) 2084 98350" }, "payments": [{ "paymentMethodName": "Credit Card", "paymentProviderName": "DummyPayment" }], "shipments": [{ "items": ["066_23294028"], "shippingAddress": { "salutation": "Mr", "firstName": "Spencor", "lastName": "Hopkin", "address1": "Urbanstraße", "address2": "119", "zipCode": "10967", "city": "Berlin", "iso2Code": "DE", "company": "spryker", "phone": "+49 (30) 2084 98350" }, "idShipmentMethod": 1, "requestedDeliveryDate": "2021-09-29" }] } } }' # Response # { # "data": { # "type": "checkout", # "attributes": { # "orderReference": "DE--1", # "redirectUrl": null, # "isExternalRedirect": null # } # } # } ``` ## Order Management - Retrieve Orders Retrieve customer order history with pagination and detailed order information including items, shipments, payments, and totals. ```bash # Get all orders with pagination curl -X GET "https://glue.mysprykershop.com/orders?page[offset]=0&page[limit]=10" \ -H "Authorization: Bearer {access_token}" # Get specific order with shipment details curl -X GET "https://glue.mysprykershop.com/orders/DE--6?include=order-shipments" \ -H "Authorization: Bearer {access_token}" # Response includes full order details # { # "data": { # "type": "orders", # "id": "DE--6", # "attributes": { # "itemStates": ["payment pending"], # "createdAt": "2021-01-05 13:43:23.000000", # "currencyIsoCode": "EUR", # "priceMode": "GROSS_MODE", # "totals": { # "expenseTotal": 1180, # "discountTotal": 0, # "taxTotal": 12173, # "subtotal": 75064, # "grandTotal": 76244 # }, # "items": [{ # "name": "Samsung Galaxy S5 mini", # "sku": "066_23294028", # "quantity": 1, # "unitPrice": 39353 # }], # "payments": [{"amount": 76244, "paymentProvider": "DummyPayment", "paymentMethod": "Invoice"}] # } # } # } ``` ## Data Exchange API - CRUD Operations The Data Exchange API provides dynamic database access for real-time data transfer, allowing you to interact with any configured database table through a unified API. ```bash # GET - Retrieve collection with pagination and filtering curl -X GET "https://glue-backend.mysprykershop.com/dynamic-entity/countries?page[offset]=0&page[limit]=20&filter[country.iso2_code]=DE" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" # GET - Retrieve with relations curl -X GET "https://glue-backend.mysprykershop.com/dynamic-entity/countries?include=countryTaxRates" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" # POST - Create new entity curl -X POST "https://glue-backend.mysprykershop.com/dynamic-entity/countries" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "data": [{ "iso2_code": "WA", "iso3_code": "WWA", "name": "New Country" }] }' # POST - Create with relations curl -X POST "https://glue-backend.mysprykershop.com/dynamic-entity/countries" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "data": [{ "iso2_code": "DE", "iso3_code": "DEU", "name": "Germany", "countryTaxRates": [{ "name": "Germany Standard", "rate": "19.00" }] }] }' # PATCH - Update existing entity curl -X PATCH "https://glue-backend.mysprykershop.com/dynamic-entity/countries/1" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "data": { "iso2_code": "WB", "name": "Updated Country" } }' # PUT - Replace entity (upsert) curl -X PUT "https://glue-backend.mysprykershop.com/dynamic-entity/countries" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "data": [{ "id_country": 1, "iso2_code": "WB", "iso3_code": "WWB", "name": "Replaced Country" }] }' # DELETE - Remove entity curl -X DELETE "https://glue-backend.mysprykershop.com/dynamic-entity/countries?filter[countries.iso2_code]={\"in\": [\"UA\",\"US\"]}" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" ``` ## Data Exchange API - Non-Transactional Mode Enable non-transactional saving to process entities independently, allowing partial success when some records fail validation. ```bash # Non-transactional batch processing curl -X POST "https://glue-backend.mysprykershop.com/dynamic-entity/countries" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "X-Is-Transactional: false" \ -d '{ "data": [ {"iso2_code": "DE", "iso3_code": "DEU", "name": "Germany"}, {"iso2_code": "FR", "name": "France"} ] }' # Response includes successful records and errors # { # "data": [{"iso2_code": "DE", "iso3_code": "DEU", "name": "Germany", "id_country": 260}], # "errors": [{"code": "1307", "status": 400, "message": "The required field must not be empty. Field: countries[1].iso3_code"}] # } ``` ## API Request Parameters Common request parameters for pagination, sorting, filtering, and including related resources in Storefront API responses. ```bash # Pagination curl "https://glue.mysprykershop.com/catalog-search?page[offset]=12&page[limit]=24" # Sorting curl "https://glue.mysprykershop.com/catalog-search?sort=price_asc" curl "https://glue.mysprykershop.com/catalog-search?sort=-name" # Descending # Filtering curl "https://glue.mysprykershop.com/catalog-search?filter[brand]=Sony" # Sparse Fields - Request specific attributes only curl "https://glue.mysprykershop.com/abstract-products/077?fields[abstract-products]=name,sku,price" # Include Related Resources curl "https://glue.mysprykershop.com/carts/{cartId}/items?include=items,concrete-products,product-offers,merchants" # Combining parameters curl "https://glue.mysprykershop.com/orders?page[offset]=0&page[limit]=10&include=order-shipments" ``` ## Backend API Resource Module Structure Creating custom Backend API resources follows a specific module structure with controllers, processors, and plugins. Resources have direct access to Spryker's business logic layer (Facades). ```php <?php // Module structure: Glue/ResourcesBackendApi/ // Route Provider Plugin namespace Spryker\Glue\StoresBackendApi\Plugin; use Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RouteProviderPluginInterface; use Spryker\Glue\Kernel\Backend\AbstractPlugin; use Symfony\Component\Routing\Route; use Symfony\Component\Routing\RouteCollection; class StoresBackendApiRouteProviderPlugin extends AbstractPlugin implements RouteProviderPluginInterface { protected const ROUTE_STORES_GET_LIST = 'stores/get-list'; protected const STRATEGIES_AUTHORIZATION = '_authorization_strategies'; protected const STRATEGY_AUTHORIZATION_API_KEY = 'ApiKey'; public function addRoutes(RouteCollection $routeCollection): RouteCollection { $route = new Route(static::ROUTE_STORES_GET_LIST); $route->setMethods(['GET']) ->setController(StoresResourceController::class, 'getCollectionAction') ->setDefault(static::STRATEGIES_AUTHORIZATION, [static::STRATEGY_AUTHORIZATION_API_KEY]); $routeCollection->add(static::ROUTE_STORES_GET_LIST, 'GET', $route); return $routeCollection; } } // Resource Controller namespace Spryker\Glue\StoresBackendApi\Controller; use Generated\Shared\Transfer\GlueRequestTransfer; use Generated\Shared\Transfer\GlueResponseTransfer; use Spryker\Glue\Kernel\Backend\Controller\AbstractController; class StoresResourceController extends AbstractController { public function getCollectionAction(GlueRequestTransfer $glueRequestTransfer): GlueResponseTransfer { return $this->getFactory() ->createStoresReader() ->getStoresCollection($glueRequestTransfer); } } ``` ## HTTP Status Codes Reference Standard HTTP status codes returned by Spryker APIs for GET, POST, PATCH, and DELETE operations. ```plaintext GET Responses: 200 OK - Entity/entities returned successfully 400 Bad Request - Invalid request format 401 Unauthenticated - Missing or invalid token 403 Unauthorized - Insufficient permissions 404 Not Found - Resource not found POST Responses: 201 Created - Resource created successfully 400 Bad Request - Invalid request data 401 Unauthenticated - Missing or invalid token 422 Unprocessable Entity - Validation failed PATCH Responses: 200 OK - Resource updated successfully 400 Bad Request - Invalid request data 404 Not Found - Resource not found DELETE Responses: 204 No Content - Deleted successfully 400 Bad Request - Invalid request 405 Method Not Allowed - Deletion not permitted for entity ``` ## Summary Spryker Commerce OS provides a comprehensive API framework supporting both customer-facing (Storefront API) and administrative (Backend API) use cases. The Storefront API follows JSON:API conventions and is optimized for building headless commerce experiences, mobile apps, PWAs, and custom storefronts. Key capabilities include catalog search with faceted navigation, cart management for various product types, multi-step checkout with split delivery support, and order management. Authentication uses OAuth 2.0 with access tokens for customers and optional API keys for system integrations. The Backend API enables enterprise integrations with ERP, CRM, and PIM systems through direct Facade access and the flexible Data Exchange API for real-time database operations. The Data Exchange API supports full CRUD operations, relations, filtering, pagination, and both transactional and non-transactional batch processing modes. The modular architecture allows organizations to adopt specific Product Business Components (PBCs) while maintaining API consistency across all touchpoints. For marketplace scenarios, the platform supports merchant products, product offers, and separate merchant order management with dedicated state machines.