Install the Merchants Backend API

This document describes how to install the Merchants Backend API, which exposes merchant data at /merchants through the Glue Backend application. For the endpoint reference, see Backend API: Manage merchants.

Prerequisites

Install the required features:

composer show spryker/merchant | grep versions

Install the module

1) Install or upgrade the module

Install or upgrade spryker/merchant to at least 3.22.0 using Composer:

composer require spryker/merchant:"^3.22.0" --update-with-dependencies

2) Check the API Platform configuration

The resource schema ships inside the installed package, at vendor/spryker/merchant/resources/api/backend/merchants.resource.yml. The generator finds it as long as the Glue Backend application serves the backend API type and scans the directory the module is installed into.

In config/GlueBackend/packages/spryker_api_platform.php, confirm that apiTypes() includes backend. Leave sourceDirectories() alone unless your project overrides it—the default already covers installed packages. For what both settings do, see Configuration.

Also confirm that config/GlueBackend/bundles.php registers SprykerApiPlatformBundle and ApiPlatformBundle. If it does not, your project has not enabled API Platform for the Glue Backend yet—see Enable API Platform.

3) Set up the database schema and transfer objects

Apply the database schema changes and generate the transfer objects:

docker/sdk console transfer:generate

4) Generate the API resources

Generate the API resources, then clear the Glue Backend kernel cache:

docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate"
rm -rf data/cache/GlueBackend/*

Enable isOpenForRelationRequest

The isOpenForRelationRequest attribute is added to the merchants resource by the spryker/merchant-relation-request module, starting with version 1.2.0. It ships its own merchants.resource.yml that extends the resource defined by spryker/merchant. This step is optional—skip it if you do not need the attribute.

1) Install the module

composer require spryker/merchant-relation-request:"^1.2.0" --update-with-dependencies

2) Register the expander plugins

The module contributes the attribute through resource and transfer expander plugins, which are not registered by default. Add them in src/Pyz/Glue/Merchant/MerchantDependencyProvider.php:

<?php

namespace Pyz\Glue\Merchant;

use Spryker\Glue\Merchant\MerchantDependencyProvider as SprykerMerchantDependencyProvider;
use Spryker\Glue\MerchantRelationRequest\Api\Backend\Plugin\MerchantRelationRequestResourceExpanderPlugin;
use Spryker\Glue\MerchantRelationRequest\Api\Backend\Plugin\MerchantRelationRequestTransferExpanderPlugin;

class MerchantDependencyProvider extends SprykerMerchantDependencyProvider
{
    /**
     * @return array<\Spryker\Glue\MerchantExtension\Dependency\Plugin\MerchantBackendResourceExpanderPluginInterface>
     */
    protected function getMerchantBackendResourceExpanderPlugins(): array
    {
        return [
            new MerchantRelationRequestResourceExpanderPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Glue\MerchantExtension\Dependency\Plugin\MerchantBackendTransferExpanderPluginInterface>
     */
    protected function getMerchantBackendTransferExpanderPlugins(): array
    {
        return [
            new MerchantRelationRequestTransferExpanderPlugin(),
        ];
    }
}

Verification

Request a Back Office access token as described in Authenticate as a Back Office user, then retrieve a merchant collection.

Retrieve a merchant collection

curl "https://glue-backend.mysprykershop.com/merchants?page[limit]=1" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/vnd.api+json"

The integration is successful when the request returns 200 with a data array and a meta.pagination object.

Create a merchant to confirm the write path:

curl -X POST "https://glue-backend.mysprykershop.com/merchants" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"merchants","attributes":{"merchantReference":"MER000001","name":"Spryker Merchant","email":"[email protected]"}}}'

The request returns 201 with the created merchant, which is waiting-for-approval and inactive.

Troubleshooting