# List Offers

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v3/offers:
    get:
      summary: List Offers
      deprecated: false
      description: >-
        Returns offers list.


        ## Query Parameters


        | Parameter            | Type      | Default    |
        Description                                                                                                                                                                                                                                             
        |

        |----------------------|-----------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

        | scope                | enum      | `standard` | When present, only
        offers from given [scope](doc-341649#scoping) will be
        returned                                                                                                                     
        |

        | types                | string[]  | null       | When present, only
        offers of given [types](doc-341695#offers-types) will be
        returned                                                                                                              
        |

        | per_page             | integer   | 100        | Number of results to
        be returned per request (100 is the
        maximum)                                                                                                                                                                                       
        |

        | page_no              | integer   | 1          | Number of results
        page                                                                                                                                                                                                                                  
        |

        | sort_by              | string    | "name"     | What attribute should
        results be sorted by? Supported attributes are: `["name",
        "usable_since", "usable_until", "visible_since", "visible_until",
        "created_at", "updated_at",
        "archived_at"]`                                                           
        |

        | sort_direction       | string    | "asc"      | Direction of sorting:
        "asc" or
        "desc"                                                                                                                                                                                                                   
        |

        | collection_ids       | integer[] | null       | When present, only
        offers belonging to at least one of given collections will be
        returned                                                                                                                                                               
        |

        | store_ids            | integer[] | null       | When present, only
        offers belonging to at at least one of given store_id will be
        returned                                                                                                                                                               
        |

        | status               | enum      | null       | When present, only
        offers with this status will be returned. See:
        [statuses](doc-341695#offers-statuses)                                                                                          
        |

        | campaign_id          | integer   | null       | When present, only
        offers with this campaign_id will be
        returned                                                                                                                                                                                        
        |

        | audience_id          | integer   | null       | When present, only
        offers with this audience_id will be
        returned                                                                                                                                                                                        
        |

        | search               | string    | null       | When present, only
        offers that match the query string will be
        returned                                                                                                                                                                                  
        |

        | extras               | object    | null       | When present, only
        offers that match given values will be returned. See:
        below                                                                                                                                                                          
        |

        | ids                  | integer[] | null       | When present, only
        offers having one of provided IDs will be
        returned                                                                                                                                                                                   
        |

        | without_collection   | boolean   | false      | When present, only
        offers without collections will be
        returned                                                                                                                                                                                          
        |

        | without_audience_id  | boolean   | false      | When present, only
        offers without audiences will be
        returned                                                                                                                                                                                            
        |

        | without_campaign_id  | boolean   | false      | When present, only
        offers without campaigns will be
        returned                                                                                                                                                                                            
        |

        | without_store        | boolean   | false      | When present, only
        offers without store will be
        returned                                                                                                                                                                                                
        |

        | with_archived        | boolean   | false      | When present, also
        archived offers will be
        returned                                                                                                                                                                                                     
        |

        | only_archived        | boolean   | false      | When present, only
        archived offers will be
        returned                                                                                                                                                                                                     
        |

        | visible_since_after  | datetime  | null       | When present, only
        offers with greater visible_since will be
        returned                                                                                                                                                                                   
        |

        | visible_since_before | datetime  | null       | When present, only
        offers with lesser visible_since will be
        returned                                                                                                                                                                                    
        |

        | visible_until_after  | datetime  | null       | When present, only
        offers with greater visible_until will be
        returned                                                                                                                                                                                   
        |

        | visible_until_before | datetime  | null       | When present, only
        offers with lesser visible_until will be
        returned                                                                                                                                                                                    
        |

        | usable_since_after   | datetime  | null       | When present, only
        offers with greater usable_since will be
        returned                                                                                                                                                                                    
        |

        | usable_since_before  | datetime  | null       | When present, only
        offers with lesser usable_since will be
        returned                                                                                                                                                                                     
        |

        | usable_until_before  | datetime  | null       | When present, only
        offers with lesser usable_until will be
        returned                                                                                                                                                                                     
        |


        All parameters are optional.


        ### Filtering by `extras`


        It is possible to filter offers by their `extra` attribute(s).


        Syntax: `?extras[<attribute>]=(!)<value>`


        * Values are always compared as strings

        * "!" may be used as a value prefix to achieve negative filtering

        * Multiple attributes may be filtered simultaneously


        Example 1: `?extras[category]=Food`


        It will return offers that have `extras["category"].toString() =
        'Food'`.


        Example 2: `?extras[category_id]=!3&extras[type]=external`


        It will return offers that have `extras["category_id"].toString() != '3'
        && extras["type"].toString() == 'external'`.


        ## Response Body


        Key | Type | Optional? | Description

        --------- | --------- | -------- | ---------

        offers | Offer[] | no (may be empty)| See [Offer
        model](doc-341695#offer-model) 

        pagination_info | PaginationInfo | no| See [Pagination info
        model](doc-341638)


        ## Example


        ```shell

        curl \

        "https://api.mpc.placewise.com/v3/infinity-mall/offers?per_page=5&page_no=1&sort_by=name&sort_direction=desc"
        \
            -H 'content-type: application/json' \
            -H 'x-client-authorization: B7t9U9tsoWsGhrv2ouUoSqpM' \
            -H 'x-product-name: default' \
            -H 'x-user-agent: CURL manual test'
        ```


        When successful, returns a list of [offers](doc-341695#offer-model) and 

        [Pagination Info](doc-341638)


        ```json

        {
          "offers": [
            {
              // (...) - see Offer model
            }
          ],
          "pagination_info": {
              // (...) - see Pagination info model
          }
        }

        ```
      tags:
        - API Reference/Management API/Offers/Offers
      parameters:
        - name: publication_status
          in: query
          description: >-
            When present, only records of given publication status will be
            returned
          required: false
          example: published
          schema:
            type: string
            enum:
              - published
              - unpublished
              - draft
              - scheduled
              - expired
            x-apidog-enum:
              - name: ''
                value: published
                description: ''
              - name: ''
                value: unpublished
                description: ''
              - name: ''
                value: draft
                description: ''
              - name: ''
                value: scheduled
                description: ''
              - name: ''
                value: expired
                description: ''
        - name: excluded_publication_status
          in: query
          description: >-
            When present, only records with publication status different than
            given will be returned
          required: false
          example: expired
          schema:
            type: string
        - name: cms_tag_ids[]
          in: query
          description: >-
            When present, only records having one of specified tag ids will be
            returned
          required: false
          example:
            - '7'
            - '10'
          schema:
            type: array
            items:
              type: integer
        - name: scope
          in: query
          description: ''
          required: false
          example: informational
          schema:
            type: string
        - name: Content-Type
          in: header
          description: '[Details](doc-341635)'
          required: true
          example: application/json
          schema:
            type: string
            default: application/json
            const: application/json
        - name: X-User-Agent
          in: header
          description: Arbitrary identifier of your client. [Details](doc-341635)
          required: true
          example: '{{X_USER_AGENT}}'
          schema:
            type: string
            default: '{{X_USER_AGENT}}'
        - name: X-Product-Name
          in: header
          description: API Product for API context. [Details](doc-341635)
          required: true
          example: '{{PRODUCT_NAME}}'
          schema:
            type: string
            default: '{{PRODUCT_NAME}}'
        - name: X-Loyalty-Club-Slug
          in: header
          description: LoyaltyClub for API context. [Details](doc-342138)
          required: false
          example: '{{LOYALTY_CLUB_SLUG}}'
          schema:
            type: string
            default: '{{LOYALTY_CLUB_SLUG}}'
        - name: X-Customer
          in: header
          description: Customer for API context.  [Details](doc-342139)
          required: false
          example: '{{CUSTOMER_ID}}'
          schema:
            type: string
            default: '{{CUSTOMER_ID}}'
        - name: Authorization
          in: header
          description: '[Member](doc-342129) or [User](doc-342130) Authorization.'
          required: false
          example: Bearer {{_OAUTH_TOKEN}}
          schema:
            type: string
            default: Bearer {{_OAUTH_TOKEN}}
        - name: X-Client-Authorization
          in: header
          description: '[Token](doc-342128) Authorization.'
          example: '{{API_TOKEN}}'
          schema:
            type: string
            default: '{{API_TOKEN}}'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  offers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Offer'
                x-apidog-orders:
                  - offers
                required:
                  - offers
                x-apidog-ignore-properties: []
              example:
                offers:
                  - type: exclusive
                    status: published
                    name:
                      en: Text
                    description: null
                    internal_name: null
                    notes: null
                    usable_since: null
                    usable_until: null
                    visible_since: '2024-05-01T10:00:00.0Z'
                    visible_until: '2024-05-31T10:00:00.0Z'
                    collection_ids: []
                    images: []
                    url: promotions/1019680
                    store_ids:
                      - 1027509
                      - 36
                    store_id: 1027509
                    stores:
                      - Espresso House
                      - Gift shop
                    audience_id: 263059
                    campaign_id: null
                    external_url: null
                    maximum_uses_per_user: 1
                    maximum_grants_per_user: 1
                    periodic_usage: null
                    stock: 10
                    usage_authorization_token: null
                    usage_authorization_token_required: false
                    external_master: null
                    image_template: null
                    display_schemas:
                      list:
                        header:
                          type: reference
                          value: name
                        body:
                          type: reference
                          value: description
                        caption:
                          type: reference
                          value: stores
                      details:
                        header:
                          type: reference
                          value: name
                        body:
                          type: reference
                          value: description
                        caption:
                          type: reference
                          value: stores
                    read_more: null
                    activation_texts: null
                    extras: {}
                    files:
                      - null
                    archived_at: null
                    uses_count: 0
                    grants_count: 0
                    publication_status: expired
                    cms_tag_ids: []
                    authorization_code_displayed: true
                  - type: parking
                    status: published
                    name:
                      en: Text
                    description: null
                    internal_name: null
                    notes: null
                    usable_since: null
                    usable_until: null
                    visible_since: '2024-05-01T10:00:00.0Z'
                    visible_until: '2024-05-31T10:00:00.0Z'
                    collection_ids: []
                    images: []
                    url: promotions/1019680
                    store_ids:
                      - 1027509
                      - 36
                    store_id: 1027509
                    stores:
                      - Espresso House
                      - Gift shop
                    audience_id: 263059
                    campaign_id: null
                    external_url: null
                    maximum_uses_per_user: 1
                    maximum_grants_per_user: 1
                    periodic_usage: null
                    stock: 10
                    usage_authorization_token: null
                    usage_authorization_token_required: false
                    external_master: null
                    image_template: null
                    display_schemas:
                      list:
                        header:
                          type: reference
                          value: name
                        body:
                          type: reference
                          value: description
                        caption:
                          type: reference
                          value: stores
                      details:
                        header:
                          type: reference
                          value: name
                        body:
                          type: reference
                          value: description
                        caption:
                          type: reference
                          value: stores
                    read_more: null
                    activation_texts: null
                    extras: {}
                    files:
                      - identifier: '1'
                        created_at: '2022-11-09T15:46:00.252860Z'
                        image_details:
                          width: 64560054
                          height: 48057366
                      - null
                    archived_at: null
                    uses_count: 0
                    grants_count: 0
                    publication_status: expired
                    cms_tag_ids: []
                    authorization_code_displayed: false
                  - type: birthday
                    status: published
                    name:
                      en: Text
                    description: null
                    internal_name: null
                    notes: null
                    usable_since: null
                    usable_until: null
                    visible_since: '2024-05-01T10:00:00.0Z'
                    visible_until: '2024-05-31T10:00:00.0Z'
                    collection_ids: []
                    images: []
                    url: promotions/1019680
                    store_ids:
                      - 1027509
                      - 36
                    store_id: 1027509
                    stores:
                      - Espresso House
                      - Gift shop
                    audience_id: 263059
                    campaign_id: null
                    external_url: null
                    maximum_uses_per_user: 1
                    maximum_grants_per_user: 1
                    periodic_usage: null
                    stock: 10
                    usage_authorization_token: null
                    usage_authorization_token_required: false
                    external_master: null
                    image_template: null
                    display_schemas:
                      list:
                        header:
                          type: reference
                          value: name
                        body:
                          type: reference
                          value: description
                        caption:
                          type: reference
                          value: stores
                      details:
                        header:
                          type: reference
                          value: name
                        body:
                          type: reference
                          value: description
                        caption:
                          type: reference
                          value: stores
                    read_more: null
                    activation_texts: null
                    extras: {}
                    files:
                      - identifier: '1'
                        created_at: '2022-11-09T15:46:00.252860Z'
                        image_details: null
                    archived_at: null
                    uses_count: 0
                    grants_count: 0
                    publication_status: expired
                    cms_tag_ids: []
                    authorization_code_displayed: false
          headers: {}
          x-apidog-name: Success
      security: []
      x-apidog-folder: API Reference/Management API/Offers/Offers
      x-apidog-status: pending
      x-run-in-apidog: https://app.eu.apidog.com/web/project/346351/apis/api-3511088-run
components:
  schemas:
    Offer:
      description: Represents a single offer
      type: object
      required:
        - id
        - created_at
        - updated_at
        - type
        - statuss
        - name
        - url
        - maximum_uses_per_user
        - stock
        - usage_authorization_token_required
        - files
        - uses_count
        - grants_count
        - publication_status
        - authorization_code_displayed
      properties:
        id: &ref_1
          $ref: '#/components/schemas/id'
          description: Primary identifier of the record
          readOnly: true
        created_at: &ref_2
          type: string
          description: Time at which the record was created
          format: date-time
          readOnly: true
          examples:
            - '2022-11-15T16:25:58.099512Z'
        updated_at: &ref_3
          type: string
          description: Time at which the record was updated for the last time
          format: date-time
          readOnly: true
          examples:
            - '2022-11-15T16:25:58.099512Z'
        type:
          description: The type of the offer.
          $ref: '#/components/schemas/offer_type'
        statuss:
          description: >-
            The current workflow status of the offer (e.g., 'published' or
            'draft').
          $ref: '#/components/schemas/cms.status'
        name: &ref_0
          description: The name of the offer, localized by language code.
          $ref: '#/components/schemas/LocalizedContent'
        description:
          description: >-
            The description of the offer, localized by language code. Can be
            null if no description is provided.
          anyOf:
            - *ref_0
            - type: 'null'
        internal_name:
          type: string
          description: An internal name for the offer, not typically shown to users.
          examples:
            - null
          nullable: true
        notes:
          type: string
          description: Internal notes or comments about the offer.
          examples:
            - null
          nullable: true
        usable_since:
          type: string
          format: date-time
          description: The start date and time from which the offer can be used.
          examples:
            - null
          nullable: true
        usable_until:
          type: string
          format: date-time
          description: The end date and time until which the offer can be used.
          examples:
            - null
          nullable: true
        visible_since:
          type: string
          format: date-time
          description: The date and time the offer becomes visible to users.
          examples:
            - '2024-05-01T10:00:00.000000Z'
          nullable: true
        visible_until:
          type: string
          format: date-time
          description: The date and time the offer ceases to be visible to users.
          examples:
            - '2024-05-31T10:00:00.000000Z'
          nullable: true
        collection_ids:
          type: array
          description: A list of collection IDs this offer belongs to.
          items:
            type: integer
          examples:
            - []
        images:
          type: array
          description: A list of associated image objects.
          items:
            type: string
          examples:
            - []
        url:
          type: string
          description: The relative URL path for this offer.
          examples:
            - promotions/1019680
        store_ids:
          type: array
          description: A list of store IDs where the offer is valid.
          items:
            type: integer
          examples:
            - - 1027509
              - 36
        store_id:
          type: integer
          description: The primary store ID associated with the offer.
          examples:
            - 1027509
          nullable: true
        stores:
          type: array
          description: A list of store names where the offer is valid.
          items:
            type: string
          examples:
            - - Espresso House
              - Gift shop
        audience_id:
          type: integer
          description: The ID of the target audience for this offer.
          examples:
            - 263059
          nullable: true
        campaign_id:
          type: integer
          description: The ID of the campaign this offer is part of.
          examples:
            - null
          nullable: true
        external_url:
          type: string
          description: An external URL related to the offer, if any.
          examples:
            - null
          nullable: true
        maximum_uses_per_user:
          type: integer
          description: The maximum number of times a single user can use this offer.
          examples:
            - 1
        maximum_grants_per_user:
          type: integer
          description: >-
            The maximum number of times an offer can be granted to a single
            user.
          examples:
            - 1
          nullable: true
        periodic_usage:
          type: object
          description: Rules for periodic usage limits, if applicable.
          examples:
            - null
          x-apidog-orders: []
          properties: {}
          x-apidog-ignore-properties: []
          nullable: true
        stock:
          type: integer
          description: The total number of available offers (stock level).
          examples:
            - 10
        usage_authorization_token:
          type: string
          description: A token required for authorizing the use of the offer.
          examples:
            - null
          nullable: true
        usage_authorization_token_required:
          type: boolean
          description: Indicates if an authorization token is required to use the offer.
          examples:
            - false
        external_master:
          type: string
          description: Reference to an external master system, if any.
          examples:
            - null
          nullable: true
        read_more:
          type: object
          description: Content for a 'read more' section, if any.
          examples:
            - null
          x-apidog-orders: []
          properties: {}
          x-apidog-ignore-properties: []
          nullable: true
        activation_texts:
          type: object
          description: Texts related to the activation of the offer.
          examples:
            - null
          x-apidog-orders: []
          properties: {}
          x-apidog-ignore-properties: []
          nullable: true
        extras:
          type: object
          description: A key-value object for extra, non-standard data.
          examples:
            - {}
          properties: {}
          x-apidog-orders: []
          x-apidog-ignore-properties: []
        files:
          type: array
          description: A list of files associated with the offer, such as images.
          items:
            $ref: '#/components/schemas/File'
        archived_at:
          type: string
          format: date-time
          description: The timestamp when the offer was archived, if applicable.
          examples:
            - null
          nullable: true
        uses_count:
          type: integer
          description: The total number of times the offer has been used.
          examples:
            - 0
        grants_count:
          type: integer
          description: The total number of times the offer has been granted to users.
          examples:
            - 0
        publication_status:
          type: string
          enum:
            - expired
            - draft
            - published
          description: The calculated publication status based on visibility dates.
          examples:
            - expired
        cms_tag_ids:
          type: array
          description: A list of CMS tag IDs associated with the offer.
          items:
            type: string
          examples:
            - []
        authorization_code_displayed:
          type: boolean
          default: true
      x-apidog-orders:
        - 01K578X0ZR9T8KPKG7YV243MTM
        - type
        - statuss
        - name
        - description
        - internal_name
        - notes
        - usable_since
        - usable_until
        - visible_since
        - visible_until
        - collection_ids
        - images
        - url
        - store_ids
        - store_id
        - stores
        - audience_id
        - campaign_id
        - external_url
        - maximum_uses_per_user
        - maximum_grants_per_user
        - periodic_usage
        - stock
        - usage_authorization_token
        - usage_authorization_token_required
        - external_master
        - read_more
        - activation_texts
        - extras
        - files
        - archived_at
        - uses_count
        - grants_count
        - publication_status
        - cms_tag_ids
        - authorization_code_displayed
      x-apidog-refs:
        01K578X0ZR9T8KPKG7YV243MTM:
          $ref: '#/components/schemas/Base%20record%20attributes'
      x-apidog-ignore-properties:
        - id
        - created_at
        - updated_at
      x-apidog-folder: ''
    File:
      type: object
      properties:
        url:
          type: string
          format: uri
          readOnly: true
          examples:
            - https://example.com/image.png
        identifier:
          type: string
          description: Only present when parent record has many files
          examples:
            - '1'
        mime_type:
          type: string
          examples:
            - image/jpeg
          readOnly: true
          description: Only present in certain circumstances
          nullable: true
        created_at:
          type: string
          format: date-time
          examples:
            - '2022-11-09T15:46:00.252860Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          examples:
            - '2022-11-09T15:46:00.252860Z'
        image_details:
          type: object
          properties:
            width:
              type: integer
              minimum: 1
            height:
              type: integer
              minimum: 1
          x-apidog-orders:
            - width
            - height
          x-apidog-ignore-properties: []
          nullable: true
      x-apidog-orders:
        - url
        - identifier
        - mime_type
        - created_at
        - updated_at
        - image_details
      required:
        - url
        - created_at
        - updated_at
      readOnly: true
      x-apidog-ignore-properties: []
      nullable: true
      x-apidog-folder: ''
    LocalizedContent:
      type: object
      properties: {}
      x-apidog-orders: []
      title: ''
      examples:
        - en: Text
      additionalProperties:
        type: string
        description: >-
          The actual set of languages depends on LC configuration. See:
          [Localization](doc-341959)
        examples:
          - Tekst
        nullable: true
      x-apidog-ignore-properties: []
      nullable: true
      x-apidog-folder: ''
    cms.status:
      type: string
      enum:
        - draft
        - published
        - unpublished
      examples:
        - published
      description: Determines visibility in [Public API](doc-341643)
      x-apidog-enum:
        - name: ''
          value: draft
          description: ''
        - name: ''
          value: published
          description: ''
        - name: ''
          value: unpublished
          description: ''
      x-apidog-folder: ''
    offer_type:
      type: string
      enum:
        - regular
        - birthday
        - exclusive
        - welcome
        - competition
        - reward
        - carbon_offset_item
        - parking
        - parking_exclusive
        - game_prize
        - informational
      x-apidog-enum:
        - value: regular
          name: ''
          description: ''
        - value: birthday
          name: ''
          description: ''
        - value: exclusive
          name: ''
          description: ''
        - value: welcome
          name: ''
          description: ''
        - value: competition
          name: ''
          description: ''
        - value: reward
          name: ''
          description: ''
        - value: carbon_offset_item
          name: ''
          description: ''
        - value: parking
          name: ''
          description: ''
        - value: parking_exclusive
          name: ''
          description: ''
        - value: game_prize
          name: ''
          description: ''
        - value: informational
          name: ''
          description: ''
      x-apidog-folder: ''
    id:
      type: integer
      description: Primary identifier of the record
      format: uint64
      readOnly: true
      examples:
        - 1
      x-apidog-folder: ''
    Base record attributes:
      type: object
      properties:
        id: *ref_1
        created_at: *ref_2
        updated_at: *ref_3
      x-apidog-orders:
        - id
        - created_at
        - updated_at
      required:
        - id
        - created_at
        - updated_at
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes: {}
servers:
  - url: https://api.mpc.dev.placewise.com
    description: Staging
security: []

```