Backend API: Manage merchants

Last updated: September 25, 2026

Edit on GitHub

The merchants Backend API resource lets you retrieve, create, and update merchants (GET /merchants, GET /merchants/{merchantReference}, POST /merchants, PATCH /merchants/{merchantReference}). You can use it to build Back Office extensions, ERP and PIM integrations, and merchant onboarding automation.

This page does not repeat the attribute list, parameter reference, or response schema—for those, use the Swagger UI your Glue Backend application serves at its root URL, or run docker/sdk cli glue api:debug merchants --api-type=backend. It documents only what that generated schema does not show: installation, module wiring, and behavior that spans multiple modules.

Installation

These endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

For the required module version and plugin registration, see Install the Merchants Backend API. In particular, the isOpenForRelationRequest attribute is contributed by the Merchant Relation Request module and appears in the schema only once that module is installed and its expander plugins are registered.

Conventions

Request headers, pagination, filtering, sorting, and errors follow the rules in Backend API conventions. A PATCH request applies only the attributes present in the payload; every attribute you omit keeps its stored value.

The resource is restricted to the ROLE_BACK_OFFICE_USER role. A valid access token that lacks this role—for example, one issued to a merchant user—returns 403.

Behavior notes

The following behaviors are either not expressible in a *.resource.yml schema or currently differ from what it describes. Everything else—filterable and sortable fields, and attribute types and defaults—is in the generated schema, not here.

merchantUrls.url: the schema description is out of date

The schema currently documents url as taken as given, with no prefix added. In practice, the backend automatically prepends the locale’s URL prefix and a /merchant/ segment—so a request sending "url": "spryker-merchant" for de_DE is stored and returned as /de/merchant/spryker-merchant. Send only the slug. Until the merchants.resource.yml description is corrected at the source, treat this note as authoritative over the generated docs for this one property.

Merchant URL required per assigned store

A merchantUrls entry is required only for the locale of each store the merchant is assigned to; a merchant with no stores has no URL requirement. This check runs on both POST and PATCH—for example, assigning a new store on update without also sending a merchantUrls entry for that store’s locale returns 422 with error code 1315.

isOpenForRelationRequest defaults

Defaults to null on create; on update, omitting it keeps the stored value instead of resetting it. This differs from isActive, which defaults to false on create, because isOpenForRelationRequest is contributed by a separate module rather than owned by the base merchants resource.

Possible errors

CODE	STATUS	REASON
N/A	403	The authenticated user does not have the `ROLE_BACK_OFFICE_USER` role—for example, a merchant user’s token.
011	400	A filter key is not in the `filter[merchants.<property>]` form.
901	422	The request body failed schema validation. Each error names the rejected attribute in `source.pointer`.
1301	404	No merchant matches the given reference.
1302	422	The merchant was rejected by the domain—for example, a duplicate email, a duplicate merchant reference, or a duplicate or blank merchant URL, or, on update, a status transition that is not allowed from the current status.
1303	400	The `sort` parameter names a field that the collection does not support.
1304	422	A `stores` entry names an unknown store.
1305	422	A `merchantUrls` entry names an unknown locale.
1309	400	The `sort` parameter names more than one field.
1312	400	A filter key names a property that the collection does not support.
1313	400	The `filter[merchants.isActive]` value is not a boolean.
1314	500	The merchant was rejected without a reported reason.
1315	422	`merchantUrls` is missing an entry for a locale used by one of the merchant’s assigned stores.
1316	400	The `filter[merchants.statuses]` value names an unknown status.

To view generic errors, see API errors and troubleshooting.