Install the Orders Backend API feature

This document describes how to install the Orders Backend API, which exposes placed sales orders over the Spryker Backend API: read them, create them, fire order-management (OMS) events on their line items, and read or add order comments.

The Orders Backend API is part of the same spryker-feature/order-experience-management package as the Recurring Orders feature. If you already installed Recurring Orders, skip to 2) Install the API Platform module.

The write side (order intake) does not reimplement checkout: it assembles a quote from the request payload and hands it to the existing checkout flow, so an API-placed order goes through the same pre-condition plugins, calculation, OMS bootstrapping, and mail as one placed on the Storefront.

Install feature core

Follow the steps below to install the Orders Backend API feature core.

Prerequisites

To start feature integration, review and install the necessary features:

1) Install the required modules

composer require spryker-feature/order-experience-management:"^1.0.0" --update-with-dependencies

The package requires spryker/checkout, spryker/sales, spryker/oms, spryker/calculation, spryker/price-cart-connector, spryker/price-product, spryker/product-option, spryker/product-measurement-unit, spryker/product-packaging-unit, spryker/shipment, spryker/payment, spryker/cart-code, spryker/company-user, spryker/company-business-unit, and spryker/glue-application, among others, so Composer installs them automatically with the command above.

2) Install the API Platform module

The Backend API endpoints run on API Platform, which spryker-feature/order-experience-management does not require unconditionally—install it explicitly:

composer require spryker/api-platform:"^1.0.0" --with-dependencies

3) Set up database schema and transfer objects

Apply database changes and generate entity and transfer changes:

console propel:install
console transfer:generate

4) Generate the API resources

The resource contracts live in the module at src/SprykerFeature/OrderExperienceManagement/resources/api/backend/. Regenerate the API Platform resource classes and drop the cached OpenAPI document:

GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate
GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue cache:clear
GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue cache:warmup

5) Set up behavior

Both plugin stacks below are optional and default to empty. Register them only if you installed Purchasing Control and want budget charging on API-placed orders.

Set up the order resource expander plugin

src/Pyz/Glue/OrderExperienceManagement/OrderExperienceManagementDependencyProvider.php

<?php

namespace Pyz\Glue\OrderExperienceManagement;

use SprykerFeature\Glue\OrderExperienceManagement\OrderExperienceManagementDependencyProvider as SprykerOrderExperienceManagementDependencyProvider;
use SprykerFeature\Glue\PurchasingControl\Plugin\OrderExperienceManagement\BudgetOrderResourceExpanderPlugin;

class OrderExperienceManagementDependencyProvider extends SprykerOrderExperienceManagementDependencyProvider
{
    /**
     * @return array<\SprykerFeature\Glue\OrderExperienceManagement\Dependency\Plugin\OrderResourceExpanderPluginInterface>
     */
    protected function getOrderResourceExpanderPlugins(): array
    {
        return [
            new BudgetOrderResourceExpanderPlugin(), #PurchasingControlFeature
        ];
    }
}

Set up the order intake quote expander plugin

src/Pyz/Zed/OrderExperienceManagement/OrderExperienceManagementDependencyProvider.php

<?php

namespace Pyz\Zed\OrderExperienceManagement;

use SprykerFeature\Zed\OrderExperienceManagement\OrderExperienceManagementDependencyProvider as SprykerOrderExperienceManagementDependencyProvider;
use SprykerFeature\Zed\PurchasingControl\Communication\Plugin\OrderExperienceManagement\BudgetOrderIntakeQuoteExpanderPlugin;

class OrderExperienceManagementDependencyProvider extends SprykerOrderExperienceManagementDependencyProvider
{
    /**
     * @return array<\SprykerFeature\Zed\OrderExperienceManagement\Dependency\Plugin\OrderIntakeQuoteExpanderPluginInterface>
     */
    protected function getOrderIntakeQuoteExpanderPlugins(): array
    {
        return [
            new BudgetOrderIntakeQuoteExpanderPlugin(), #PurchasingControlFeature
        ];
    }
}

The DI container caches the plugin chain, so clear it after wiring either stack:

console cache:empty-all

6) Exempt API-placed orders from the duplicate-checkout lock

The Storefront guards against double submission by locking a quote for the duration of checkout, keyed on the quote UUID. An intake quote has no UUID, so without an exemption the lock falls back to a guest name and email hash that collides across unrelated API orders.

src/Pyz/Zed/QuoteCheckoutConnector/QuoteCheckoutConnectorConfig.php

<?php

namespace Pyz\Zed\QuoteCheckoutConnector;

use Spryker\Zed\QuoteCheckoutConnector\QuoteCheckoutConnectorConfig as SprykerQuoteCheckoutConnectorConfig;
use SprykerFeature\Zed\OrderExperienceManagement\OrderExperienceManagementConfig;

class QuoteCheckoutConnectorConfig extends SprykerQuoteCheckoutConnectorConfig
{
    /**
     * @return array<string>
     */
    public function getQuoteCheckoutLockExemptSources(): array
    {
        return [
            OrderExperienceManagementConfig::SOURCE_API,
        ];
    }
}

7) Configure the fallback locale

Checkout errors are translated into the locale the request resolved. When none resolves, the module falls back to en_US.

src/Pyz/Zed/OrderExperienceManagement/OrderExperienceManagementConfig.php

<?php

namespace Pyz\Zed\OrderExperienceManagement;

use SprykerFeature\Zed\OrderExperienceManagement\OrderExperienceManagementConfig as SprykerOrderExperienceManagementConfig;

class OrderExperienceManagementConfig extends SprykerOrderExperienceManagementConfig
{
    public function getFallbackLocaleName(): string
    {
        return 'de_DE';
    }
}

Verify

TOKEN=$(curl -s -X POST http://glue-backend.mysprykershop.com/token \
  -d 'grant_type=password&[email protected]&password=change123' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

curl -s "http://glue-backend.mysprykershop.com/orders?page[limit]=1" \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/vnd.api+json'

A 200 response with a data array and meta.pagination confirms the resource is wired. The generated OpenAPI document is at http://glue-backend.mysprykershop.com/docs.

To learn how to use the endpoints, see Retrieve orders.