Link Search Menu Expand Document

Fetch a campaign by its ID

An example response for a successful get-campaign request:

    "result": {
        "code": 1,
        "status": "ok"
    "results": {
        "campaign": {
            "active": true,
            "allows_user_to_claim_voucher": true,
            "assigned_barcodes": [
            "assigned_barcodes_earn": [],
            "assigned_barcodes_spend": [],
            "assigned_business_ids": [
                    "id": 2797,
                    "name": "ACME Flagship stoere"
            "assigned_currencies": [],
            "assignment_count": 4,
            "assignment_count_by_type": {
                "barcode": 3,
                "brand": 0,
                "business": 1,
                "category": 0,
                "currency": 0,
                "gender": 0,
                "product": 0,
                "season": 0,
                "type": 0
            "cashback_ratio": "1.0000",
            "chain_id": 1743,
            "created_date": "2017-09-22T08:45:47+00:00",
            "created_voucher_claimed_by_default": false,
            "currency": {
                "code": "PTS",
                "display_position": "after",
                "id": 5,
                "name_en": "Points",
                "symbol": "pts"
            "custom_content": null,
            "description": "Get 1 point for each €1 spent",
            "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": 158,
            "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-11-11T14:43:07+00:00",
            "last_updated_by": {
                "name": "Dave Sevenoaks",
                "user_id": 21
            "last_updated_date": "2022-11-11T14:43:07+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": 157,
            "recipient_reward_amount": 1,
            "recipient_reward_discount_ratio": 0,
            "recipient_reward_method": "points",
            "return_reclaims_earned_rewards": true,
            "reward_priority": 0,
            "rounding_precision": 0,
            "rounding_strategy": "round_up",
            "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_contribution": true,
            "supports_user_segments": true,
            "tags": null,
            "target_count": 0,
            "title": "Earn points on every purchase",
            "type": "cashback",
            "user_progress": {
                "award_count": 2,
                "total_amount_awarded": 251
            "user_segment_id": "AXIYnQplKpCtyKmmd8Hn",
            "visible_to_all_user_segments": false,
            "voucher_description": null,
            "voucher_expiry_days": 0,
            "voucher_image_url": null,
            "voucher_notes": null,
            "voucher_text": "Your cashback amount",
            "voucher_title": null
        "result_type": "get-campaign"


  • Call name: get-campaign
  • Endpoint URL:
  • Request methods: GET
  • Response Content-Type: application/json
  • Auth required: yes

The get-campaign endpoint is used to fetch a campaign by its ID. The campaign ID is passed as a parameter to the API call. The call returns a campaign object. 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 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-campaign 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.

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 access to the chain to which the user is connected.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.
  • User authentication: a session generated by an end-user login.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
campaign_id mandatory (integer) The ID of the Campaign the user is querying.
chain_id mandatory when querying user specific information (integer) 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_identifer mandatory when querying user specific information The Spaaza unique ID (user_id), member_number (user code), username (email) or identity in a third-party authentication system (authentication_point_identifier/ auxiliary_identifer) of the user for whom the campaign is being requested.


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.

Possible error responses

The following represents a list of possible error responses for the interact-campaign 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
68 permission_denied_or_non_existent
This user has insufficient permissions for this object or the object does not exist.
154 user_id_invalid
The user_id passed must be an integer up to 10 digits long
217 chain_id_not_found
No record has been found for that chain_id
228 auth_method_invalid
The given auth_method parameter has an invalid value.
238 myprice_app_not_found
The MyPrice app you requested was not found.
245 campaign_id_not_present
The campaign_id must be passed as a parameter.
246 campaign_id_not_found
The campaign_id supplied could not be found.
247 campaign_id_invalid
The campaign_rule_id passed must be an integer.
264 myprice_app_without_entity
The requested MyPrice app does not have an entity associated with it.
265 authorization_invalid
The given authorization header is invalid.
266 access_token_invalid
The given access token is invalid.
267 no_valid_user
A valid username needs to be specified.
269 no_myprice_app
Myprice app is required.
270 user_not_found
No user was found.
405 entity_mismatch
The entities or chains supplied do not match.
416 multiple_parameter_mismatch
Multiple parameters supplied when fewer are required.
419 parameter_invalid
One of the parameters is invalid and should be in a different format.
424 access_denied
Access is denied.
449 campaign_not_active
The requested campaign is not active.