Spryker (spryker/spryker-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
Show doc for...
Context Summary (auto-generated)
Raw
# 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.