v1

latestOpenAPI 3.0.1MIT2026-07-263151,3912.3 MB

Campaigns

List Campaigns

Retrieve a list of campaigns in a project.

The campaigns are returned sorted by creation date, with the most recent campaigns appearing first.

When you get a list of campaigns, you can optionally specify query parameters to customize the amount of campaigns returned per call using limit, which page of campaigns to return using page, sort the campaigns using the order query parameter and filter the results by the campaign_type.

This method will return an error when trying to return a limit of more than 100 campaigns.

get/v1/campaigns

Query parameters

limitinteger

Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items.

pageinteger

Which page of results to return. The lowest value is 1.

campaign_type'PROMOTION' | 'GIFT_VOUCHERS' | 'REFERRAL_PROGRAM' | 'DISCOUNT_COUPONS' | 'LOYALTY_PROGRAM'

This attribute allows filtering by campaign type.

expand'category' | 'access_settings_assignments'

Includes an expanded categories object in the response. If the Areas and Stores Enterprise feature is enabled, add access_settings_assignments to return assigned areas and stores.

campaign_status'DONE' | 'IN_PROGRESS' | 'FAILED' | 'DRAFT' | 'MODIFYING'

Status of the campaign. Allowed values: DONE, IN_PROGRESS, DRAFT, FAILED MODIFYING

Sorts the results by the status of the campaign.

is_referral_codeboolean

Lists campaigns that have or do not have referral codes.

Sorts the results that are or are not referral campaigns.

order'created_at' | '-created_at' | 'updated_at' | '-updated_at'

Sorts the results using one of the filtering options, where the dash - preceding a sorting option means sorting in a descending order.

junction'and' | 'or'

Logical Operator Between Filters. Filter by conditions set on the junction parameter indicating how the conditions should be accounted for in the query. An AND is an all-inclusive logical operator, meaning the AND operator displays a record if ALL the conditions separated by AND are TRUE, while an OR operator displays a record if ANY of the conditions separated by OR is TRUE.

Filters the results by various campaign properties.

{
  "validity_timeframe": {
    "conditions": {
      "$after": "2024-01-01T00:00:00.000Z",
      "$before": "2024-01-01T00:00:00.000Z"
    }
  },
  "created_date": {
    "conditions": {
      "$after": "2024-01-01T00:00:00.000Z",
      "$before": "2024-01-01T00:00:00.000Z"
    }
  },
  "updated_at": {
    "conditions": {
      "$after": "2024-01-01T00:00:00.000Z",
      "$before": "2024-01-01T00:00:00.000Z"
    }
  },
  "start_date": {
    "conditions": {
      "$after": "2024-01-01T00:00:00.000Z",
      "$before": "2024-01-01T00:00:00.000Z"
    }
  },
  "expiration_date": {
    "conditions": {
      "$after": "2024-01-01T00:00:00.000Z",
      "$before": "2024-01-01T00:00:00.000Z"
    }
  }
}

Filter by areas and stores IDs to return campaigns that are assigned to areas, stores, and all stores in an area.

{
  "filter": {
    "areas_ids": [
      "ar_0ab12cde3456789fgh"
    ],
    "area_all_stores_ids": [
      "ar_0ab12cde3456789fgh"
    ],
    "area_stores_ids": [
      "ars_0ab12cde3456789fgh"
    ]
  }
}

Response

Returns a dictionary with a campaign property that contains an array of campaigns. The maximum number of campaigns returned is determined by the limit query parameter. Each entry in the array is a separate campaign object. If no more campaigns are available, the resulting array on a given page will be empty.

objectstring

The type of the object represented by JSON. This object stores information about campaigns in a dictionary.

data_refstring

Identifies the name of the attribute that contains the array of campaign objects.

totalinteger

Total number of campaigns.

Example response

{
  "campaigns": [
    {
      "id": "camp_f7fBbQxUuTN7dI7tGOo5XMDA",
      "voucher": {
        "start_date": "2022-09-20T00:00:00.000Z",
        "expiration_date": "2022-09-30T00:00:00.000Z",
        "validity_timeframe": {
          "duration": "PT1H",
          "interval": "P2D"
        },
        "validity_hours": {
          "daily": [
            {
              "start_time": "12:00",
              "expiration_time": "14:00"
            }
          ]
        }
      },
      "validity_timeframe": {
        "duration": "PT1H",
        "interval": "P2D"
      },
      "validity_hours": {
        "daily": [
          {
            "start_time": "12:00",
            "expiration_time": "14:00"
          }
        ]
      },
      "start_date": "2022-09-20T00:00:00.000Z",
      "expiration_date": "2022-09-30T00:00:00.000Z",
      "created_at": "2021-12-01T08:00:50.038Z",
      "updated_at": "2022-09-20T09:18:19.623Z",
      "category_id": "cat_0b688929a2476386a7",
      "categories": [
        {
          "created_at": "2022-07-14T10:45:13.156Z",
          "updated_at": "2022-08-16T10:52:08.094Z"
        }
      ],
      "referral_program": {
        "custom_event": {
          "id": "ms_Ll9enAm2BCN0M1s4VxWobLFM"
        },
        "referee_reward": {
          "related_object_parent": {
            "id": "camp_kdxp3vf1clQ9CFs1jpqv3tZe"
          }
        }
      },
      "access_settings_assignments": {
        "data": [
          {
            "id": "arsca_0ef5ee192117ae2416",
            "area_id": "ar_0ea6cd7b781b8f857f",
            "area_store_id": "ars_0ec347e2016bed85f4",
            "created_at": "2024-06-25T19:04:16.260Z"
          }
        ]
      }
    }
  ]
}