Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Automate store management

Use API requests to create, retrieve, and update your stores

The Management API lets you retrieve, create, and update your stores by making API requests. You can also do this manually in your Customer Area, but with API requests, you can automate these processes.

For more information about stores and point-of-sale account structures, see Set up your Adyen account for point of sale.

Before you start making API requests to manage stores, there are a couple of things you need to be aware of:

Store identification

Historically, stores under a merchant account have a human-readable reference, also known as the store code. This reference is unique for the merchant account. However, it is possible that a store reference is not unique on our platform. So we introduced a platform-generated unique store ID for each store.

When you create a store, you can provide a reference for it, and Adyen will automatically assign a unique ID.

For existing stores, the situation can vary. We are currently assigning unique IDs to existing stores, but it will take a while before this is completed. This means that if your existing store doesn't have an ID yet, you can't make a PATCH request to update the store.

Opening and closing stores

Stores can have three statuses that determine how they operate:

  • active: when you create a store, it is automatically set to active. After assigning and boarding payment terminals, the store is immediately open for business.

  • inactive: this blocks the terminals under the store from accepting new transactions, but capturing outstanding transactions is still possible. When you change the store status from active to inactive, the maximum transaction limits and number of Store-and-Forward transactions for the store are set to zero (0).
    When you open up the store again by changing the store status back to active, all these restrictions are lifted.

  • closed: before you can close a store, you must first change the store status to inactive. Then, when you change the store status from inactive to closed, all payment terminals under the store are immediately reassigned to the merchant inventory. This means the terminals need to be assigned to a different store and boarded before they can process transactions again.
    The main difference with the inactive status is that it is not possible to change the status anymore. You can't re-open a closed store.

API key, permissions, and versioning

To authenticate your requests, you need to have an API credential with an API key and the following roles:

  • Management API—Stores read
  • Management API—Stores read and write

You must specify the API key in the X-API-Key header of your requests.

You can create an API key in your test Customer Area. To access the live endpoints, you need to generate a new API key in your live Customer Area.

If you are using a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.

Versioning

Versioning is handled as part of the endpoint URL. For example, to send a request to version 1 of the /stores endpoint of the Management API, use:

https://management-test.adyen.com/v1/stores

Retrieve store details

You can make API requests to:

Get all stores

To retrieve a list of all stores that your API key has access to:

  1. Make a GET request to the /stores endpoint, optionally using one or more of the following query parameters to filter the list:

    • pageNumber: the list is grouped in pages. This query parameter returns the stores listed on the specified page.
    • pageSize: the number of stores to have on a page. The default is 10, the maximum is 100.
    • merchantId: the merchant account ID that a store belongs to. You can also get a list of stores under a specific merchant account using the /merchants/{merchantId} endpoint.
    • reference: the reference of the store. Because a store reference is only unique within a merchant account, a GET request to /stores using the store reference as a query parameter returns all stores with that reference, including those of different merchant accounts.
    Get a list of your stores
    curl https://management-test.adyen.com/v1/stores \
    -H "Content-Type: application/json" \
    -H "x-API-key: YOUR_API_KEY" \
  2. In the response, note the store ID. You can use this value to view information about a specific store or update a store.

    The next table shows the store details that the response can include.

    Parameter Description
    address An object that contains:
    • city: the city of the store.
    • country: the country of the store.
    • line1 line2 line3: up to three lines used for the street name, street number, and other information.
    • postalCode: the postal code of the store.
    • stateOrProvince: the state or province code as defined in ISO 3166-2. For example, ON for Ontario, Canada.
    description Your description of the store.
    externalReferenceId Only when using the Zip payment method.

    The location ID that Zip has assigned to your store.

    id Unique identifier of the store, starting with ST. This value is generated by Adyen.
    legalEntityId Only for Adyen for Platforms merchants.

    The legal entity that the store is associated with. If not specified, the legal entity of the merchant account is used.

    links The URL of the store.
    merchantId The ID of the merchant account that the store belongs to.
    phoneNumber The phone number of the store.
    reference Your reference to recognize the store by. The reference appears in your reports.
    shopperStatement Store name shown on the shopper's bank or credit card statement and on the shopper receipt.
    splitConfiguration Only for Adyen for Platforms merchants.

    An object that contains:

    • balanceAccountId: the balance account linked to the account holder.
    • splitConfigurationId: the UUID of the split configuration that is set up for the store in the Customer Area.

    status The status of the store.
    List of stores
    {
        "_links": {
            "first": {
                "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=1&pageSize=1"
            },
            "last": {
                "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=2&pageSize=1"
            },
            "next": {
                "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=2&pageSize=1"
            },
            "self": {
                "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=1&pageSize=1"
            }
        },
        "itemsTotal": 2,
        "pagesTotal": 1,
        "data": [
            {
                "id": "ST322LJ223223K5F4SQNR9XL5",
                "address": {
                    "city": "Springfield",
                    "country": "US",
                    "line1": "200 Main Street",
                    "line2": "Building 5A",
                    "line3":"Suite 3",
                    "postalCode":"20250",
                    "stateOrProvince":"NY"
                },
                "description": "City centre store",
                "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
                "phoneNumber": "1813702551707653",
                "reference": "Springfield Shop",
                "status": "active",
                "_links": {
                     "self": {
                        "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL5"
                     }
                }
            },
            {
                "id": "ST322LJ223223K5F4SQNR9XL6",
                "address": {
                    "city": "North Madison",
                    "country": "US",
                    "line1": "1492 Townline Road",
                    "line2": "Rowland Business Park",
                    "postalCode":"20577",
                    "stateOrProvince":"NY"
                },
                "description": "West location",
                "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
                "phoneNumber": "1211992213193020",
                "reference": "Second Madison store",
                "status": "active",
                "_links": {
                     "self": {
                        "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL6"
                     }
                }
            }
        ]
    }

Get stores under a merchant account

To retrieve a list of all stores under a specific merchant account:

  1. Make sure you know your merchant account ID. To retrieve a list of merchant account IDs accessible with your API key, make a GET request to https://management-test.adyen.com/v1/merchants/.

  2. Make a GET request to the /merchants/{merchantId}/stores endpoint, optionally using one or more of the following query parameters to filter the list:

    • pageNumber: the list is grouped in pages. This query parameter returns the stores listed on the specified page.
    • pageSize: the number of stores to have on a page. The default is 10, the maximum is 100.
    • reference: the reference of the store.

    Alternatively, you can make a GET request to /stores?merchantId={merchantId}, using the merchantId as a query parameter.

    Get a list of stores by merchant account ID

    The response format is the same as when you get all stores that your API key has access to.

Get a store by ID

To retrieve the details of a specific store, you need to identify that store by its unique store ID.

  1. Make sure you know the id or the reference of the store. To obtain this, get a list of all stores or a list of stores under a specific merchant account.

  2. Make a GET request to one of the following endpoints:

    • /stores/{id}
    • /merchants/{merchantId}/stores/{id}

    Alternatively, if the store doesn't have a unique ID yet, use the store reference as a query parameter. However, because the reference is only unique within a merchant account, you will get all stores with that reference, including those of different merchant accounts. To use the reference, make a GET request to:

    • /stores?reference={reference}
    • /merchants/{merchantId}/stores?reference={reference}

    This example shows how to get information about a store using the store ID in the path.

    Get information about a store by ID
    curl https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL6 \
    -H "x-API-key: YOUR_API_KEY" \
    -X GET \

    The response returns the same details as when you view all stores that your API key has access to, but only for the specified store. Here is an example:

    Response showing the store details
    {
        "id": "ST322LJ223223K5F4SQNR9XL6",
        "address": {
            "city": "North Madison",
            "country": "US",
            "line1": "1492 Townline Road",
            "line2": "Rowland Business Park",
            "postalCode":"20577",
            "stateOrProvince":"NY"
        },
        "description": "West location",
        "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
        "phoneNumber": "1211992213193020",
        "reference": "Second Madison store",
        "status": "active",
        "_links": {
            "self": {
                "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL6"
            }
        }
    }

Create a store

To add a store to your merchant account:

  1. Make sure you know your merchant account ID. To retrieve a list of merchant account IDs accessible with your API key, make a GET request to https://management-test.adyen.com/v1/merchants/.

  2. Make a POST request to /stores, specifying:

    Parameter Required Type Description
    address -white_check_mark- Object An object that contains:
    • city: the city of the store.
    • country: the country of the store.
    • line1 line2 line3: up to three lines can be used for the street name, street number, and other information. Only the first line is mandatory.
    • postalCode: the postal code of the store.
    • stateOrProvince: Required for Australia, Brazil, Canada, India, Mexico, New Zealand, United States. The state or province of the store as defined in ISO 3166-2. For example, ON for Ontario, Canada.
    description -white_check_mark- String A description for the store.
    externalReferenceId String Only when using the Zip payment method.

    The location ID that Zip has assigned to your store.

    legalEntityId String Only for Adyen for Platforms merchants. Required if different than the legal entity of the merchant account.

    The legal entity of the store.

    merchantId -white_check_mark- String Your merchant account ID.
    phoneNumber -white_check_mark- String The phone number of the store.
    reference String A reference to recognize the store by. The reference appears in your reports. Allowed characters: lowercase and uppercase letters without diacritics, numbers 0 through 9, hyphen (-), and underscore (_).
    shopperStatement -white_check_mark- String Store name shown on the shopper's bank or credit card statement and the shopper receipt. Maximum length: 22 characters. Cannot be all numerals.
    splitConfiguration Object Only for Adyen for Platforms merchants. Required if the store has a split configuration.

    This object consists of:

    • balanceAccountId: the balance account linked to the account holder.
    • splitConfigurationId: the UUID of the split configuration that is set up for the store in the Customer Area.

    You can also make a POST request to /merchants/{merchantId}/stores/ using the same parameters. In that case you do not need to include your merchant account ID in the request body.

    This example request shows how you create a store:

    Create a store
    curl https://management-test.adyen.com/v1/stores \
    -H "Content-Type: application/json" \
    -H "x-API-key: YOUR_API_KEY" \
    -X POST \
    -d '
    {
        "merchantId":"YOUR_MERCHANT_ACCOUNT_ID",
        "description":"City centre store",
        "shopperStatement": "Springfield Shop",
        "phoneNumber":"1813702551707653",
        "reference":"Spring_store_2",
        "address":{
            "country": "US",
            "line1": "200 Main Street",
            "line2": "Building 5A",
            "line3":"Suite 3",
            "city": "Springfield",
            "stateOrProvince": "NY",
            "postalCode":"20250"
        }
    }
  3. In the response, note that this includes:

    • id: the platform-generated ID for your new store. You can use this when you want to update the store.
    Store created
    {
        "id": "ST322LJ223223K5F4SQNR9XL5",
        "address":{
            "country": "US",
            "line1": "200 Main Street",
            "line2": "Building 5A",
            "line3":"Suite 3",
            "city": "Springfield",
            "stateOrProvince": "NY",
            "postalCode":"20250"
        },
        "description": "City centre store",
        "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
        "phoneNumber": "1813702551707653",
        "reference": "Spring_store_2",
        "shopperStatement": "Springfield Shop",
        "status": "active",
        "_links": {
            "self": {
                "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL5"
            }
        }
    }

Error-handling

When an error occurs while creating a store, you receive a response with the following fields:

  • title: the reason for the error.
  • status: the HTTP status message.
  • requestId: an automatically-generated ID for the request.
  • invalidFields: an object that contains:
    • name: the parameter that caused the error.
    • message: an explanation of the error.

Some of the most common errors are:

invalidFields.name invalidFields.message Action
reference "Requested store already exists" Make another store creation request using a different store reference.
address.country "Country is invalid" The country code is not correct. Specify a two-letter country code in ISO_3166-1_alpha-2 format.
address.country "Not allowed to create stores in this country" It is not possible to create a store for this country through API. Contact our POS Support Team.

Update a store

To update a specific store, you need to identify that store by its unique store ID.

You can update the following store details:

  • address, except the country
  • description
  • externalReferenceId
  • splitConfiguration
  • status

In your request, include only the parameters you want to update. The same applies if the parameter is inside an object.

For example, to change the postal code and remove the third address line from the store address, the address object should include the postalCode parameter with the new value, and the line3 parameter with an empty value.

To update a store:

  1. Make sure you know the id of the store. To obtain this, get a list of all stores or a list of stores under a specific merchant account.

  2. Make a PATCH request to one of the following endpoints:

    https://management-test.adyen.com/v1/stores/{id}
    https://management-test.adyen.com/v1/merchants/{merchantId}/stores/{id}

    In the request body, include any of the following parameters:

    Parameter Type Description
    address Object Can contain string values for the following parameters:
    • city: the city of the store.
    • line1 line2 line3: up to three lines can be used for the street name, street number, and other information.
    • postalCode: the postal code of the store.
    • stateOrProvince: Required for Australia, Brazil, Canada, India, Mexico, New Zealand, United States. The state or province of the store as defined in ISO 3166-2. For example, ON for Ontario, Canada.
    It is not possible to update the country of the store.
    description String Your description of the store.
    externalReferenceId String Only when using the Zip payment method.

    The location ID that Zip has assigned to your store.

    splitConfiguration Object Only for Adyen for Platforms merchants.

    An object that contains:

    • balanceAccountId: the balance account linked to the account holder.
    • splitConfigurationId: the UUID of the split configuration that is set up for the store in the Customer Area.

    status Enum The status of the store. You can change the status from active to inactive or from inactive to active or closed. Once closed, you can't change the status anymore.

    This example shows how you update a store's street address and postal code, identifying the store by ID. The first two lines of the address are changed and the third line is removed by including an empty value:

    Update a store's address
    curl https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL5 \
    -H "Content-Type: application/json" \
    -H "x-API-key: YOUR_API_KEY" \
    -X PATCH \
    -d '
    {
         "address":{
            "line1": "1776 West Pinewood Avenue",
            "line2": "Heartland Building",
            "line3": "",
            "postalCode":"20251"
         }
    }

    When you receive the response, note that this includes the full store details, not just the parameter(s) you updated.

    Store address updated
    {
        "id": "ST322LJ223223K5F4SQNR9XL5",
        "address":{
            "country": "US",
            "line1": "1776 West Pinewood Avenue",
            "line2": "Heartland Building",
            "city": "Springfield",
            "stateOrProvince": "NY",
            "postalCode":"20251"
        },
        "description": "City Centre store",
        "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
        "phoneNumber": "1813702551707653",
        "reference": "Spring_store_2",
        "status": "active",
        "_links": {
            "self": {
                "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL5"
            }
        }
    }

See also