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

# List Offers

> Retrieve a paginated list of all offers on your account.

Returns all offers associated with your account. By default, archived offers are excluded unless explicitly requested via the `status` filter.

## Query Parameters

<ParamField query="status" type="string" optional>
  Filter offers by status. Accepted values: `active`, `paused`, `archived`. When omitted, all non-archived offers are returned.
</ParamField>

<ParamField query="external_id" type="string" optional>
  Filter offers by their exact external platform ID.
</ParamField>

<ParamField query="external_platform" type="string" optional>
  Filter offers by external platform. Accepted values: `tune`, `everflow`.
</ParamField>

<ParamField query="page" type="integer" optional default="1">
  Page number for pagination.
</ParamField>

<ParamField query="per_page" type="integer" optional default="50">
  Number of offers per page. Maximum value is `100`.
</ParamField>

## Response Fields

<ResponseField name="offers" type="array">
  An array of offer objects.

  <Expandable title="Offer object properties">
    <ResponseField name="id" type="string">
      Unique identifier for the offer.
    </ResponseField>

    <ResponseField name="slug" type="string">
      Human-readable unique slug for the offer, in the form `ofr_{slugified-name}_{hex}`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the offer.
    </ResponseField>

    <ResponseField name="tracking_url" type="string">
      The tracking/click URL for this offer.
    </ResponseField>

    <ResponseField name="external_platform" type="string">
      The external affiliate platform. One of `tune`, `everflow`, or `null`.
    </ResponseField>

    <ResponseField name="external_id" type="string">
      The offer ID on the external platform.
    </ResponseField>

    <ResponseField name="advertiser_id" type="string">
      The advertiser ID associated with the offer.
    </ResponseField>

    <ResponseField name="advertiser_name" type="string">
      The advertiser name associated with the offer.
    </ResponseField>

    <ResponseField name="payout" type="float">
      Payout amount for the offer.
    </ResponseField>

    <ResponseField name="payout_type" type="string">
      Payout model. One of `cpa` or `cpc`.
    </ResponseField>

    <ResponseField name="filter_bots" type="boolean">
      Whether bot click filtering is enabled.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the offer: `active`, `paused`, or `archived`.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Custom key-value metadata attached to the offer.
    </ResponseField>

    <ResponseField name="excluded_days_of_week" type="array">
      Weekday names (lowercase `monday` through `sunday`) on which the SMS ad server will not send this offer, evaluated in the contact's local time. Empty array when none are excluded.
    </ResponseField>

    <ResponseField name="day_parting_enabled" type="boolean">
      Whether intra-day send-window restrictions apply to this offer.
    </ResponseField>

    <ResponseField name="day_parting" type="object">
      Allow-list of send windows keyed by lowercase weekday, evaluated in Eastern Time. Shape: `{"monday": [{"start": "HH:MM", "end": "HH:MM"}]}`. Empty object when no windows are configured.
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      ISO 8601 timestamp of when the offer was created.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      ISO 8601 timestamp of the last update.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="Pagination properties">
    <ResponseField name="page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      Number of results per page.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of offers matching the query.
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
      Total number of pages available.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET "https://api.tracklysms.com/api/v2/offers?status=active&page=1&per_page=25" \
      -H "X-Api-Key: trk_your_api_key_here"
    ```

    ```python Python theme={null}
    import requests

    response = requests.get(
        "https://api.tracklysms.com/api/v2/offers",
        headers={"X-Api-Key": "trk_your_api_key_here"},
        params={
            "status": "active",
            "page": 1,
            "per_page": 25
        }
    )

    data = response.json()
    for offer in data["offers"]:
        print(offer["name"], offer["status"])
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.tracklysms.com/api/v2/offers?status=active&page=1&per_page=25",
      {
        headers: {
          "X-Api-Key": "trk_your_api_key_here"
        }
      }
    );

    const data = await response.json();
    console.log(data.offers);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "offers": [
      {
        "id": "664f1a2b3c4d5e6f7a8b9c0d",
        "slug": "ofr_summer-promo_a1b2c3",
        "name": "Summer Promo",
        "tracking_url": "https://track.example.com/click?offer_id=123",
        "external_platform": "tune",
        "external_id": "4521",
        "advertiser_id": "adv_882",
        "advertiser_name": "Acme Health",
        "payout": 2.50,
        "payout_type": "cpa",
        "filter_bots": true,
        "status": "active",
        "metadata": {
          "vertical": "health",
          "geo": "US"
        },
        "excluded_days_of_week": ["saturday", "sunday"],
        "day_parting_enabled": true,
        "day_parting": {
          "monday": [{"start": "09:00", "end": "17:00"}]
        },
        "created_at": "2025-11-01T14:30:00",
        "updated_at": "2025-12-15T09:12:00"
      },
      {
        "id": "664f1a2b3c4d5e6f7a8b9c0e",
        "slug": "ofr_winter-sale_d4e5f6",
        "name": "Winter Sale",
        "tracking_url": "https://track.example.com/click?offer_id=456",
        "external_platform": null,
        "external_id": null,
        "advertiser_id": null,
        "advertiser_name": null,
        "payout": 1.75,
        "payout_type": "cpc",
        "filter_bots": false,
        "status": "active",
        "metadata": {},
        "excluded_days_of_week": [],
        "day_parting_enabled": false,
        "day_parting": {},
        "created_at": "2025-12-01T08:00:00",
        "updated_at": "2025-12-01T08:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 2,
      "total_pages": 1
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Invalid credentials",
    "code": "invalid_credentials"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code            | Description                                                                |
| ----------- | --------------------- | -------------------------------------------------------------------------- |
| 401         | `invalid_credentials` | API key is missing or invalid.                                             |
| 403         | `account_suspended`   | Your account is suspended. Resolve outstanding billing or contact support. |
| 429         | `rate_limited`        | Request throttled; retry with exponential backoff after the window resets. |
| 500         | `server_error`        | An unexpected error occurred on the server.                                |

## Next Steps

<CardGroup cols={2}>
  <Card title="Offers Overview" icon="tag" href="/guides/offers/overview">
    Manage offers and payouts
  </Card>

  <Card title="Record Revenue" icon="dollar-sign" href="/api-reference/v2/revenue/record-revenue">
    Track revenue for your offers
  </Card>
</CardGroup>