# Introduction This section describes endpoints destined for offers management. Navigate to [Offers](doc-341649) section to see docs for member-related endpoints. ## Offer model ### Example ```json { "id": 129, "type": "regular", "status": "published", "name": {"en": "Great Offer!", "pl": "Super Oferta" }, "description": { "en": "Special", "pl": "Specjalna" }, "internal_name": "Internal offer name", "notes": "Internal offer description", "usable_since": "2022-05-05T13:00:00.000000Z", "usable_until": "2030-05-05T13:00:00.000000Z", "visible_since": "2021-05-05T13:00:00.000000Z", "visible_until": "2031-05-05T13:00:00.000000Z", "collection_ids": [2], "store_id": 15, "audience_id": 34, "campaign_id": 32, "url": "promotions/423", "external_url": "https://example.com", "maximum_uses_per_user": 5, "maximum_grants_per_user": 10, "periodic_usage": {"timespan": "week", "limit": 15 }, "stock": 30, "usage_authorization_token": "tok3n", "usage_authorization_token_required": true, "external_master": null, "image_template": { "width": 100, "height": 300, "default": false, "rectangles": [ { "name": "Title", "color": "#FF00FF", "width": 100, "height": 200, "number": 5, "content": "{{stores}}", "padding": 5, "font_url": "https://fonts.googleapis.com/css?family=Raleway:400,700&display=swap", "font_size": 15, "font_style": "normal", "offset_top": 5, "text_align": "center", "font_family": "'Playfair Display', serif", "font_weight": "normal", "offset_left": 15, "text_decoration": "none" } ], "background_url": "https://example.com/image.png" }, "read_more": { "button_title": "More", "url": "https://example.com", "title": "That's more", "text": "End that's even more", "enabled": true }, "activation_texts": { "button": "Button", "modal": "Modal", "description": "Description" }, "extras": { "something": "additional" }, "files": [ { "url": "https://offers-api.s3.eu-central-1.amazonaws.com/offer-1000115-offer_default-original.jpg", "width": 600, "height": 800, "kind": "offer_default", "size_type": "base" } ], "images": [ { "url": "https://cdn-files.eu.placewise.com/f/CJYHEMwCGgtvZmZlcl9pb", "mime_type": "image/webp", "created_at": "2025-08-29T05:23:34Z", "updated_at": "2025-08-29T05:23:34Z", "image_details": { "width": 640, "height": 640 } } ], "created_at": "2022-05-27T09:12:29.358079Z", "updated_at": "2022-05-27T09:12:29.358079Z", "archived_at": null, "uses_count": 0, "grants_count": 0 } ``` ### Definition | Key | Type | Readonly? | Default | Description | |------------------------------------|----------------------------------------------|-----------|-----------|----------------------------------------------------------------------------------------------------| | id | integer | yes | | | | name | [LocalizedContent](doc-341959#localizedcontent-json-model) | no | {} | | | description | [LocalizedContent](doc-341959#localizedcontent-json-model) | no | {} | | | type | enum | no | 'regular' | See: [Offer types](doc-341695#offers-types) | | status | enum | no | 'draft' | See: [Offer statuses](doc-341695#offers-statuses) | | internal_name | string | no | null | Internal name | | notes | string | no | null | Internal description / comment | | visible_since | date | no | null | Time since the offer is visible to members. If null, there is no restriction. | | visible_until | date | no | null | Time until the offer is visible to members. If null, there is no restriction. | | usable_since | date | no | null | Time since the offer may be used. If null, there is no restriction. | | usable_until | date | no | null | Time until the offer may be used. If null, there is no restriction. | | collection_ids | integer[] | no | [] | List of collections ids the offer belongs to | | store_id | integer | no | null | ID of store related to the offer. | | audience_id | integer | no | null | DMP's audience ID. If it is set, the offer is available only to members belonging to this audience | | campaign_id | integer | no | null | MPC's campaign ID | | url | string | yes | | Address of the entity page on website | | external_url | string | no | null | The URL the offer may be linked with | | maximum_uses_per_user | integer | no | null | Limit of uses individual member may perform. When empty, there's no limit. | | periodic_usage | object | no | null | Allows to set `limit` of how many times individual member may perform in given `timespan` | | periodic_usage.timespan | enum | no | null | Enum: `['hour', 'day', 'week', 'month', 'year']` | | periodic_usage.limit | integer | no | null | | | stock | integer | no | null | Global limit of member uses. When empty, there's no limit. | | maximum_grants_per_user | integer | no | null | Limit of grants individual member may receive. When empty, there's no limit. | | usable_in_seconds_after_granting | integer | no | null | Time in seconds that offer will be available for the member after granting | | usage_authorization_token | string | no | null | See: [Offer use authorization](api-3510865#offer-use-authorization) | | usage_authorization_token_required | boolean | no | false | See: [Offer use authorization](api-3510865#offer-use-authorization) | | external_source | string | no | nul | When present, the record is being synced from given external source | | image_template | object | no | null | See: [Offer Image Template](doc-341696) below | | read_more | object | no | null | Additional offer display data | | read_more.button_title | string | no | null | | | read_more.url | string | no | null | | | read_more.title | string | no | null | | | read_more.text | string | no | null | | | activation_texts | object | no | null | Additional offer display data | | activation_texts.modal | string | no | null | | | activation_texts.button | string | no | null | | | activation_texts.description | string | no | null | | | extras | object | no | {} | Extendable container for any potential extra data | | files | object[] | yes | [] | (DEPRECATED) A list of offer files - see [File model](doc-341697#file-model) | | images | object[] | yes | [] | A list of offer files | | created_at | date | yes | n/a | When the offer has been created | | updated_at | date | yes | n/a | Last time when the offer has been updated | | archived_at | date | yes | null | Time when the offer has been archived | | uses_count | date | yes | 0 | Total number of times the offer has been used by members | | grants_count | date | yes | 0 | Total number of times the offer has been granted to members | | cms_tag_ids | integer[] | no | [] | Tag ids related to CMS tags API | ### Offers types Type | [Scope](doc-341649#scoping) | Description -------------------|--------------------------| ----------- regular | standard | Standard offer exclusive | standard | Standard offer that is accessible to member only after [Granting](api-3511014) welcome | standard | Like exclusive, but granted to member by system on sign up birthday | standard | Like regular, but expected to have some birthday audience assigned to it competition | standard | Like regular, but utilized to register members to some events informational | informational | Non-usable static offer carbon_offset_item | carbon_offset | Like regular, but utilized to register members carbon offer check-ins parking | parking | Like regular, but for parking-related benefits parking_exclusive | parking | Like exclusive, but for parking-related benefits game_prize | standard | Like exclusive, but given as game prize ### Offers statuses | Status | Description | | ----------- |-------------------------------------------------------------------------------| | draft | Offer is not visible in [Offers API](doc-341649) | | published | Offer visible in [Offers API](doc-341649) | | unpublished | Just like `'draft'`, may be used as an indicator that it was published before | ### Offer Image Template With this object, you can determine that offer's image will be rendered according to the given definition which reflects the [ImageTemplate model](doc-341696#imagetemplate-model). However, it **is not** a reference to existing [ImageTemplate record](doc-341696#imagetemplate-record). If you want to apply record's model to the Offer, you must use it's [ImageTemplate model](doc-341696#imagetemplate-model) (copy it) as the offer's `image_template` attribute. When custom `background_url` is desired for given Offer, a new file may be uploaded to Files API as `offer_inline_template_background` and with identifier of given Offer. ## Collection model ### Example ```json { "id": 4591, "scope": "standard", "title": {"en": "Super Collection", "pl": "Super Kolekcja" }, "description": { "en": "Very Special", "pl": "Bardzo specjalna" }, "offers_order": [], "created_at": "2021-09-22T10:41:45.872Z", "updated_at": "2021-12-10T10:55:42.536Z", "archived_at": null, "position": 2, "offers_count": 1, "offers_visible_count": 0, "offers_uses_count": 1, "offers_upcoming_count": 0, "visible_since": "2021-09-21T22:00:00.000Z", "visible_until": "2021-09-23T21:59:59.999Z", "usable_since": "2021-09-21T22:00:00.000Z", "usable_until": "2021-09-23T21:59:59.999Z", "files": [ { "url": "https://offers-api.s3.eu-central-1.amazonaws.com/offer-1000115-offer_default-original.jpg", "width": 600, "height": 800, "kind": "collection_cover_default", "size_type": "base" } ] } ``` ### Definition | Key | Type | Readonly? | Description | |-----------------------|--------------------------------------------|-----------|-------------------------------------------------------------------------------------------------| | id | integer | yes | | | scope | enum (see: [Offer scope](doc-341649#scoping)) | no | When present, collection will be marked as destined for specific [Offer scope](doc-341649#scoping) | | | title | string | no | [LocalizedContent](doc-341959#localizedcontent-json-model) | | description | string | no | [LocalizedContent](doc-341959#localizedcontent-json-model) | | offers_order | integer[] | no | Specifies order of offers (consists of their IDs) that belong to the collection | | offers_count | integer | yes | Number of offers assigned to the collection | | offers_visible_count | integer | yes | Number of offers assigned to the collection that are visible | | offers_upcoming_count | integer | yes | Number of offers assigned to the collection that are not yet visible | | offers_uses_count | integer | yes | Number of offer uses inside the collection | | usable_since | date | yes | First `usable_since` of collection offers | | usable_until | date | yes | Last `usable_since` of collection offers | | visible_since | date | yes | First `visible_since` of collection offers | | visible_until | date | yes | Last `visible_until` of collection offers | | files | File[] | no | A list of collection files - see [File model](doc-341697#file-model) | | created_at | date | yes | When the collection has been created | | updated_at | date | yes | Last time when the collection has been updated | | archived_at | date | yes | Time when the collection has been archived |