Merchants

The merchants resource is a grouping mechanism whose function is to associate store resources with one another. 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.

Although you are not required to create merchants in order to transact card purchases, create orders, or implement spend controls, merchants can be useful in terms of transaction tracking and reporting. Merchant information is included in the transaction response when applicable.

The merchant resource also provides a convenient way to enable/disable partial authorization for all stores associated with the merchant.

Note that as opposed to stores, merchants are not directly involved in card transactions.

Create merchant

Action: POST
Endpoint: /merchants

Use this endpoint to create a merchant. Add the merchant 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.

As a result of creating a merchant, the system creates a default campaign resource. This campaign resource will have the same name as the merchant and a token value generated by the system. You can issue a GET /campaign/{merchant_name} to retrieve the default campaign.

Body field details

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

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
name string Yes The name of the merchant.

This name is also used to name the default campaign that is created as a result of the POST /merchants call.
40 char max
active boolean No Indicates whether the merchant is active.

An active merchant is one who is in business and supported by Marqeta. Inactive merchants no longer accept payments through the Marqeta system.
true | false

Default: true
contact string No The name of the merchant contact. 40 char max
contact_email string No The email address of the merchant contact. 40 char max
address1 string No Merchant address. 255 char max
address2 string No Merchant address. 255 char max
city string No Merchant city. 40 char max
state string No Merchant state. 255 char max
province string No Merchant province. 20 char max
zip string No Merchant zip code. 10 char max
phone string No Merchant phone. 40 char max
country string No Merchant country. 40 char max
longitude number No GPS longitude coordinate for merchant location. 10 char max
latitude number No GPS latitude coordinate for merchant location. 10 char max
partial_auth_flag boolean No If true, allows cardholder to split payment between payment card and other payment method, such as cash or credit card. For example, if the charge is $50 but there is only $30 on the payment card, then the cardholder can pay the balance in cash or credit card. If false, entire transaction must use a single payment card (entire $50 must be covered by payment card). true | false

Default: true

Sample request body

{
"name": "My Merchant",
"active": "true",
"contact": "John Doe",
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}

Sample response body

{
"name": "My Merchant",
"active": true,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}


Retrieve merchant

Action: GET
Endpoint: /merchants/{token}

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

This endpoint supports field filtering.

URL path parameters

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

Issue GET to /merchants to retrieve merchant tokens.

Sample response body

{
"name": "My Merchant",
"active": true,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}


Update merchant

Action: PUT
Endpoint: /merchants/{token}

Use this endpoint to update a merchant. Include the token path parameter to specify the merchant to update. Add the merchant 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 merchant to update. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.

Body field details

Name Type Required? Description Allowable Values
name string No The name of the merchant. 40 char max
active boolean No Indicates whether the merchant is active.

An active merchant is one who is in business and supported by Marqeta. Inactive merchants no longer accept payments through the Marqeta system.
true | false

Default: true
contact string No The name of the merchant contact. 40 char max
contact_email string No The email address of the merchant contact. 40 char max
address1 string No Merchant address. 255 char max
address2 string No Merchant address. 255 char max
city string No Merchant city. 40 char max
state string No Merchant state. 255 char max
province string No Merchant province. 20 char max
zip string No Merchant zip code. 10 char max
phone string No Merchant phone. 40 char max
country string No Merchant country. 40 char max
longitude number No GPS longitude coordinate for merchant location. 10 char max
latitude number No GPS latitude coordinate for merchant location. 10 char max
partial_auth_flag boolean No If true, allows cardholder to split payment between payment card and other payment method, such as cash or credit card. For example, if the charge is $50 but there is only $30 on the payment card, then the cardholder can pay the balance in cash or credit card. If false, entire transaction must use a single payment card (entire $50 must be covered by payment card). true | false

Default: true

Sample request body

{
"active": "false"
}

Sample response body

{
"name": "My Merchant",
"active": false,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}


List merchants

Action: GET
Endpoint: /merchants

Use this path to list merchants.

This endpoint supports field filtering and pagination.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 1,
"is_more": yes,
"data": [
{
"name": "My Merchant",
"active": false,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}
]
}


Retrieve merchant balance

Action: GET
Endpoint: /merchants/{token}/balance

Use this endpoint to return the aggregate balance across all cardholders for a merchant. Include the merchant's token path parameter to indicate which merchant's balance to return. Use the optional start_date and end_date query parameters to return the balance over a date range.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the merchant whose balance you want to retrieve. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.

Query parameters

Name Type Required? Description Allowable Values
start_date string No The beginning of the date range. yyyy-MM-dd
end_date string No The end of the date range. yyyy-MM-dd

Sample response body

{
"token": "my_merchant",
"committed": 0,
"triggered": 0,
"balance": 0,
"customers_balance": 0,
"customers_spent": 0
}


List merchant stores

Action: GET
Endpoint: /merchants/{token}/stores

Use this endpoint to return the stores associated with a merchant. Include the merchant's token path parameter to indicate which merchant's stores to request.

This endpoint supports field filtering and pagination.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the merchant whose stores you want to retrieve. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"name": "My Store",
"longitude": 0,
"latitude": 0,
"token": "my_store1",
"partial_auth_capable": false,
"keyed_auth_cvv_enforced": false
},
{
"name": "My Store2",
"longitude": 0,
"latitude": 0,
"token": "my_store2",
"partial_auth_capable": false,
"keyed_auth_cvv_enforced": false
}
]
}