> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yuko.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List booster campaigns

> Retrieves a paginated list of your organisation's active booster campaigns.

Results are sorted by `created_at`, newest first. Draft, completed, cancelled and disabled campaigns are not returned. The list is filtered by status only, not by date, so check `starts_at`, `ends_at` and `schedule` to see whether a campaign is running right now.

<Info>Requires the `read:booster_campaigns` scope. See [Scopes](/developer/api/scopes).</Info>

## Query parameters

<ParamField query="per_page" type="integer" default={20}>
  The number of results per page. Values above `100` are capped at `100`.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  The page number to retrieve. See [Classic pagination](/developer/api/classic-pagination).
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  The active booster campaigns on this page.

  <Expandable title="booster campaign properties">
    <ResponseField name="uuid" type="string<uuid>">
      Unique UUID identifier for the booster campaign.
    </ResponseField>

    <ResponseField name="name" type="string">
      The campaign name.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      The campaign description.
    </ResponseField>

    <ResponseField name="type" type="enum<string>">
      The booster campaign type. One of `multiplier`, `bonus_flat`, `spending_goal`, `order_frequency`, `streak`, `multi_action`, `dormant_reactivation`, `first_purchase_boost`, `product_collection_multiplier`.
    </ResponseField>

    <ResponseField name="status" type="string">
      The campaign status. Always `active` for this endpoint.
    </ResponseField>

    <ResponseField name="stackable" type="boolean">
      Whether the campaign can stack with other booster campaigns.
    </ResponseField>

    <ResponseField name="schedule" type="object | null">
      When the campaign runs, for example `type` (`evergreen`, `one_time` or `recurring`), recurrence settings, `days_of_week`, and `active_hours_start` / `active_hours_end`.
    </ResponseField>

    <ResponseField name="targeting" type="object | null">
      Targeting settings, such as the `products` and `collections` the campaign applies to.
    </ResponseField>

    <ResponseField name="product_scope" type="object | null">
      The product scope the campaign applies to.
    </ResponseField>

    <ResponseField name="display" type="object">
      Storefront display settings, such as `show_in_widget` and `labels`. Always includes an `icon` object (or `null`) with `source`, `slug`, `id` and `url`, the same shape as a reward's icon.
    </ResponseField>

    <ResponseField name="config" type="object | null">
      Type-specific settings. Structure varies by `type`, for example `milestones` for spending goals and order frequency, or `actions` and `completion_logic` for multi-action challenges.
    </ResponseField>

    <ResponseField name="starts_at" type="string<date-time> | null">
      When the campaign starts (ISO 8601).
    </ResponseField>

    <ResponseField name="ends_at" type="string<date-time> | null">
      When the campaign ends (ISO 8601), or `null` if it has no end date.
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time> | null">
      When the campaign was created (ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="pagination" type="object">
      Pagination details. See [Classic pagination](/developer/api/classic-pagination).

      <Expandable title="pagination properties">
        <ResponseField name="current_page" type="integer">The page returned.</ResponseField>
        <ResponseField name="per_page" type="integer">The number of records per page.</ResponseField>
        <ResponseField name="total" type="integer">The total number of records.</ResponseField>
        <ResponseField name="last_page" type="integer">The number of the last page.</ResponseField>
        <ResponseField name="has_more" type="boolean">`true` if there are more pages after this one.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | Code | When |
| :- | :- | :- |
| `401` | `missing_token`, `invalid_token` | The API key is missing, wrong or revoked. |
| `403` | `insufficient_scope` | The key doesn't have `read:booster_campaigns`. |
| `429` | | The key exceeded the [rate limit](/developer/api/rate-limits). |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.yukoapp.com/api/v1/public/booster-campaigns?per_page=20" \
    --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ per_page: "20" });

  const response = await fetch(
    `https://api.yukoapp.com/api/v1/public/booster-campaigns?${params}`,
    {
      method: "GET",
      headers: {
        Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      },
    }
  );

  const data = await response.json();
  ```

  ```php PHP theme={null}
  $query = http_build_query(["per_page" => 20]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/booster-campaigns?{$query}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "uuid": "5b1f2c9e-7d3a-4e8b-9c11-2f6a8d4e0b73",
        "name": "Spend $100 this month",
        "description": "Earn bonus points when you spend $100 in 30 days.",
        "type": "spending_goal",
        "status": "active",
        "stackable": false,
        "schedule": {
          "type": "evergreen"
        },
        "targeting": null,
        "product_scope": null,
        "display": {
          "show_in_widget": true,
          "icon": null
        },
        "config": {
          "time_window_days": 30,
          "milestones": [
            { "id": "m1", "spending_amount": 100, "label": "Spend $100" }
          ]
        },
        "starts_at": "2026-10-01T00:00:00+00:00",
        "ends_at": null,
        "created_at": "2026-10-01T09:00:00+00:00"
      }
    ],
    "meta": {
      "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1,
        "has_more": false
      }
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "insufficient_scope",
      "message": "Your API token does not have the required 'booster_campaigns' scope for this action"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.