Create stores

In the platform setup, you need to create stores for your users for point-of-sale and ecommerce payments. A store ensures that the transactions you process for them corresponds to an accurate payer statement. You can use the Management API to create and manage stores for your users.

Stores are linked to the legal entity of your user through business lines. To create a store, you will first need to collect from your user the address and phone number of the store, and the name of the store that will appear on the bank and credit card statements of shoppers.

Before you begin

This page assumes you have already:

• Completed other onboarding steps.
• Received your Management API credentials.

Store identification

When you create a store, Adyen automatically assigns a unique ID to the store. You can also optionally provide a store reference for your reports. The store ID is unique to the entire Adyen platform, while the reference is only unique to your merchant account. To update the store, you need to know the store ID.

Business lines

When you create a store in the platform setup, you need to link the store to at least one business line. A business line includes information such as the goods or services the legal entity offers.

Adyen first checks the information provided by your users in their business line to assess possible risks from doing business with them. Once their business line is verified and the required capability is allowed, you can start processing payments through the stores.

A store can be linked to multiple business lines, as long as the business lines are part of the same legal entity. To create a business line, see create business lines.

Store status

Stores can have three statuses that determine how they operate:

• active: when you create a store, it is automatically set to active. The store can then immediately process payments.

• inactive: when you change the store status from active to inactive, the store is blocked from accepting new transactions, but capturing outstanding transactions is still possible. When you change the store status back to active, this restriction is removed.

• closed: before you can close a store, you must first change the store status to inactive. It is not possible to change the status anymore because a closed store cannot be reopened.

Create a store

Before you create a store, make sure you know the merchant account ID and business lines that the store will be associated with.
For a list of merchant account IDs accessible with your API key, make a GET request to /merchants.

1. To create a store, make a POST /stores, specifying:

Parameter	Required	Description
address		An object that contains: city: the city of the store. country: the country of the store. The store country must match the country of the legal entity. 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 only for the United States. The state or province of the store as defined in ISO 3166-2. For example, IL in the United States.
description		A description for the store.
businessLineIds		An array that contains business line IDs. Must be part of the same legal entity as the merchant account. Leave blank to use the business line of the merchant account. Required when there are multiple business lines under the merchant account.
merchantId		The merchant account ID.
phoneNumber		The complete phone number of the store, beginning with + and the country code.
reference		A reference to recognize the store by. Allowed characters: Lowercase and uppercase letters without diacritics, numbers 0 through 9, hyphen (-), and underscore (_). If you do not provide a reference in your POST request, it is populated with the Adyen-generated id.
shopperStatement		The store name shown on the shopper's bank or credit card statement and the shopper receipt. Maximum length: 22 characters. Cannot be all numerals.

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

The following example shows how to create a store:

2. In the response, note that this includes the Adyen-generated id for the store. You can use this as a path parameter to update the store.

Retrieve store details

You can make API requests to:

• Get a list of stores. For each store, the response includes the full details.
• Get the details of a specific store.

Get a list of stores

1. To get a list of stores, use one of the following endpoints:

   • GET /stores for the details of all stores that your API key has access to.
   • GET /merchants/{merchantId}/stores for the details of the stores under a specific merchant account. To find the merchantId, make a GET request to /merchants.

   You can filter the paginated response using the following query parameters:

   • pageNumber: 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 only use this query parameter with a GET /stores request.
   • reference: the reference of the store. Because a store reference is only unique within a merchant account, a GET /stores request using the store reference as a query parameter returns all stores with that reference, including those of different merchant accounts.

2. In the response, note the id of the store. You can use this value to get the details of a specific store or to 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, IL for Illinois in the United States.
   description	The description of the store.
   id	Unique identifier of the store, starting with ST. This value is generated by Adyen.
   businessLineIds	Unique identifiers of the business lines associated with the store.
   _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, including the country code.
   reference	The reference for the store. If a reference was not specified when the store was created, the reference is populated with the store id.
   shopperStatement	Store name shown on the shopper's bank or credit card statement and on the shopper receipt.
   status	The status of the store.

Get the details of a specific store

1. Make sure you know the id or the reference of the store. To find these values, get a list of stores.

2. To get the details of a single store, use the following endpoints:

   • GET /stores/{storeId}
   • GET /merchants/{merchantId}/stores/{storeId}

   You can also use the store reference as a query parameter. Because the reference is only unique within a merchant account, if you use the /stores endpoint you get all stores with that reference, including those of different merchant accounts.

   To get the details of a store under a merchant account using the store reference, make a GET request to /merchants/{merchantId}/stores?reference={reference}.

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

3. Note that the response returns the same details as when you get a list of stores, but only for the specified store.

Update a store

To update a store, you need to know its unique store ID. 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 find this value, get a list of stores.

2. To update the store, use the following endpoints:

   • PATCH /stores/{storeId}
   • PATCH /merchants/{merchantId}/stores/{storeId}

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

   Parameter	Description
   address	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. Must be in the same postal code format as the country of the store. stateOrProvince: Required only for the United States. The state or province of the store as defined in ISO 3166-2. For example, IL for Illinois in the United States. It is not possible to update the country of the store.
   description	Your description of the store.
   businessLineIds	An array that contains unique identifiers of business lines. Must be part of the same legal entity as the merchant account. Business lines can only be added, not removed from a store.
   status	The status of the store. You can change the status from active to inactive or from inactive to active or closed. After a store is 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:

3. Note that the response includes the full store details.