Campaigns

A campaign is a mechanism for defining a group of stores. Campaigns are used with offers and MSA orders to specify the stores where funds can be spent. Funds can be spent at this group of stores only while the campaign is in effect (between the campaign's start_date and end_date) and only if the campaign's active field is set to true.

The Marqeta platform automatically generates a campaign whenever a merchant is created. In this case, the name and token of the campaign is the same as the merchant's. You can also create campaigns explicitly. However, depending on the use case, you might find that stores are not required and that a merchant with its automatically-generated campaign are sufficient.

Create campaign

Action: POST
Endpoint: /campaigns

Use this endpoint to create a campaign. Add the campaign 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, the system will generate one automatically.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier for the campaign.

If you do not include a token value, 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
active boolean No Defines whether the campaign is active. true | false

Default: true
name string Yes Name of the campaign. We recommend using a unique string. 40 char max
start_date string Yes The date the campaign begins. If active = false, then date is not relevant. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z, 36 char max
end_date string No The date the campaign ends. If active = false, then date is not relevant. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z, 36 char max
store_tokens array No The unique identifier(s) of the store(s) participating in the campaign. Existing store tokens enclosed in brackets, for example:

["store1", "store2"]

Issue a GET to /stores to retrieve store tokens.

Sample request body

{
"active": true,
"name": "My campaign 03",
"token": "my_campaign_token_03",
"start_date": "2016-05-24",
"end_date": "2019-05-24",
"store_tokens": [
"chicken_tooth_music_east_token",
"chicken_tooth_music_west_token"
]
}

Sample response body

{
"active": true,
"name": "My campaign 03",
"token": "my_campaign_token_03",
"start_date": "2016-05-24T00:00:00Z",
"end_date": "2019-05-24T00:00:00Z",
"store_tokens": [
"chicken_tooth_music_east_token",
"chicken_tooth_music_west_token"
],
"created_time": "2016-05-24T18:10:19Z",
"last_modified_time": "2016-05-24T18:10:19Z"
}


Retrieve campaign

Action: GET
Endpoint: /campaigns/{token}

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

This endpoint supports field filtering.

URL path parameters

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

Issue a GET to /campaigns to retrieve campaign tokens.

Sample response body

{
"active": true,
"name": "My campaign 03",
"token": "my_campaign_token_03",
"start_date": "2016-05-24T00:00:00Z",
"end_date": "2019-05-24T00:00:00Z",
"store_tokens": [
"chicken_tooth_music_east_token",
"chicken_tooth_music_west_token"
],
"created_time": "2016-05-24T18:10:19Z",
"last_modified_time": "2016-05-24T18:10:19Z"
}


Update campaign

Action: PUT
Endpoint: /campaigns/{token}

Use this endpoint to update a campaign. Include the campaign token path parameter to indicate the campaign to update. Add the modified detail parameters 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 campaign to update. Existing campaign token.

Issue a GET to /campaigns to retrieve campaign tokens.

Body field details

Name Type Required? Description Allowable Values
active boolean No Defines whether the campaign is active. true | false

Default: true
name string No Name of the campaign. We recommend using a unique string. 40 char max
start_date string No The date the campaign begins. If the active field = false, then date is not relevant. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z, 36 char max
end_date string No The date the campaign ends. If active = false, then date is not relevant. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z, 36 char max
store_tokens array No The unique identifier(s) of the store(s) participating in the campaign. Existing store tokens enclosed in brackets, for example:

["store1", "store2"]

Issue a GET to /stores to retrieve store tokens.

Sample request body

{
"active": "false"
}

Sample response body

{
"active": false,
"name": "My campaign 03",
"token": "my_campaign_token_03",
"start_date": "2016-05-24",
"end_date": "2019-05-24",
"store_tokens": [
"chicken_tooth_music_east_token",
"chicken_tooth_music_west_token"
],
"created_time": "2016-05-24T18:10:19Z",
"last_modified_time": "2016-05-24T18:16:36Z"
}


List campaigns

Action: GET
Endpoint: /campaigns

Use this endpoint to retrieve a list of existing campaigns.

This endpoint supports field filtering and pagination.

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": true,
"data": [
{
"active": true,
"name": "My_campaign_02",
"token": "my_campaign_token_02",
"start_date": "2016-05-23",
"store_tokens": [
"my_store3",
"my_store4"
]
"created_time": "2016-05-23T23:38:30Z",
"last_modified_time": "2016-05-23T23:38:30Z"
},
{
"active": true,
"name": "My_campaign_01",
"token": "my_campaign_token_01",
"start_date": "2016-05-23",
"store_tokens": [
"my_store1",
"my_store2"
]
"created_time": "2016-05-23T23:38:00Z",
"last_modified_time": "2016-05-23T23:38:00Z"
}
]
}


Retrieve campaign balance

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

Use this endpoint to return the balance for a specific campaign. Include a campaign token path parameter to indicate the campaign to return. You can optionally request the balance for a specific date range.

The campaign balance is an aggregation of balances across all cardholders for a specific campaign.

URL path parameters

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

Issue a GET to /campaigns to retrieve campaign tokens.

Query parameters

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

Sample response body

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


Retrieve campaign stores

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

Use this endpoint to return a list of stores associated with a campaign. Include the campaign token to indicate the source campaign.

This endpoint supports field filtering and pagination.

URL path parameters

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

Issue a GET to /campaigns to retrieve campaign tokens.

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"name": "Chicken Tooth Music West",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "555 First St",
"city": "Berkeley",
"state": "CA",
"zip": "94703",
"phone": "510-888-8888",
"country": "USA",
"token": "chicken_tooth_music_west_token",
"mid": "44444",
"mfd": {
"calculation_schedule_token": null,
"mode": "INHERIT"
},
"partial_auth_flag": true,
"created_time": "2015-11-14T01:30:20Z",
"last_modified_time": "2015-11-14T01:30:20Z",
"merchant_token": "chicken_tooth_music_token",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
},
{
"name": "Chicken Tooth Music East",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "222 Main St",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"phone": "510-888-8888",
"country": "USA",
"token": "chicken_tooth_music_east_token",
"mid": "33333",
"mfd": {
"calculation_schedule_token": null,
"mode": "INHERIT"
},
"partial_auth_flag": true,
"created_time": "2015-11-14T01:29:09Z",
"last_modified_time": "2015-11-14T01:29:09Z",
"merchant_token": "chicken_tooth_music_token",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
}
]
}