Stores

The stores resource represents a single storefront that sells goods and/or services and accepts payment by card. A store can represent either a physical or e-commerce storefront. Stores that are owned or operated by a single business entity can be grouped together through association to a common merchant resource. This grouping works well to represent chain stores and other such businesses. For example, if Safeway, Inc. were represented by a merchant resource, then the Safeway storefront at 2995 San Pablo Ave, Berkeley and the e-commerce storefront, Safeway.com, would both be represented by store resources. Stores are associated with a merchant by way of their merchant_token field. (Note that the Marqeta Platform also provides a resource named "business" that represents a buyer of goods or services and which provides payment by card.)

Before creating a campaign resource, you must create the stores that will participate in the campaign.

Create store

Action: POST
Endpoint: /stores

Use this endpoint to create a store. Add the store details to the body of the request in JSON format .

When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using up to 36 alphanumeric characters. If you do not include a token value, one is generated automatically.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the store.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
merchant_token string Yes The unique identifier of the merchant with which the store is associated. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.
mid string Yes Merchant identification number. 15 char max
address1 string Yes Street address of the store location. 255 char max
city string Yes City where the store is located. 40 char max
state string Yes State where the store is located. 255 char max
zip string Yes Zip code for the store location. 10 char max
name string Yes The name of the store. 40 char max
partial_auth_flag boolean No Indicates whether this store is accepting transactions that require partial authorizations. true | false

Default: true
partial_approval_capable boolean No True indicates that the store is capable of performing partial authorizations; false means the store is not capable of partial authorizations.

This value can be overriden during merchant onboarding.
true | false

Default: false
keyed_auth_cvv_enforced boolean No Indicates whether the CVV number must be entered for transactions at this store. true | false

Default: false
country string No The country where the store is located. 40 char max
active boolean No Indicates whether the store is active. true | false

Default: true
phone string No The store phone number. 40 char max
province string No The province of the store. 20 char max
address2 string No Additional address information. 255 char max
contact string No The name of the store contact. 40 char max
contact_email string No The email address of the store contact. 40 char max
latitude string No GPS latitude coordinate for store location. 10 char max
longitude string No GPS longitude coordinate for store location. 10 char max

Sample request body

{
"token": "my_store",
"mid": "123456",
"state": "ca",
"zip": "94610",
"address1": "200 Ellis Ave",
"city": "Newville",
"merchant_token": "BigChainRestaurant_merchant",
"name": "Store1"
}

Sample response body

{
"name": "Store1",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "200 Ellis Ave",
"city": "Newville",
"state": "ca",
"zip": "94610",
"token": "my_store",
"mid": "123456",
"merchant_token": "my_merchant",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
}


Retrieve store

Action: GET
Endpoint: /stores/{token}

Use this endpoint to retrieve a specific store. Include the store token path parameter to specify the store to return.

This endpoint supports field filtering.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the store to retrieve. Existing store token.

Issue a GET to /stores to retrieve store tokens.

Sample response body

{
"name": "Store1",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "200 Ellis Ave",
"city": "Newville",
"state": "ca",
"zip": "94610",
"token": "my_store",
"mid": "123456",
"merchant_token": "my_merchant",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
}


Update store

Action: PUT
Endpoint: /stores/{token}

Use this endpoint to update a store. Include the token path parameter to specify the store to update. Add the store details to the body of the request in JSON format. Only values of parameters in the request are modified; all others are left unchanged.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the store to update. Existing store token.

Issue a GET to /stores to retrieve store tokens.

Body field details

Name Type Required? Description Allowable Values
merchant_token string No The unique identifier of the merchant with which the store is associated. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.
partial_approval_capable boolean No True indicates that the store is capable of performing partial authorizations; false means the store is not capable of partial authorizations.

This value can be overriden during merchant onboarding.
true | false

Default: false
keyed_auth_cvv_enforced boolean No Indicates whether the CVV number must be entered for transactions at this store. true | false

Default: false
mid string No Merchant identification number. 15 char max
address1 string No Street address of the store location. 255 char max
city string No City where the store is located. 40 char max
state string No State where the store is located. 255 char max
zip string No Zip code for the store location. 10 char max
name string No The name of the store. 40 char max
country string No The country where the store is located. 40 char max
active boolean No Indicates whether the store is active. true | false

Default: true
phone string No The store phone number. 40 char max
province string No The province of the store. 20 char max
address2 string No Additional address information. 255 char max
contact string No The name of the store contact. 40 char max
contact_email string No The email address of the store contact. 40 char max
partial_auth_flag boolean No Indicates whether this store is accepting transactions that require partial authorizations. true | false

Default: true
latitude string No GPS latitude coordinate for store location. 10 char max
longitude string No GPS longitude coordinate for store location. 10 char max

Sample request body

{
"contact": "my_contact"
}

Sample response body

{
"name": "Store1",
"contact": "my_contact",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "200 Ellis Ave",
"city": "Newville",
"state": "ca",
"zip": "94610",
"token": "my_store",
"mid": "123456",
"merchant_token": "my_merchant",
"keyed_auth_cvv_enforced": false
}


List stores

Action: GET
Endpoint: /stores

Use this endpoint to list existing stores.

This endpoint supports field filtering and pagination.

Sample response body

{
"count": 5,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"name": "Store1",
"active": false,
"longitude": 0,
"latitude": 0,
"address1": "200 Ellis Ave",
"city": "Newville",
"state": "ca",
"zip": "94610",
"token": "89f1baed-cf9e-430b-93af-7f5b7a850fd0",
"mid": "123456",
"merchant_token": "my_merchant",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
},
{
"name": "Falafel City",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "3344 Mountain Blvd",
"city": "Berkeley",
"state": "CA",
"zip": "94609",
"country": "string",
"token": "FalafelCity_token",
"mid": "09359398345",
"merchant_token": "my_merchant",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
}
]
}


Retrieve stores by MID

Action: GET
Endpoint: /stores/mid/{mid}

Use this endpoint to retrieve a store based on its MID number. Include the mid number as a path parameter to specify the store to return.

This endpoint supports field filtering.

URL path parameters

Name Type Required? Description Allowable Values
mid string Yes The MID identifying the store you want to retrieve. 15 char max

Sample response code

{
"name": "Store1",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "200 Ellis Ave",
"city": "Newville",
"state": "ca",
"zip": "94610",
"token": "my_store",
"mid": "123456",
"merchant_token": "BigChainRestaurant_merchant",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
}