Introduction

This section describes endpoints destined for offers management.

Navigate to Offers section to see docs for member-related endpoints.

Offer model

Example

{
  "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	no	{}
description	LocalizedContent	no	{}
type	enum	no	'regular'	See: Offer types
status	enum	no	'draft'	See: Offer 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
usage_authorization_token_required	boolean	no	false	See: 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 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
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	Description
regular	standard	Standard offer
exclusive	standard	Standard offer that is accessible to member only after Granting
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
published	Offer visible in Offers API
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.

However, it is not a reference to existing ImageTemplate record.
If you want to apply record's model to the Offer, you must use it's
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

{
  "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)	no	When present, collection will be marked as destined for specific Offer scope
title	string	no	LocalizedContent
description	string	no	LocalizedContent
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
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

Offer model#

Example#

Definition#

Offers types#

Offers statuses#

Offer Image Template#

Collection model#

Example#

Definition#

Offer model

Example

Definition

Offers types

Offers statuses

Offer Image Template

Collection model

Example

Definition