1. Promotions
Marketplace
  • Getting an API token
  • Introduction
  • Customers
    • Get a list of Customer Fields
      GET
    • Retrieve Customer Fields matching the given ID
      GET
    • Get a list of Customers
      GET
    • Retrieve Customers matching the given ID
      GET
    • Update a Customer
      PUT
    • Delete a Customer
      DELETE
    • Bulk Add/Update Customers
      POST
    • Create a new Customer
      POST
    • Get a list of Orders
      GET
  • Distributors
    • Get a list of Distributors
      GET
    • Retrieve Distributors matching the given ID
      GET
    • Update a Distributor
      PUT
    • Delete a Distributor
      DELETE
    • Create a new Distributor
      POST
  • Warehouses
    • Get a list of Warehouses
      GET
    • Retrieve Warehouses matching the given ID
      GET
    • Update a Warehouse
      PUT
    • Delete a Warehouse
      DELETE
    • Bulk Add/Update Warehouses
      POST
    • Create a new Warehouse
      POST
  • Exports
    • Get available exports
    • Get parameter options
    • Run custom export
  • Orders
    • Get a list of Order Batches
    • Retrieve Order Batch matching the given order batch Ids (from orderBatches/list)
    • Update Order Batch status
    • Delete Order Batch
    • Create a new Order
    • Update an existing Order
    • Bulk Add/Update Orders
    • Bulk Update Order Batch Statuses
  • People
    • Get a list of People
    • Retrieve a specific Person by ID
    • Update a Person
    • Delete a Person
    • Create a new Person
    • Bulk Add/Update Persons
    • Get a list of roles
    • Get a list of person types
    • Retrieve a specific Person Type by ID
  • Products
    • Get a list of Products
    • Create a new Product
    • Bulk Add/Update Products
    • Retrieve Products matching the given ID
    • Update a Product
    • Delete a Product
    • Get a list of Product Skus
    • Create a new Product Sku
    • Update a Product Sku
    • Bulk Add/Update Product Skus
    • Get a list of Pricing information for a given product
    • Bulk Add/Update Pricing
    • Get a list of categories
    • Get a list of brands
    • Get a list of PriceZones
    • Get a list of Product Fields
    • Get a list of Product Sku Fields
    • Get a list of product options
    • Retrieve a product option matching the given ID
    • Update a product option
    • Delete a product option
    • Create a new product option
    • Update Pricing for a product that starts on a given date
    • Create new Pricing for a product
    • Delete Pricing for a product that starts on a given date
    • Retrieve a field matching the given ID
    • Add or update the component SKUs linked to a kit Product
    • Bulk Add/Update the component SKUs linked to kit Products, across any number of kits
  • Vendors
    • Get a list of Vendors
    • Retrieve Vendors matching the given ID
    • Update a Vendor
    • Delete a Vendor
    • Bulk Add/Update Vendors
    • Create a new Vendor
  • Content
  • Promotions
    • Get a list of Promotions
      GET
    • Retrieve the Promotion matching the given ID
      GET
    • Get a list of Deals linked to the given Promotion
      GET
    • Retrieve the Deal matching the given ID under the given Promotion
      GET
    • Update the Deal's details, and optionally its status. Card and banner appearance stays inherited from the Promotion
      PUT
    • Bulk Add/Update fixed price Deals under the given Promotion
      POST
    • Set the Deal's fixed price reward, with a price per product
      POST
    • Add products to the Deal's fixed price reward pool
      POST
    • Set the Deal's warehouses, price zones, customers and delivery dates in one call
      PUT
  • Imports
  • Product Skus
    • Retrieve Fields matching the given ID
    • Retrieve Product Skus matching the given ID
    • Delete a Product Sku
    • Bulk Add/Update Product Skus across multiple Products
  • Pricing
    • Retrieve Pricing for a product that starts on a given date
    • Bulk Add/Update Pricing across multiple products
  • PriceZones
    • Retrieve PriceZone by ID
  • Product Highlights
    • Get a list of product highlights
    • Add products to the product highlight with a name, creating it if there is none
    • Add products to a product highlight
  • Product Options
  • Schemas
    • Schemas
      • Export
      • ExportParameter
      • PriceAssociatedProductSku
      • PriceList
      • Pricing
    • BulkFailMessage
    • AddressApiInput
    • DealAvailability
    • BulkSkippedProduct
    • SelectionItem
    • ProductOption
    • Customer
    • Address
    • Country
    • State
    • Distributor
    • FreeStock
    • OrderBatch
    • OrderLine
    • Person
    • PersonType
    • PricingMutation
    • ProductSku
    • Vendor
    • Warehouse
    • WarehouseUnderDistributor
    • BulkUpdateResult
    • Deal
    • DealBulkItemApiInput
    • DealUpdateApiInput
    • FIELD_TYPE
    • PERMISSION
    • PriceListMutation
    • ProductSkuApiInput
    • SELECTION_TYPE
    • DealAvailabilityApiInput
    • BulkSuccessItem
    • DealBulkApiInput
    • CompleteOrder
    • DealDateRange
    • CompleteOrderApiInput
    • DealDeliveryDateRangeApiInput
    • CompleteOrderBulkApiInput
    • DealPagedResults
    • CompleteOrderQuantityApiInput
    • DealProductPrice
    • CompleteOrderWithIdApiInput
    • DealProductPriceApiInput
    • DealProductsApiInput
    • DealReward
    • CustomerApiInput
    • CustomerAssociation
    • ENTITY_STATUS
    • CustomerAssociationApiInput
    • EntityAssociationResult
    • CustomerBulkApiInput
    • FIELD_COMPONENT
    • CustomerOrdering
    • CustomerOrderingApiInput
    • CustomerRule
    • Field
    • CustomerRuleApiInput
    • FieldComponent
    • CustomersConnection
    • KitComponent
    • PagedResults
    • DistributorPagedResults
    • PriceZone
    • ENTITY_STATUS_WITH_TEST
    • PricingCrossProductBulkApiInput
    • Email
    • ProductKitComponentApiInput
    • Error
    • ProductKitComponentBulkApiInput
    • ProductKitComponentCrossProductBulkApiInput
    • ProductSkuCrossProductBulkApiInput
    • Promotion
    • PromotionPagedResults
    • REWARD_APPLY
    • RolePermission
    • ORDER_STATUS
    • Section
    • OrderBatchStatusApiInput
    • Selection
    • OrderBatchStatusBulkApiInput
    • VISIBILITY
    • OrdersConnection
    • PRODUCT_SKU_STATUS_RAW
    • PersonApiInput
    • PersonBulkApiInput
    • PersonRule
    • PersonRuleApiInput
    • PersonTypeAssociation
    • PersonTypeAssociationApiInput
    • PersonsConnection
    • Phone
    • PriceAssociatedProductSkuMutation
    • PriceZonePagedResults
    • PricingBulkApiInput
    • PricingPagedResults
    • Product
    • ProductApiInput
    • ProductAssociation
    • ProductAssociationApiInput
    • ProductBulkApiInput
    • ProductHighlight
    • ProductHighlightByNameApiInput
    • ProductHighlightByNameResult
    • ProductHighlightPagedResults
    • ProductHighlightProductsApiInput
    • ProductOptionApiInput
    • ProductPagedResults
    • ProductRule
    • ProductRuleApiInput
    • ProductSkuBulkApiInput
    • SelectionPagedResults
    • VALIDATION_STATUS
    • ValidationProblemDetails
    • VendorApiInput
    • VendorBulkApiInput
    • VendorBulkItemApiInput
    • VendorPagedResults
    • WarehouseApiInput
    • WarehouseBulkApiInput
    • WarehouseBulkDistributorApiInput
    • WarehouseBulkItemApiInput
    • WarehousePagedResults
    • WarehouseSkuId
  1. Promotions

Get a list of Promotions

GET
/v1/promotions/list
Lists the promotions, 100 per page by default and at most 500. externalId and name keep only the promotions whose external id or name contains the value. Pass pagination.endCursor back as cursor for the next page.

Request

Query Params

Responses

🟢200
application/json
OK
Bodyapplication/json

🟠400
🟠401
🟠429
🔴500
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://marketplacerest.perenso.net/v1/promotions/list?cursor=&externalId=&name=&resultsPerPage='
Response Response Example
200 - Success Example
{
    "items": [
        {
            "id": "PROMO-SPRING26",
            "name": "Spring Savings 2026",
            "subTitle": "Seasonal favourites at fixed prices",
            "allDates": false,
            "startDate": "2026-09-01T00:00:00+00:00",
            "endDate": "2026-11-30T00:00:00+00:00",
            "displayOrder": 1,
            "showDealsOnLandingPage": true,
            "dealCount": 12,
            "bannerColour": "#1E5AA8",
            "bannerTextColour": "#FFFFFF",
            "bannerOverlayText": "Spring deals",
            "bannerOverlayTextColour": "#FFFFFF"
        },
        {
            "id": "PROMO-SPRING26-LIQ",
            "name": "Spring Liquor Specials",
            "subTitle": null,
            "allDates": true,
            "startDate": null,
            "endDate": null,
            "displayOrder": 2,
            "showDealsOnLandingPage": false,
            "dealCount": 4,
            "bannerColour": "#7A1F3D",
            "bannerTextColour": "#FFFFFF",
            "bannerOverlayText": null,
            "bannerOverlayTextColour": null
        }
    ],
    "pagination": {
        "endCursor": "YXJyYXljb25uZWN0aW9uOjk5",
        "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
        "hasNextPage": true,
        "hasPreviousPage": false,
        "totalRecords": 240,
        "resultsPerPage": 100
    }
}
Modified at 2026-11-17 17:43:44
Previous
Create a new Vendor
Next
Retrieve the Promotion matching the given ID
Built with