---
title: List Promotions
slug: api-documentation/list-promotions
createdAt: 2026-11-20T10:03:06.998Z
---

{
  "id": "ue2yvEy1HDtxCCdmDijUH",
  "type": "api-oas-v2",
  "data": {
    "method": "GET",
    "url": "https://api.upstartcommerce.com/v1/promotion",
    "servers": [
      {
        "url": "https://api.upstartcommerce.com/v1/promotion"
      }
    ],
    "name": "List Promotions",
    "description": "<p>This endpoint returns a page of the tenant's promotions for the given site, optionally filtered by a date\nwindow and a search text. It replaces the promotions search index for the admin promotions list and calendar.</p>\n<p>All query parameters are optional. Without <code>isArchived</code>, archived and active promotions are both returned;\n<code>isArchived</code> filters both the items and <code>total</code>.\nA promotion matches the site when its <code>siteIds</code> contain the <code>x-upstart-site</code> header, or are empty.</p>\n<p><code>from</code> and <code>to</code> are UTC timestamps (<code>YYYY-MM-DDTHH:MM:SS[.fff]Z</code>; date-only values and other offsets are\nrejected) and inclusive: <code>from</code> keeps promotions whose stop date is at or after <code>from</code>, <code>to</code> keeps promotions\nwhose start date is at or before <code>to</code>; with both, the promotion's run overlaps the window. To filter by a\ntenant-local day, send that day's start and end converted to UTC.</p>\n<p>Results are ordered by the <code>sort</code> entries, then by <code>id</code>; the default is <code>name</code> (byte order), then <code>id</code>.</p>\n<p>Authorized permissions:</p>\n<ul>\n<li><code>promotion.read</code></li>\n</ul>",
    "contentType": "application/json",
    "request": {
      "pathParameters": [],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json"
          ],
          "default": "application/json"
        },
        {
          "kind": "required",
          "name": "x-upstart-tenant",
          "type": "string",
          "description": "Tenant identifier associated with the site this call is for."
        },
        {
          "kind": "required",
          "name": "x-upstart-site",
          "type": "string",
          "description": "The site identifier."
        }
      ],
      "queryParameters": [
        {
          "kind": "optional",
          "name": "from",
          "type": "string",
          "example": "2026-10-01T06:00:00Z",
          "description": "<p>Start of the window, a UTC timestamp. Inclusive.</p>"
        },
        {
          "kind": "optional",
          "name": "to",
          "type": "string",
          "example": "2026-11-01T05:59:59Z",
          "description": "<p>End of the window, a UTC timestamp. Inclusive. Must not be before <code>from</code>.</p>"
        },
        {
          "kind": "optional",
          "name": "query",
          "type": "string",
          "description": "<p>Case-insensitive text contained in the name, description or message, or the exact promotion id.</p>"
        },
        {
          "kind": "optional",
          "name": "isArchived",
          "type": "string",
          "example": "false",
          "description": "<p><code>true</code> or <code>false</code>: keep only archived, or only non-archived, promotions. Absent: both.</p>"
        },
        {
          "kind": "optional",
          "name": "page",
          "type": "string",
          "example": "0",
          "description": "<p>Zero-based page number. Default 0.</p>"
        },
        {
          "kind": "optional",
          "name": "pageSize",
          "type": "string",
          "example": "25",
          "description": "<p>Promotions per page, 1 to 10000. Default 25.</p>"
        },
        {
          "kind": "optional",
          "name": "sort",
          "type": "array",
          "description": "<p>Repeatable sort entry <code>property[:asc|:desc]</code>, property one of <code>name</code>, <code>priority</code>, <code>startDate</code>, <code>stopDate</code>. Direction defaults to <code>asc</code>.</p>",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        }
      ],
      "bodyDataParameters": [],
      "formDataParameters": [],
      "oAuthParameters": [
        {
          "id": "NoChannelPortalAccess",
          "name": "NoChannelPortalAccess",
          "kind": "optional",
          "type": "http",
          "description": "<p>This authentication is required for clients to interact with any of the management APIs. Similar to 'LoggedIn', it indicates that the user has actually logged into the system, but in this case with a management role.</p>",
          "scheme": "bearer"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "200",
        "description": "<p>Success-the requested page of promotions.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "One page of promotions.",
            "customType": "PromotionListResponse",
            "schema": [
              {
                "name": "items",
                "kind": "required",
                "type": "array",
                "description": "<p>A promotion as listed by <code>GET /promotion</code>, with the executor's template id as <code>type</code>.</p>",
                "modelRef": "#/components/schemas/PromotionListItem",
                "customType": "PromotionListItem[]",
                "schema": [
                  {
                    "name": "id",
                    "kind": "required",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "siteIds",
                    "kind": "required",
                    "type": "array",
                    "description": "",
                    "example": "",
                    "itemType": "string",
                    "customType": "string[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "name",
                    "kind": "required",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "description",
                    "kind": "optional",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "message",
                    "kind": "required",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "priority",
                    "kind": "required",
                    "type": "integer",
                    "description": ""
                  },
                  {
                    "name": "startDate",
                    "kind": "required",
                    "type": "string<date-time>",
                    "description": "",
                    "format": "date-time"
                  },
                  {
                    "name": "stopDate",
                    "kind": "required",
                    "type": "string<date-time>",
                    "description": "",
                    "format": "date-time"
                  },
                  {
                    "name": "isActive",
                    "kind": "required",
                    "type": "boolean",
                    "description": ""
                  },
                  {
                    "name": "isArchived",
                    "kind": "required",
                    "type": "boolean",
                    "description": ""
                  },
                  {
                    "name": "taxCode",
                    "kind": "optional",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "media",
                    "kind": "required",
                    "type": "map",
                    "description": "",
                    "example": "",
                    "customType": "map<string, MediaValue>",
                    "schema": []
                  },
                  {
                    "name": "type",
                    "kind": "required",
                    "type": "string",
                    "description": "<p>The promotion type, e.g. <code>ItemLevelPromotion</code>.</p>"
                  }
                ]
              },
              {
                "name": "total",
                "kind": "required",
                "type": "integer",
                "description": "Number of matching promotions before paging."
              },
              {
                "name": "page",
                "kind": "required",
                "type": "integer",
                "description": ""
              },
              {
                "name": "pageSize",
                "kind": "required",
                "type": "integer",
                "description": ""
              }
            ],
            "modelRef": "#/components/schemas/PromotionListResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "400",
        "description": "The request contained information that the server was unable to process. Appropriate errors are provided in the response body.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>Error payload returned when a request fails validation, identifying the offending input by name, code and detail.</p>",
            "customType": "ValidationErrorResponse",
            "schema": [
              {
                "name": "name",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "code",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "detail",
                "kind": "optional",
                "type": "string",
                "description": ""
              }
            ],
            "modelRef": "#/components/schemas/ValidationErrorResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "401",
        "description": "The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>Standard error payload identifying a failure by name, code and detail, with an optional machine-readable reason.</p>",
            "customType": "ErrorResponse",
            "schema": [
              {
                "name": "name",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "code",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "detail",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "reason",
                "kind": "optional",
                "type": "string",
                "description": ""
              }
            ],
            "modelRef": "#/components/schemas/ErrorResponse",
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "example-0-curl",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request GET \\\n     --url https://api.upstartcommerce.com/v1/promotion \\\n     --header 'accept: application/json' \\\n     --header 'x-upstart-tenant: string' \\\n     --header 'x-upstart-site: string'"
        },
        {
          "id": "example-1-javascript",
          "language": "javascript",
          "label": "javascript",
          "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-upstart-tenant\", \"string\");\nmyHeaders.append(\"x-upstart-site\", \"string\");\n\nvar requestOptions = {\n   method: 'GET',\n   headers: myHeaders,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/promotion\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "example-2-ruby",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/promotion\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest[\"x-upstart-site\"] = \"string\"\n\nresponse = https.request(request)\nputs response.read_body\n"
        },
        {
          "id": "example-3-python",
          "language": "python",
          "label": "Python",
          "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/promotion\"\n\npayload = {}\nheaders = {\n   'accept': 'application/json',\n   'content-type': 'application/json',\n   'x-upstart-tenant': 'string',\n   'x-upstart-site': 'string'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
        }
      ],
      "selectedLanguageId": "example-0-curl"
    },
    "results": {
      "languages": [
        {
          "id": "response-0-200",
          "language": "200",
          "code": "// Success-the requested page of promotions.\n{\n  \"items\": [\n    {\n      \"id\": \"\",\n      \"siteIds\": [\n        \"\"\n      ],\n      \"name\": \"\",\n      \"description\": \"\",\n      \"message\": \"\",\n      \"priority\": 0,\n      \"startDate\": \"\",\n      \"stopDate\": \"\",\n      \"isActive\": false,\n      \"isArchived\": false,\n      \"taxCode\": \"\",\n      \"media\": \"\",\n      \"type\": \"\"\n    }\n  ],\n  \"total\": 0,\n  \"page\": 0,\n  \"pageSize\": 0\n}"
        },
        {
          "id": "response-1-400",
          "language": "400",
          "code": "// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.\n{\n  \"name\": \"\",\n  \"code\": \"\",\n  \"detail\": \"\"\n}"
        },
        {
          "id": "response-2-401",
          "language": "401",
          "code": "// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.\n{\n  \"name\": \"\",\n  \"code\": \"\",\n  \"detail\": \"\",\n  \"reason\": \"\"\n}"
        }
      ],
      "selectedLanguageId": "response-0-200"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}