Retrieve information about all campaigns within a chain.
Contents
- Overview
- Version-specific information
- Permissions and Authentication
- HTTP parameters
- Headers
- Example request & response
- Possible error responses
Overview
- Call name: get-campaigns
- Endpoint URL: https://api0.spaaza.com/get-campaigns
- Request methods: GET
- Response Content-Type: application/json
- Auth required: yes
The get-campaigns endpoint is used to fetch a list of campaigns that are associated with a chain. Note that if there are more than 500 campaign assignments, no assignments are shown in the response and a warning is given, objects_exceed_maximum_quantity.
It is also possible, when using admin authentication, to fetch a campaign on behalf of a user and get the customer’s user_progress for the campaign. The user_progress in the get-campaigns response will provide a brief summary of a users interaction with a campaign. For a more complete description of user_progress in the campaign response please refer to user progress.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| >= 1.5.0 | Add current_count field to item purchase count campaign in response |
| >= 1.4.11 | Change default value of exclude_inactive from false to true and thereby do not show inactive campaigns by default |
Permissions and authentication
This API call requires a valid Spaaza session. The session can be as follows:
- Admin authentication: the performing user needs to be logged in and have
read accessto the chain to which the user is connected. - User authentication: a session generated by an end-user login.
HTTP parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| chain_id | (integer, mandatory) The ID of the chain for which the information is being requested. |
| user_id OR member_number OR username OR referral_code OR authentication_point_identifier OR auxiliary_identifier | (mandatory when querying user-specific information using admin authentication) The Spaaza unique ID (user_id, integer), member number (member_number, string), email address (username, valid email address), or identity in a third-party authentication system (authentication_point_identifier/auxiliary_identifier, string) of the user for whom the campaign is being requested. In the case of admin authentication, if this parameter is not passed, all campaigns for a chain are returned. |
| display_full_campaign | (boolean, default true, optional) Optional boolean flag to display the full campaign response JSON. A full campaign includes campaign_rules and campaign_assignments. The default behavior is to display the full campaign JSON. |
| campaign_type* | (string, optional) The type of campaign to be returned. This can be one of basket, birthday, cashback, content, interaction, item_purchase_count, login, loyalty, matching_item, mobile_content, points_wallet, profile_completion, progress, purchase_count, referral, signup, and wallet. If this field is omitted, campaigns of all types are returned. |
| order_by | (string, optional) A campaign parameter by which the results are returned in descending order. Current options for this field include priority and created_date. If no parameter is supplied, created_date is used as the default value. |
| exclude_inactive | (boolean, default true, optional) By default, inactive campaigns are NOT included in the results of this endpoint. Setting this flag to false includes any currently inactive campaigns in the results, both on the basis of whether their active parameter is set to false or on any dates defined in their active_date_from or active_date_until parameters. |
| campaign_type | (string, optional) This field allows the client to specify a set of campaign types to filter the campaigns in the response. The types should be provided as a comma-separated string. The field accepts a string containing any combination of the following campaign type keywords, separated by commas loyalty, wallet, points_wallet, product, basket, progress, cashback, referral, purchase_count, item_purchase_count, signup, birthday, content, mobile_content, profile_completion , interaction, login, matching_item, subscription or mobile_content. If this field is omitted, campaigns of all types are returned. |
*Requesting content campaigns
Note that in the case of campaign_type parameter values of content or mobile_content, a user or admin authentication-based session is not required to display campaign information specific to those campaign types.
Headers
The following headers can/must be passed to the API call:
| Parameter | Description |
|---|---|
| X-Spaaza-MyPrice-App-Hostname | (mandatory in the case of user authentication, not required otherwise) The hostname of the app for which the user is requesting the card. |
Example Request & Response
Request (#request)
Example curl request:
curl --location 'https://api0.spaaza.com/internal/get-campaigns?chain_id=1743&exclude_inactive=false' \
--header 'X-Spaaza-Session-User-Id: 1548854' \
--header 'X-Spaaza-Session-Key: 564e5b4faa7f639dacf1983f1dae62155d5734b789b06b5986c43bfe2542854e' \
--header 'X-Spaaza-API-Version: 1.4.11'
Response (#response)
Example response:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"campaigns": [
{
"active": true,
"allows_user_to_claim_voucher": true,
"assignment_count": 0,
"chain_id": 1762,
"created_date": "2022-05-31T19:47:34+00:00",
"created_voucher_claimed_by_default": true,
"currency_id": 2,
"custom_content": null,
"description": "Exchange your points for a voucher",
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 2013,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_contributor": false,
"is_default": false,
"is_deleted": false,
"last_modified_date": "2022-05-31T19:49:40+00:00",
"last_updated_by": {
"name": "Dave Sevenoaks",
"user_id": 21
},
"last_updated_date": "2022-05-31T19:49:40+00:00",
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"operator_type": "or",
"owner_code": "PTX_001",
"parameters": [],
"point_cost": 450,
"point_cost_method": "points",
"point_cost_method_wallet_campaign_id": 859,
"recipient_campaign_id": null,
"recipient_reward_amount": 15,
"recipient_reward_code": "",
"recipient_reward_discount_ratio": 0,
"recipient_reward_method": "voucher",
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 2,
"rounding_strategy": "neutral",
"sender_campaign_id": null,
"styling": {
"background_colour": "null",
"background_image_filename": null,
"background_image_url": null,
"layout_style": "standard",
"primary_action_background_colour": "null",
"primary_action_text_colour": "null",
"secondary_action_background_colour": "null",
"secondary_action_text_colour": "null",
"text_colour": "null"
},
"supports_contribution": true,
"supports_user_segments": true,
"tags": null,
"target_count": 0,
"title": "Get a €15 voucher with 450 points",
"type": "interaction",
"user_segment_id": null,
"visible_to_all_user_segments": true,
"voucher_description": "Thanks for being a valued customer",
"voucher_expiry_days": 120,
"voucher_image_url": null,
"voucher_notes": "null",
"voucher_text": "Your €15 voucher",
"voucher_title": "Your €15 voucher"
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"assignment_count": 0,
"cashback_ratio": "1.0000",
"chain_id": 1762,
"created_date": "2022-05-31T19:43:31+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 2,
"custom_content": null,
"description": "Earn 1 point for every euro spent at ACME",
"earn_on_promotional_items": true,
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 2011,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_contributor": true,
"is_default": false,
"is_deleted": false,
"last_modified_date": "2022-05-31T19:44:41+00:00",
"last_updated_by": {
"name": "Dave Sevenoaks",
"user_id": 21
},
"last_updated_date": "2022-05-31T19:44:41+00:00",
"max_reward_quantity": null,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"operator_type": "or",
"owner_code": null,
"parameters": [],
"recipient_campaign_id": 859,
"recipient_reward_amount": 1,
"recipient_reward_code": "",
"recipient_reward_discount_ratio": 0,
"recipient_reward_method": "points",
"return_reclaims_earned_rewards": false,
"reward_priority": 0,
"rounding_precision": 2,
"rounding_strategy": "neutral",
"sender_campaign_id": null,
"styling": {
"background_colour": "null",
"background_image_filename": null,
"background_image_url": null,
"layout_style": "standard",
"primary_action_background_colour": "null",
"primary_action_text_colour": "null",
"secondary_action_background_colour": "null",
"secondary_action_text_colour": "null",
"text_colour": "null"
},
"supports_contribution": true,
"supports_user_segments": true,
"tags": "csh_001,spring_005",
"target_count": 0,
"title": "Save points on every euro",
"type": "cashback",
"user_segment_id": null,
"visible_to_all_user_segments": true,
"voucher_description": null,
"voucher_expiry_days": 365,
"voucher_image_url": null,
"voucher_notes": null,
"voucher_text": null,
"voucher_title": null
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"assignment_count": 0,
"chain_id": 1762,
"created_date": "2022-05-31T19:23:12+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 2,
"custom_content": null,
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 2008,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_contributor": false,
"is_default": false,
"is_deleted": false,
"last_modified_date": "2022-05-31T19:30:45+00:00",
"last_updated_by": {
"name": "Dave Sevenoaks",
"user_id": 21
},
"last_updated_date": "2022-05-31T19:30:45+00:00",
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"operator_type": "or",
"owner_code": "PCT-ACME-001",
"parameters": [],
"recipient_campaign_id": null,
"recipient_reward_amount": 0,
"recipient_reward_code": "",
"recipient_reward_discount_ratio": 0.1,
"recipient_reward_method": "percentage_basket_voucher",
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 2,
"rounding_strategy": "neutral",
"sender_campaign_id": null,
"styling": {
"background_colour": "null",
"background_image_filename": null,
"background_image_url": null,
"layout_style": "standard",
"primary_action_background_colour": "null",
"primary_action_text_colour": "null",
"secondary_action_background_colour": "null",
"secondary_action_text_colour": "null",
"text_colour": "null"
},
"supports_contribution": true,
"supports_user_segments": true,
"tags": null,
"target_count": 0,
"title": "Welcome to the club",
"type": "signup",
"user_segment_id": null,
"visible_to_all_user_segments": true,
"voucher_description": "Welcome to the club",
"voucher_expiry_days": 30,
"voucher_image_url": null,
"voucher_notes": "Notes",
"voucher_text": "Welcome to the club",
"voucher_title": "Welcome to the club"
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"assignment_count": 0,
"chain_id": 1762,
"created_date": "2020-11-19T15:23:23+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 2,
"custom_content": null,
"days_before": 14,
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 1269,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": false,
"is_contributor": false,
"is_default": false,
"is_deleted": false,
"last_modified_date": "2022-05-31T19:12:12+00:00",
"last_updated_by": {
"name": "Dave Sevenoaks",
"user_id": 21
},
"last_updated_date": "2022-05-31T19:12:12+00:00",
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"notes": "",
"operator_type": "or",
"owner_code": null,
"parameters": [],
"recipient_campaign_id": null,
"recipient_reward_amount": 10,
"recipient_reward_code": "",
"recipient_reward_discount_ratio": 0,
"recipient_reward_method": "voucher",
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 2,
"rounding_strategy": "neutral",
"sender_campaign_id": null,
"styling": {
"background_colour": "null",
"background_image_filename": null,
"background_image_url": null,
"layout_style": "standard",
"primary_action_background_colour": "null",
"primary_action_text_colour": "null",
"secondary_action_background_colour": "null",
"secondary_action_text_colour": "null",
"text_colour": "null"
},
"supports_contribution": true,
"supports_user_segments": true,
"tags": "aeg034447a",
"target_count": 0,
"title": "Birthday",
"type": "birthday",
"user_segment_id": null,
"visible_to_all_user_segments": true,
"voucher_description": "null",
"voucher_expiry_days": 365,
"voucher_image_url": null,
"voucher_notes": "null",
"voucher_text": "Congratulations on your birthday!",
"voucher_title": "Congratulations on your birthday!"
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"assignment_count": 0,
"balance_can_subzero": true,
"chain_id": 1762,
"created_date": "2020-03-12T16:21:16+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 2,
"custom_content": null,
"description": "Earn vouchers to spend on your next purchase",
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"goal_amount": "150.00",
"id": 868,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_contributor": false,
"is_default": false,
"is_deleted": false,
"is_recurring": true,
"last_modified_date": "2023-05-02T11:39:18+00:00",
"last_updated_by": {
"name": "John Smith",
"user_id": 3341451
},
"last_updated_date": "2023-05-02T11:39:18+00:00",
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"notes": "",
"operator_type": "or",
"owner_code": null,
"parameters": [],
"recipient_campaign_id": 859,
"recipient_reward_amount": 5,
"recipient_reward_code": "",
"recipient_reward_discount_ratio": 0,
"recipient_reward_method": "voucher",
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 2,
"rounding_strategy": "undefined",
"sender_campaign_id": null,
"styling": {
"background_colour": null,
"background_image_filename": null,
"background_image_url": null,
"layout_style": "standard",
"primary_action_background_colour": null,
"primary_action_text_colour": null,
"secondary_action_background_colour": null,
"secondary_action_text_colour": null,
"text_colour": null
},
"supports_contribution": true,
"supports_user_segments": true,
"tags": null,
"target_count": 0,
"title": "Spend €150 and earn €5",
"type": "progress",
"user_segment_id": null,
"visible_to_all_user_segments": true,
"voucher_description": null,
"voucher_expiry_days": 90,
"voucher_image_url": null,
"voucher_notes": null,
"voucher_text": "Get your hands on a new ACME Voucher!",
"voucher_title": "Get your hands on a new ACME Voucher!"
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"aggregate_wallet_balance_shown": false,
"assignment_count": 0,
"balance_can_subzero": true,
"chain_id": 1762,
"created_date": "2020-03-10T09:11:34+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 5,
"custom_content": null,
"description": "Build up points in your wallet",
"element_styling": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 859,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_default": true,
"is_deleted": false,
"is_redeemable": false,
"last_modified_date": "2020-03-10T09:11:34+00:00",
"last_updated_date": null,
"max_manual_daily_amount": "200.00",
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"operator_type": "or",
"owner_code": null,
"parameters": [],
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 0,
"rounding_strategy": "round_down",
"spend_on_promotional_items": true,
"styling": {
"background_colour": null,
"background_image_filename": null,
"background_image_url": null,
"layout_style": null,
"primary_action_background_colour": null,
"primary_action_text_colour": null,
"secondary_action_background_colour": null,
"secondary_action_text_colour": null,
"text_colour": null
},
"tags": null,
"target_count": 0,
"title": "ACME Points Wallet",
"type": "points_wallet",
"visible_to_all_user_segments": true,
"voucher_description": null,
"voucher_expiry_days": 365,
"voucher_image_url": null,
"voucher_notes": null,
"voucher_text": null,
"voucher_title": null
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"assignment_count": 0,
"chain_id": 1762,
"created_date": "2020-02-18T14:45:59+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 2,
"custom_content": null,
"description": "The best loyalty programme",
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 809,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_default": false,
"is_deleted": false,
"last_modified_date": "2020-02-18T14:45:59+00:00",
"last_updated_date": null,
"loyalty_levels": [
{
"automated_level_logic": true,
"campaign_id": 809,
"description": "",
"id": 107,
"name": "New"
},
{
"automated_level_logic": true,
"campaign_id": 809,
"description": "",
"id": 108,
"name": "+ member"
},
{
"automated_level_logic": true,
"campaign_id": 809,
"description": "",
"id": 109,
"name": "Gold member"
}
],
"loyalty_rules": [
{
"action": "setLevel",
"action_is_repeatable": false,
"campaign_id": 809,
"id": 89,
"loyalty_level_id": 107,
"loyalty_level_name": "New",
"points_threshold": 0,
"title": "initial level rule",
"type": "initial"
},
{
"action": "setLevel",
"action_is_repeatable": true,
"campaign_id": 809,
"description": "",
"direction": "up",
"id": 90,
"loyalty_level_id": 108,
"loyalty_level_name": "+ member",
"operand_campaign_id": 2009,
"points_threshold": 300,
"title": "Set + level",
"type": "points_tracker",
"wallet_campaign_id": 2009
},
{
"action": "setLevel",
"action_is_repeatable": true,
"campaign_id": 809,
"description": "",
"direction": "up",
"id": 91,
"loyalty_level_id": 109,
"loyalty_level_name": "Gold member",
"operand_campaign_id": 2009,
"points_threshold": 850,
"title": "Set Gold member",
"type": "points_tracker",
"wallet_campaign_id": 2009
}
],
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"myprice_app_id": 27,
"owner_code": "LOYAL7456",
"recipient_campaign_id": null,
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"sender_campaign_id": null,
"styling": {
"background_colour": null,
"background_image_filename": null,
"background_image_url": null,
"layout_style": null,
"primary_action_background_colour": null,
"primary_action_text_colour": null,
"secondary_action_background_colour": null,
"secondary_action_text_colour": null,
"text_colour": null
},
"supports_user_segments": false,
"tags": null,
"target_count": 0,
"title": "ACME Loyalty Campaign",
"type": "loyalty",
"user_segment_id": null,
"visible_to_all_user_segments": true,
"voucher_description": null,
"voucher_expiry_days": 365,
"voucher_image_url": null,
"voucher_notes": null,
"voucher_text": "Your ACME loyalty voucher",
"voucher_title": null
},
{
"active": true,
"allows_user_to_claim_voucher": true,
"aggregate_wallet_balance_shown": false,
"assignment_count": 0,
"balance_can_subzero": true,
"chain_id": 1762,
"created_date": "2018-07-26T15:59:17+00:00",
"created_voucher_claimed_by_default": false,
"currency_id": 2,
"custom_content": null,
"description": "Converted wallet points come here",
"display_currency": null,
"display_currency_multiplication_factor": null,
"element_styling": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 238,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_default": true,
"is_deleted": false,
"is_redeemable": true,
"last_modified_date": "2018-07-26T15:59:17+00:00",
"last_updated_date": null,
"max_manual_daily_amount": "200.00",
"max_reward_quantity": 1,
"max_reward_quantity_unit": null,
"minimum_basket_total_value": 0,
"operator_type": "or",
"owner_code": "WALLETACME",
"parameters": [],
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 2,
"rounding_strategy": "neutral",
"spend_on_promotional_items": true,
"styling": {
"background_colour": null,
"background_image_filename": null,
"background_image_url": null,
"layout_style": null,
"primary_action_background_colour": null,
"primary_action_text_colour": null,
"secondary_action_background_colour": null,
"secondary_action_text_colour": null,
"text_colour": null
},
"tags": null,
"target_count": 0,
"title": "ACME Monetary Wallet",
"type": "wallet",
"visible_to_all_user_segments": true,
"voucher_description": null,
"voucher_expiry_days": 0,
"voucher_image_url": null,
"voucher_notes": null,
"voucher_text": null,
"voucher_title": null
}
],
"result_type": "get-campaigns"
}
}
Possible error responses
The following represents a list of possible error responses for the get-campaigns endpoint:
| Code | Name and Description | HTTP Status Code |
|---|---|---|
| 6 | no_valid_session The user needs to be logged in and a valid session key needs to be sent | 401 |
| 68 | permission_denied_or_non_existent This user has insufficient permissions for this object or the object does not exist. | 500 |
| 154 | user_id_invalid The user_id passed must be an integer up to 10 digits long | 400 |
| 217 | chain_id_not_found No record has been found for that chain_id | 400 |
| 228 | auth_method_invalid The given auth_method parameter has an invalid value. | 500 |
| 238 | myprice_app_not_found The MyPrice app you requested was not found. | 500 |
| 245 | campaign_id_not_present The campaign_id must be passed as a parameter. | 400 |
| 246 | campaign_id_not_found The campaign_id supplied could not be found. | 404 |
| 247 | campaign_id_invalid The campaign_rule_id passed must be an integer. | 400 |
| 264 | myprice_app_without_entity The requested MyPrice app does not have an entity associated with it. | 400 |
| 265 | authorization_invalid The given authorization header is invalid. | 400 |
| 266 | access_token_invalid The given access token is invalid. | 401 |
| 267 | no_valid_user A valid username needs to be specified. | 401 |
| 269 | no_myprice_app Myprice app is required. | 400 |
| 270 | user_not_found No user was found. | 404 |
| 405 | entity_mismatch The entities or chains supplied do not match. | 400 |
| 416 | multiple_parameter_mismatch Multiple parameters supplied when fewer are required. | 400 |
| 419 | parameter_invalid One of the parameters is invalid and should be in a different format. | 400 |
| 424 | access_denied Access is denied. | 400 |
| 449 | campaign_not_active The requested campaign is not active. | 400 |