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, one is generated 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, 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": [
"hairyshatseast_token",
"hairyshatswest_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": [
"hairyshatseast_token",
"hairyshatswest_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": [
"hairyshatseast_token",
"hairyshatswest_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": [
"hairyshatseast_token",
"hairyshatswest_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": "Hairy's Hats West",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "555 First St",
"city": "Berkeley",
"state": "CA",
"zip": "94703",
"phone": "510-888-8888",
"country": "USA",
"token": "hairyshatswest_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": "hairyshats_token",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
},
{
"name": "Hairy's Hats East",
"active": true,
"longitude": 0,
"latitude": 0,
"address1": "222 Main St",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"phone": "510-888-8888",
"country": "USA",
"token": "hairyshatseast_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": "hairyshats_token",
"partial_approval_capable": false,
"keyed_auth_cvv_enforced": false
}
]
}