--- title: Update Promotion slug: api-documentation/9Gf6-update-promotion createdAt: 2026-08-27T17:06:56.421Z --- { "id": "4t6DUlCMT2_2kb1ZR3yon", "type": "api-oas-v2", "data": { "method": "PUT", "url": "https://api.upstartcommerce.com/v1/promotion/{promotionId}", "servers": [ { "url": "https://api.upstartcommerce.com/v1/promotion/{promotionId}" } ], "name": "Update Promotion", "description": "

This endpoint allows administrators to update the details of an existing promotion.

\n

Authorized permissions:

\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "promotionId", "type": "string", "description": "Unique identifier for the promotion." } ], "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." } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "The updated values for the promotion.", "customType": "UpdatePromotionRequest", "schema": [ { "name": "data", "kind": "required", "type": "object", "description": "

The presentation details of a promotion: its name, description, customer-facing message and media.

", "modelRef": "#/components/schemas/PromotionData", "customType": "PromotionData", "schema": [ { "name": "description", "kind": "optional", "type": "string", "description": "" }, { "name": "media", "kind": "optional", "type": "map", "description": "", "example": "", "customType": "map", "schema": [] }, { "name": "message", "kind": "required", "type": "string", "description": "" }, { "name": "name", "kind": "required", "type": "string", "description": "" } ] }, { "name": "executor", "kind": "required", "type": "object", "description": "This class describes the type of promotion.", "modelRef": "#/components/schemas/Executor", "customType": "Executor", "schema": [ { "name": "templateId", "kind": "required", "type": "string", "description": "

Unique identifier for a template (e.g. by x get 1 free).

" }, { "name": "configuration", "kind": "required", "type": "object", "description": "

The configuration values for the template (e.g. by one get one free, get 10% off).

", "example": "", "schema": [] } ] }, { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier for the promotion." }, { "name": "siteIds", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "isActive", "kind": "required", "type": "boolean", "description": "", "default": false }, { "name": "priority", "kind": "required", "type": "integer", "description": "" }, { "name": "startDate", "kind": "required", "type": "string", "description": "", "format": "date-time" }, { "name": "stopDate", "kind": "required", "type": "string", "description": "", "format": "date-time" }, { "name": "taxCode", "kind": "optional", "type": "string", "description": "Tax code used in cart tax calculations." }, { "name": "excludedPromotionIds", "kind": "optional", "type": "array", "description": "

Ids of promotions this promotion must never be applied together with. Exclusion is mutual: listing B on A also prevents A from applying once B has applied, and whichever applies first wins. Coupon-gated promotions are evaluated as a batch before automatic ones, so a coupon-gated promotion always beats an automatic one it excludes, whatever their priorities. Within a batch, order is the promotion's category then its priority, with id as a tie-break - so priority decides an excluded pair only when both promotions are coupon-gated or both are automatic.

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/UpdatePromotionRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "NoChannelPortalAccess", "name": "NoChannelPortalAccess", "kind": "optional", "type": "http", "description": "

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.

", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "

Success-promotion updated.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

A promotion, with its rule data, executor, priority and whether it is currently active or archived.

", "customType": "Promotion", "schema": [ { "name": "data", "kind": "required", "type": "object", "description": "

The presentation details of a promotion: its name, description, customer-facing message and media.

", "modelRef": "#/components/schemas/PromotionData", "customType": "PromotionData", "schema": [ { "name": "description", "kind": "optional", "type": "string", "description": "" }, { "name": "media", "kind": "optional", "type": "map", "description": "", "example": "", "customType": "map", "schema": [] }, { "name": "message", "kind": "required", "type": "string", "description": "" }, { "name": "name", "kind": "required", "type": "string", "description": "" } ] }, { "name": "executor", "kind": "required", "type": "object", "description": "This class describes the type of promotion.", "modelRef": "#/components/schemas/Executor", "customType": "Executor", "schema": [ { "name": "templateId", "kind": "required", "type": "string", "description": "

Unique identifier for a template (e.g. by x get 1 free).

" }, { "name": "configuration", "kind": "required", "type": "object", "description": "

The configuration values for the template (e.g. by one get one free, get 10% off).

", "example": "", "schema": [] } ] }, { "name": "id", "kind": "optional", "type": "string", "description": "Unique identifier for a promotion." }, { "name": "isActive", "kind": "required", "type": "boolean", "description": "", "default": false }, { "name": "isArchived", "kind": "required", "type": "boolean", "description": "", "default": false }, { "name": "priority", "kind": "required", "type": "integer", "description": "" }, { "name": "siteIds", "kind": "required", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "startDate", "kind": "required", "type": "string", "description": "", "format": "date-time" }, { "name": "stopDate", "kind": "required", "type": "string", "description": "", "format": "date-time" }, { "name": "taxCode", "kind": "optional", "type": "string", "description": "Tax code used in cart tax calculations." }, { "name": "excludedPromotionIds", "kind": "required", "type": "array", "description": "

Ids of promotions this promotion must never be applied together with. Exclusion is mutual: listing B on A also prevents A from applying once B has applied, and whichever applies first wins. Coupon-gated promotions are evaluated as a batch before automatic ones, so a coupon-gated promotion always beats an automatic one it excludes, whatever their priorities. Within a batch, order is the promotion's category then its priority, with id as a tie-break - so priority decides an excluded pair only when both promotions are coupon-gated or both are automatic.

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/Promotion", "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": "

Error payload returned when a request fails validation, identifying the offending input by name, code and detail.

", "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": "

Standard error payload identifying a failure by name, code and detail, with an optional machine-readable reason.

", "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, "deprecated": false, "examples": { "languages": [ { "id": "example-0-curl", "language": "curl", "label": "cURL", "code": "curl --request PUT \\\n --url https://api.upstartcommerce.com/v1/promotion/{promotionId} \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --data '{\n \"data\": {\n \"message\": \"\",\n \"name\": \"\"\n },\n \"executor\": {\n \"templateId\": \"\",\n \"configuration\": \"\"\n },\n \"id\": \"\",\n \"isActive\": false,\n \"priority\": \"\",\n \"startDate\": \"\",\n \"stopDate\": \"\"\n }'" }, { "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\");\n\nvar raw = JSON.stringify({\n \"data\": {\n \"message\": \"\",\n \"name\": \"\"\n },\n \"executor\": {\n \"templateId\": \"\",\n \"configuration\": \"\"\n },\n \"id\": \"\",\n \"isActive\": false,\n \"priority\": \"\",\n \"startDate\": \"\",\n \"stopDate\": \"\"\n});\n\nvar requestOptions = {\n method: 'PUT',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/promotion/{promotionId}\", 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/{promotionId}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Put.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest.body = JSON.dump({\n \"data\": {\n \"message\": \"\",\n \"name\": \"\"\n },\n \"executor\": {\n \"templateId\": \"\",\n \"configuration\": \"\"\n },\n \"id\": \"\",\n \"isActive\": false,\n \"priority\": \"\",\n \"startDate\": \"\",\n \"stopDate\": \"\"\n})\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/{promotionId}\"\n\npayload = json.dumps({\n \"data\": {\n \"message\": \"\",\n \"name\": \"\"\n },\n \"executor\": {\n \"templateId\": \"\",\n \"configuration\": \"\"\n },\n \"id\": \"\",\n \"isActive\": False,\n \"priority\": \"\",\n \"startDate\": \"\",\n \"stopDate\": \"\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string'\n}\n\nresponse = requests.request(\"PUT\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "example-0-curl" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Success-promotion updated.\n{\n \"data\": {\n \"description\": \"\",\n \"media\": \"\",\n \"message\": \"\",\n \"name\": \"\"\n },\n \"executor\": {\n \"templateId\": \"\",\n \"configuration\": {}\n },\n \"id\": \"\",\n \"isActive\": false,\n \"isArchived\": false,\n \"priority\": 0,\n \"siteIds\": [\n \"\"\n ],\n \"startDate\": \"\",\n \"stopDate\": \"\",\n \"taxCode\": \"\",\n \"excludedPromotionIds\": [\n \"\"\n ]\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": "" } ] }