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

# List Offerings

> This API returns a paginated list of offerings in the authenticated workspace. Use the query
parameters to filter by ID, name, status, tags, creation date, or creator, and to
request a sparse set of fields. Requires the `read:offers` scope.


#### Rate Limit

The rate limits are at the workspace level. Each endpoint allows 100 requests per minute, 300 requests per hour, and 600 requests per day.


## OpenAPI

````yaml /api/offerings/offerings.yaml get /v5/offers
openapi: 3.0.0
info:
  title: Offerings Public API
  version: 1.0.0
  description: >
    This API creates, updates, and lists offerings in a MoEngage

    workspace, and lists the personalization templates available for offering
    content.


    An offering is a targeted piece of personalized content — such as a
    promotional card or

    banner — that MoEngage Offer Decisioning serves to a chosen user segment
    within a

    scheduled window.


    **Tags**: Attach tags to an offering to group offerings and let Decision
    Policies select

    them by tag. Tags are referenced by tag ID and must already exist in the
    workspace.


    **Capping rules**: Limit how often an offering is delivered with two
    independent rules —

    an overall cap across all users and a per-user cap. Each rule uses a single
    time-based

    schedule (daily, weekly, or monthly) and a limit value.


    **Rate Limits**: The following limits apply to each endpoint, per workspace.

     | Rate Limit Name | Rate Limit |
     | :--- | :--- |
     | Requests per minute | The total number of requests per minute per workspace allowed is 100. |
     | Requests per hour | The total number of requests per hour per workspace allowed is 300. |
     | Requests per day | The total number of requests per day per workspace allowed is 600. |

     <Note>
       * Breaching any limit rejects the request with a `429` response that includes a `Retry-After` header.
       * A `429` response does not count against your quota.
     </Note>
servers:
  - url: https://api-{dc}.moengage.com
    variables:
      dc:
        default: '01'
        description: >
          MoEngage data center identifier. Replace it with the number assigned
          to your account, such as 01 (US), 02 (EU), 03 (India), 05 (Singapore),
          or 06 (Indonesia). For example, https://api-01.moengage.com.
        enum:
          - '01'
          - '02'
          - '03'
          - '05'
          - '06'
security: []
paths:
  /v5/offers:
    get:
      tags:
        - Public Offerings
      summary: List Offerings
      description: >
        This API returns a paginated list of offerings in the authenticated
        workspace. Use the query

        parameters to filter by ID, name, status, tags, creation date, or
        creator, and to

        request a sparse set of fields. Requires the `read:offers` scope.
      operationId: listPublicOfferings
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
          description: Filter by exact offering ID, including the `offer_` prefix.
          example: offer_683abc123def456789012345
        - name: name_contains
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
          description: >
            Case-insensitive substring match on the offering name. Maximum 100
            characters; a longer value returns `400 OUT_OF_RANGE`.
        - name: status_in
          in: query
          required: false
          schema:
            type: string
          description: >
            Comma-separated list of statuses to match (OR semantics — an
            offering is returned if its status matches any value).
            Case-insensitive. Valid values: `active`, `scheduled`, `expired`,
            `archived`, `draft`.  Example: `status_in=active,scheduled`.
        - name: tags
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: >
            Filter by tag ID (AND semantics — an offering is returned only if it
            has all specified tags). Repeat the parameter for each tag:
            `tags=tag_summer_sale&tags=tag_loyalty`.
        - name: created_date_gte
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Return offerings created on or after this date (`YYYY-MM-DD`).
        - name: created_date_lte
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Return offerings created on or before this date (`YYYY-MM-DD`).
        - name: created_by
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: >
            Filter by creator email address. Repeat the parameter for multiple
            creators:
            `created_by=john.doe@example.com&created_by=jane.smith@example.com`.
        - name: fields
          in: query
          required: false
          schema:
            type: string
          description: >
            Comma-separated list of fields to include for each item.
            Case-sensitive. Defaults to all six fields: `id`, `name`, `status`,
            `tags`, `created_at`, `created_by`. An unrecognized field name
            returns `400 INVALID_FIELDS_PARAM`. Example:
            `fields=id,name,status`.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
            maximum: 500
          description: >
            Page number to retrieve, starting at 1. Maximum 500; a higher value
            returns `400 OUT_OF_RANGE`. When the page number exceeds the total
            number of available pages, returns an empty `items` array (not an
            error).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page. Default 20, maximum 100.
        - name: X-MOE-Request-Id
          in: header
          required: false
          schema:
            type: string
            format: uuid
          description: >
            Client-supplied trace ID (UUID v4). The server echoes it in the
            `X-MOE-Request-Id` response header and records it in its logs, so
            you can correlate a client request with server-side activity. If you
            omit it, the server generates one.
      responses:
        '200':
          description: Paginated list of offerings.
          headers:
            X-MOE-Request-Id:
              schema:
                type: string
              description: >-
                Trace ID echoed from the request, or server-generated if none
                was sent.
            X-RateLimit-Limit:
              schema:
                type: integer
                example: 100
              description: Maximum requests allowed in the current per-minute window.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests remaining in the current per-minute window.
            X-RateLimit-Reset:
              schema:
                type: integer
              description: UTC epoch second when the current per-minute window resets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_id:
                    type: string
                    description: Server-generated UUID for tracing this response.
                  type:
                    type: string
                    enum:
                      - offer
                    description: Resource type discriminator. Always `offer`.
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/OfferingListItem'
                      pagination:
                        $ref: '#/components/schemas/PagePagination'
              example:
                response_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                type: offer
                data:
                  items:
                    - id: offer_683abc123def456789012345
                      name: Summer_Sale_Promo_2026
                      status: active
                      tags:
                        - tag_summer_sale
                        - tag_returning_users
                      created_at: '2026-06-01T08:30:00Z'
                      created_by: marketing-team@example.com
                  pagination:
                    page: 1
                    limit: 20
                    has_more: true
                    total_count: 42
        '400':
          description: >
            Invalid query parameter. Common error codes in
            `error.details[].code`:

            - `OUT_OF_RANGE` — `page` exceeds 500, `limit` exceeds 100, or
            `name_contains` exceeds 100 characters.

            - `INVALID_ENUM_VALUE` — unrecognized value in `status_in`.

            - `INVALID_FIELDS_PARAM` — unrecognized field name in `fields`.

            - `INVALID_TYPE` — `created_date_gte` or `created_date_lte` is not
            in `YYYY-MM-DD` format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_FAILED
                  message: One or more query parameters are invalid.
                  target: status_in
                  details:
                    - code: INVALID_ENUM_VALUE
                      target: status_in
                      message: >-
                        'invalid_status' is not a valid status. Allowed values:
                        active, scheduled, expired, archived, draft.
                  doc_url: https://docs.moengage.com/errors/VALIDATION_FAILED
                response_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '401':
          $ref: '#/components/responses/GatewayAuthError'
        '403':
          $ref: '#/components/responses/FeatureNotEnabled'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - basicAuth: []
components:
  schemas:
    OfferingListItem:
      description: >
        Summary of an offering returned by `GET /v5/offers`. Use the `fields`
        query parameter to request a subset of these fields.
      type: object
      properties:
        id:
          type: string
          description: >
            Offering identifier assigned at creation, including the `offer_`
            prefix. Use this value as the `offer_id` path parameter in `PATCH
            /v5/offers/{offer_id}`.
          example: offer_683abc123def456789012345
        name:
          type: string
          description: Display name of the offering, unique within the workspace.
          example: Summer_Sale_Promo_2026
        status:
          type: string
          description: >
            Current lifecycle status. `active` — live and eligible for
            decisioning. `scheduled` — the start time is in the future.
            `expired` — the expiry time has passed. `archived` — manually
            archived and excluded from decisioning. `draft` — not yet published.
          enum:
            - active
            - scheduled
            - expired
            - archived
            - draft
          example: active
        tags:
          type: array
          description: Tag IDs attached to the offering.
          items:
            type: string
          example:
            - tag_summer_sale
            - tag_returning_users
        created_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the offering was created.
          example: '2026-06-01T08:30:00Z'
        created_by:
          type: string
          description: Email address of the user who created the offering.
          example: marketing-team@example.com
    PagePagination:
      description: Pagination metadata included in list responses.
      type: object
      properties:
        page:
          type: integer
          description: Current page number, starting at 1.
          example: 1
        limit:
          type: integer
          description: Number of items per page, matching the `limit` parameter.
          example: 20
        has_more:
          type: boolean
          description: >
            Whether more pages exist beyond this one. Use this as the primary
            pagination signal — when `true`, increment `page` to fetch the next
            page.
          example: true
        total_count:
          type: integer
          format: int64
          description: Total number of items matching the applied filters.
          example: 42
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code in `ALL_CAPS_SNAKE_CASE`.
              example: VALIDATION_FAILED
            message:
              type: string
              description: Human-readable description of the error.
            target:
              type: string
              description: The field or parameter the error relates to.
            details:
              type: array
              description: >-
                Per-field errors. The create and update endpoints return every
                error together.
              items:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code for this field.
                  target:
                    type: string
                    description: Dot-notation path to the field that failed validation.
                  message:
                    type: string
                    description: Human-readable description of this field error.
            doc_url:
              type: string
              description: Link to documentation for this error code.
        response_id:
          type: string
          description: Server-generated UUID for tracing this response.
  responses:
    GatewayAuthError:
      description: >
        Authentication failed because the `Authorization` header is missing,
        malformed, or invalid (`401 UNAUTHORIZED`). This response is returned by
        the APISIX gateway.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNAUTHORIZED
              message: >-
                Authentication failed. Ensure the Authorization header is set to
                Basic with a valid API key.
              target: Authorization
            response_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    FeatureNotEnabled:
      description: >
        The Offer Decisioning feature is not enabled for this workspace (`403
        FORBIDDEN`). Contact your MoEngage account team to request access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: FORBIDDEN
              message: The Offer Decisioning feature is not enabled for this workspace.
              target: workspace
            response_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    RateLimited:
      description: >
        Rate limit exceeded (`429`). The `Retry-After` header gives the number
        of seconds until the most restrictive window resets. Limits are 100
        requests per minute, 300 per hour, and 600 per day, per workspace.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the most restrictive rate-limit window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMITED
              message: >-
                Rate limit exceeded: per-minute limit of 100 requests reached.
                Retry after 30 seconds.
            response_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    InternalError:
      description: An unexpected server-side error occurred (`500 INTERNAL_ERROR`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INTERNAL_ERROR
              message: >-
                An unexpected error occurred processing your request. Reference
                the X-MOE-Request-Id when contacting support.
            response_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    ServiceUnavailable:
      description: >
        The APISIX gateway is temporarily unable to route the request (`503`),
        for example when the upstream service is unreachable. The response body
        is HTML from the gateway, not JSON.
      content:
        text/html:
          schema:
            type: string
            example: >-
              <html><body><h1>503 Service Temporarily
              Unavailable</h1></body></html>
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >
        Authentication is done via Basic Auth. This requires a base64-encoded
        string of your credentials in the format 'username:password'.


        - **Username**: Use your MoEngage Workspace ID (also known as the App
        ID). You can find it in the MoEngage dashboard at **Settings** >
        **Account** > **APIs** > **Workspace ID (earlier app id)**.

        - **Password**: Use your API Key, which you can find within the
        **Personalize** tile.


        For more information on authentication and getting your credentials,
        refer
        [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

````