Backend API: Retrieve merchant profiles

Last updated:
Edit on GitHub

The Backend API exposes merchant profiles through two resources, one per audience:

  • merchant-profile: a merchant user retrieves the profile of the merchant they are assigned to. The merchant is resolved from the access token, so the endpoint carries no identifier. The resource covers what the merchant manages on the Merchant Portal profile page, including the merchant details, the Storefront URLs, the address, and the localized texts.
  • merchant-profiles: a Back Office user retrieves the profile of any merchant by its merchant reference.

The two audiences are strictly separated. A merchant user calling the merchant-profiles endpoint, or a Back Office user calling the merchant-profile endpoint, gets a 403 response.

There is no endpoint to create or delete a profile: a profile is created together with its merchant and removed with it. To create a merchant, use the Back Office or the merchants resource of the Backend API.

Installation

The endpoints are provided by the MerchantProfile module and require the API Platform integration of the Backend API. For installation instructions, see Install the Merchant Profile Backend API.

Retrieve the profile of your merchant

To retrieve the profile of the merchant the authenticated merchant user is assigned to, send the request:

GET /merchant-profile

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the merchant user to send requests to protected resources. Get it by authenticating as a merchant user.

The merchant of the authenticated user must be approved. A merchant user of a merchant that is still waiting for approval gets a 403 response, as in the Merchant Portal.

Request sample: retrieve the profile of your merchant

GET https://glue-backend.mysprykershop.com/merchant-profile

Response

merchantUrls and localizedAttributes contain one entry per locale of the stores listed in stores, with null values where a URL or text is not set.

Response sample: retrieve the profile of your merchant 
{
    "data": {
        "type": "merchant-profile",
        "id": "MER000001",
        "attributes": {
            "merchantReference": "MER000001",
            "name": "Spryker",
            "email": "[email protected]",
            "registrationNumber": "HRB 134310",
            "isActive": true,
            "isOpenForRelationRequest": true,
            "stores": [
                "DE",
                "AT"
            ],
            "merchantUrls": [
                {
                    "localeName": "de_DE",
                    "url": "/de/merchant/spryker"
                },
                {
                    "localeName": "en_US",
                    "url": "/en/merchant/spryker"
                }
            ],
            "contactPersonTitle": "Mr",
            "contactPersonFirstName": "Harald",
            "contactPersonLastName": "Schmidt",
            "contactPersonRole": "E-Commerce Manager",
            "contactPersonPhone": "+49 30 208498350",
            "publicEmail": "[email protected]",
            "publicPhone": "+49 30 208498350",
            "faxNumber": "+49 30 208498351",
            "logoUrl": "https://images.example.com/merchants/spryker/logo.png",
            "address": {
                "countryIso2Code": "DE",
                "zipCode": "10117",
                "city": "Berlin",
                "address1": "Julie-Wolfthorn-Straße",
                "address2": "1",
                "address3": null,
                "latitude": "52.5290",
                "longitude": "13.3846"
            },
            "localizedAttributes": [
                {
                    "localeName": "de_DE",
                    "description": "Spryker ist der führende Anbieter für Unterhaltungselektronik.",
                    "bannerUrl": "https://images.example.com/merchants/spryker/banner-de.png",
                    "deliveryTime": "1-3 Werktage",
                    "termsConditions": "<p>Es gelten unsere allgemeinen Geschäftsbedingungen.</p>",
                    "cancellationPolicy": "<p>Widerruf innerhalb von 14 Tagen.</p>",
                    "imprint": "<p>Spryker Systems GmbH, Berlin.</p>",
                    "dataPrivacy": "<p>Wir verarbeiten Ihre Daten gemäß DSGVO.</p>"
                },
                {
                    "localeName": "en_US",
                    "description": "Spryker is your partner for consumer electronics.",
                    "bannerUrl": "https://images.example.com/merchants/spryker/banner-en.png",
                    "deliveryTime": "1-3 business days",
                    "termsConditions": null,
                    "cancellationPolicy": null,
                    "imprint": null,
                    "dataPrivacy": null
                }
            ]
        }
    }
}
ATTRIBUTE TYPE DESCRIPTION
merchantReference String Unique reference of the merchant. It is also the resource id. Read-only.
name String Name of the merchant.
email String Contact email of the merchant. Unique across merchants.
registrationNumber String Official business registration number of the merchant.
isActive Boolean Defines whether the merchant’s store is online. An inactive merchant is not published on the Storefront, and its product offers can’t be bought; its merchant users keep their access.
isOpenForRelationRequest Boolean Defines whether the merchant accepts merchant relation requests. null until it is set.
stores Array Names of the stores the merchant is assigned to. Read-only.
merchantUrls Array URLs of the merchant page on the Storefront, one entry per locale.
merchantUrls.localeName String Locale of the entry—for example, de_DE.
merchantUrls.url String Relative URL of the merchant page in the locale—for example, /de/merchant/spryker. null if no URL is set for the locale yet—for example, right after a new store is assigned to the merchant.
contactPersonTitle String Title of the contact person: Mr, Mrs, Dr, or Ms.
contactPersonFirstName String First name of the contact person.
contactPersonLastName String Last name of the contact person.
contactPersonRole String Role of the contact person in the merchant company.
contactPersonPhone String Phone number of the contact person.
publicEmail String Email address shown to customers.
publicPhone String Phone number shown to customers.
faxNumber String Fax number of the merchant.
logoUrl String URL of the merchant logo.
address Object Business address of the merchant. A profile has exactly one address.
address.countryIso2Code String Two-letter ISO 3166-1 country code of the address.
address.zipCode String Postal code.
address.city String City.
address.address1 String First line of the address, usually the street.
address.address2 String Second line of the address, usually the house number.
address.address3 String Third line of the address.
address.latitude String Latitude of the address in decimal degrees.
address.longitude String Longitude of the address in decimal degrees.
localizedAttributes Array Texts of the merchant per locale, with null where a text is not translated.
localizedAttributes.localeName String Locale of the entry—for example, de_DE.
localizedAttributes.description String Description of the merchant.
localizedAttributes.bannerUrl String URL of the merchant banner. null if no banner is set for the locale yet.
localizedAttributes.deliveryTime String Delivery time information.
localizedAttributes.termsConditions String Terms and conditions.
localizedAttributes.cancellationPolicy String Cancellation policy.
localizedAttributes.imprint String Imprint.
localizedAttributes.dataPrivacy String Data privacy statement.

Retrieve a merchant profile

To retrieve the profile of a merchant as a Back Office user, send the request:

GET /merchant-profiles/{{merchant_reference}}

PATH PARAMETER DESCRIPTION
{{merchant_reference}} Reference of the merchant whose profile to retrieve. To get it, retrieve merchants or check the merchant in the Back Office.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

The merchant does not have to be approved: a Back Office user retrieves the profile of a merchant that is still waiting for approval, as in the Back Office.

Request sample: retrieve a merchant profile

GET https://glue-backend.mysprykershop.com/merchant-profiles/MER000001

Response

The response has the same attributes as the response of Retrieve the profile of your merchant, with the resource type merchant-profiles. merchantUrls and localizedAttributes contain one entry for every locale configured in the project, not only the locales of the merchant’s stores. A merchant that has no profile yet is returned with null profile attributes.

Response sample: retrieve a merchant profile 
{
    "data": {
        "type": "merchant-profiles",
        "id": "MER000001",
        "attributes": {
            "merchantReference": "MER000001",
            "name": "Spryker",
            "email": "[email protected]",
            "registrationNumber": "HRB 134310",
            "isActive": true,
            "isOpenForRelationRequest": true,
            "stores": [
                "DE",
                "AT"
            ],
            "merchantUrls": [
                {
                    "localeName": "de_DE",
                    "url": "/de/merchant/spryker"
                },
                {
                    "localeName": "en_US",
                    "url": "/en/merchant/spryker"
                }
            ],
            "contactPersonTitle": "Mr",
            "contactPersonFirstName": "Harald",
            "contactPersonLastName": "Schmidt",
            "contactPersonRole": "E-Commerce Manager",
            "contactPersonPhone": "+49 30 208498350",
            "publicEmail": "[email protected]",
            "publicPhone": "+49 30 208498350",
            "faxNumber": "+49 30 208498351",
            "logoUrl": "https://images.example.com/merchants/spryker/logo.png",
            "address": {
                "countryIso2Code": "DE",
                "zipCode": "10117",
                "city": "Berlin",
                "address1": "Julie-Wolfthorn-Straße",
                "address2": "1",
                "address3": null,
                "latitude": "52.5290",
                "longitude": "13.3846"
            },
            "localizedAttributes": [
                {
                    "localeName": "de_DE",
                    "description": "Spryker ist der führende Anbieter für Unterhaltungselektronik.",
                    "bannerUrl": "https://images.example.com/merchants/spryker/banner-de.png",
                    "deliveryTime": "1-3 Werktage",
                    "termsConditions": "<p>Es gelten unsere allgemeinen Geschäftsbedingungen.</p>",
                    "cancellationPolicy": "<p>Widerruf innerhalb von 14 Tagen.</p>",
                    "imprint": "<p>Spryker Systems GmbH, Berlin.</p>",
                    "dataPrivacy": "<p>Wir verarbeiten Ihre Daten gemäß DSGVO.</p>"
                },
                {
                    "localeName": "en_US",
                    "description": "Spryker is your partner for consumer electronics.",
                    "bannerUrl": "https://images.example.com/merchants/spryker/banner-en.png",
                    "deliveryTime": "1-3 business days",
                    "termsConditions": null,
                    "cancellationPolicy": null,
                    "imprint": null,
                    "dataPrivacy": null
                }
            ]
        }
    }
}
ATTRIBUTE TYPE DESCRIPTION
merchantReference String Unique reference of the merchant. It is also the resource id. Read-only.
name String Name of the merchant.
email String Contact email of the merchant. Unique across merchants.
registrationNumber String Official business registration number of the merchant.
isActive Boolean Defines whether the merchant’s store is online. An inactive merchant is not published on the Storefront, and its product offers can’t be bought; its merchant users keep their access.
isOpenForRelationRequest Boolean Defines whether the merchant accepts merchant relation requests. null until it is set.
stores Array Names of the stores the merchant is assigned to. Read-only.
merchantUrls Array URLs of the merchant page on the Storefront, one entry per locale.
merchantUrls.localeName String Locale of the entry—for example, de_DE.
merchantUrls.url String Relative URL of the merchant page in the locale—for example, /de/merchant/spryker. null if no URL is set for the locale yet—for example, right after a new store is assigned to the merchant.
contactPersonTitle String Title of the contact person: Mr, Mrs, Dr, or Ms.
contactPersonFirstName String First name of the contact person.
contactPersonLastName String Last name of the contact person.
contactPersonRole String Role of the contact person in the merchant company.
contactPersonPhone String Phone number of the contact person.
publicEmail String Email address shown to customers.
publicPhone String Phone number shown to customers.
faxNumber String Fax number of the merchant.
logoUrl String URL of the merchant logo.
address Object Business address of the merchant. A profile has exactly one address.
address.countryIso2Code String Two-letter ISO 3166-1 country code of the address.
address.zipCode String Postal code.
address.city String City.
address.address1 String First line of the address, usually the street.
address.address2 String Second line of the address, usually the house number.
address.address3 String Third line of the address.
address.latitude String Latitude of the address in decimal degrees.
address.longitude String Longitude of the address in decimal degrees.
localizedAttributes Array Texts of the merchant per locale, with null where a text is not translated.
localizedAttributes.localeName String Locale of the entry—for example, de_DE.
localizedAttributes.description String Description of the merchant.
localizedAttributes.bannerUrl String URL of the merchant banner. null if no banner is set for the locale yet.
localizedAttributes.deliveryTime String Delivery time information.
localizedAttributes.termsConditions String Terms and conditions.
localizedAttributes.cancellationPolicy String Cancellation policy.
localizedAttributes.imprint String Imprint.
localizedAttributes.dataPrivacy String Data privacy statement.

Possible errors

STATUS CODE REASON
401 N/A The Authorization header is missing, or the access token is invalid or expired.
403 N/A The authenticated user is a merchant user calling /merchant-profiles/{merchant_reference}, or a Back Office user calling /merchant-profile.
403 N/A The access token carries the merchant user scope, but the user is not assigned to a merchant.
403 N/A The merchant of the authenticated merchant user is not approved.
404 N/A The merchant with the specified reference doesn’t exist.

To view generic errors and status codes of the Backend API, see Backend API request and response reference.