Create Campaign

Action: POST
Endpoint: /campaigns

To create a campaign, send a POST request to the /campaigns endpoint and include the campaign details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. 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}

To retrieve a specific campaign, issue a GET request to the /campaigns/{token} endpoint. 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}

To update a campaign, send a PUT request to the /campaigns/{token} endpoint. Include the campaign token path parameter to indicate the campaign to update. Include the modified detail parameters in JSON format in the body of the request. 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

To retrieve a list of existing campaigns, issue a GET request to the /campaigns endpoint.

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

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

To return the balance for a specific campaign, send a GET request to the /campaigns/{token}/balance endpoint. Supply a campaign token path parameter to indicate the campaign to return. You can optionally request the balance for a specific date range.

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

To return a list of stores associated with a campaign, send a GET request to the /campaigns/{token}/stores endpoint. Include the campaign token to indicate the campaign whose store(s) to retrieve.

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
}
]
}