# PR01 - List promotions

Call FrequencyRecommended usage: At each display of a promotions list page or on-promo offer detail page.Maximum usage: At each display of a promotions list page or on-promo offer detail page.PaginationThis resource supports offset pagination (see documentation)Sort fieldssort field can have the following values:startDate (Default) - Sort by promotion activity start date (Newest first) (desc by default)endDate - Sort by promotion activity end date (Newest first) (desc by default)dateCreated - Sort by promotion creation date (Newest first) (desc by default)

Endpoint: GET /api/promotions

## Query parameters:

  - `ids` (string)
    A comma separated list of identifiers for a promotion

  - `types` (string)
    A comma separated list of types for a promotion [AMOUNT_OFF|FREE_ITEMS|PERCENTAGE_OFF|REDUCED_UNIT_PRICE]

  - `states` (string)
    A comma separated list of states for a promotion [PENDING|ACTIVE|EXPIRED|PENDING_APPROVAL|REJECTED|ALL]

  - `ending_after` (string)
    Returns promotions which ended or will end after this date

  - `starting_before` (string)
    Returns promotions which started or will start before this date

  - `date_created_from` (string)
    Filter promotion creation date lower limit

  - `date_created_to` (string)
    Filter promotion creation date upper limit

  - `last_request_date` (string)
    Last request date and time. We recommend using the differential mode along with the states parameter.

  - `locale` (string)
    The locale to filter the medias and the public descriptions with. If not specified, medias and public descriptions of all locales are returned.If specified, only the media and the public description matching the locale will be returned, or, if not exist, the one matching the platform default locale.

  - `trigger_offer_ids` (string)
    Promotion-triggering offer ids, separated by commas

  - `reward_offer_ids` (string)
    Promotion reward offer ids, separated by commas

  - `channel_codes` (string)
    Channel codes on which promotions apply, separated by commas

  - `shop_id` (integer)
    Use this parameter when your user has access to several shops. If not specified, the shop_id from your default shop will be used.

## Response 200 fields (application/json):

  - `promotions` (array, required)
    List of promotions

  - `promotions.amount_off` (number)
    The amount off of the promotion. Only applicable when promotion is of type AMOUNT_OFF, null otherwise

  - `promotions.application_to_cart` (array, required)
    If applicable, returns promo code associated to the promotion

  - `promotions.application_to_cart.promo_code` (string)
    Promo code associated to the promotion

  - `promotions.campaign` (object)
    Campaign information, if applicable

  - `promotions.campaign.identifier` (string, required)
    Identifier of the campaign

  - `promotions.channels` (array, required)
    Channels on which the promotion is applied. If none, promotion applied on all channels

  - `promotions.channels.code` (string, required)
    Channel code

  - `promotions.channels.label` (string, required)
    Channel label

  - `promotions.customer_group_ids` (array)
    The customer groups on which the promotion is applied. If none, promotion applies to all customer groups.

  - `promotions.customer_organization_ids` (array)
    The customer organizations on which the promotion is applied. If none, promotion applies to all customer organizations.

  - `promotions.date_created` (string, required)
    Creation date of the promotion

  - `promotions.end_date` (string, required)
    End date of the promotion period of activity

  - `promotions.free_items_quantity` (integer)
    The free item target quantity of the promotion. Only applicable when promotion is of type FREE_ITEMS, null otherwise

  - `promotions.internal_description` (string, required)
    Internal description of the promotion, set by the shop

  - `promotions.internal_id` (string, required)
    Promotion identifier

  - `promotions.last_updated` (string, required)
    Last update date of the promotion

  - `promotions.max_quantity_to_discount` (integer)
    Maximum quantity of items on which a percentage off discount applies. Only applicable when promotion is of type PERCENTAGE_OFF, null otherwise

  - `promotions.medias` (array, required)
    The medias associated with this promotion, with the locales they apply to

  - `promotions.medias.locale` (string, required)
    Media's locale

  - `promotions.medias.url` (string, required)
    Url to download the media

  - `promotions.percentage_off` (number)
    The percentage off of the promotion. Only applicable when promotion is of type PERCENTAGE_OFF, null otherwise

  - `promotions.public_descriptions` (array, required)
    The public descriptions of the promotion, with the locales they apply to

  - `promotions.public_descriptions.locale` (string, required)
    Description's locale

  - `promotions.public_descriptions.value` (string, required)
    The description itself

  - `promotions.reduced_unit_price` (number)
    The new offer’s unit price triggered by the promotion. Only applicable when promotion is of type REDUCED_UNIT_PRICE, null otherwise.

  - `promotions.reward_offer_ids` (array)
    Offers used as reward in the promotion, according to the requested reward_offer_ids

  - `promotions.reward_on_purchased_items` (boolean, required)
    Specifies if the promotion's reward applies to purchased items or to a specific selection

  - `promotions.start_date` (string, required)
    Start date of the promotion period of activity

  - `promotions.state` (string, required)
    Promotion state
    Enum: "ACTIVE", "PENDING", "PENDING_APPROVAL", "REJECTED", "EXPIRED"

  - `promotions.trigger_offer_ids` (array)
    Offers which trigger the promotion, according to the requested trigger_offer_ids

  - `promotions.triggers` (array, required)
    Triggers of the promotion

  - `promotions.triggers.amount_purchased` (number)
    Amount that triggers the promotion. Available for minimum_amount or every_amount type triggers.

  - `promotions.triggers.quantity_purchased` (integer)
    Quantity of items that triggers the promotion. Available for minimum_quantity or every_quantity type triggers.

  - `promotions.triggers.same_item_purchased` (boolean)
    Whether the promotion requires the same item to be triggered or not. Available for minimum_quantity or every_quantity type triggers.

  - `promotions.triggers.type` (string, required)
    Type of promotion trigger
    Enum: "minimum_quantity", "every_quantity", "minimum_amount", "every_amount"

  - `promotions.type` (string, required)
    Promotion type
    Enum: "AMOUNT_OFF", "FREE_ITEMS", "PERCENTAGE_OFF", "REDUCED_UNIT_PRICE"

  - `total_count` (integer, required)