Change status

Pause a promotion, resume it, turn on a draft, or end it for good.

The photos change in the background: retrieve the promotion afterwards to confirm its new status.

POSThttps://api.spyne.ai/api/pv1/promotions/{id}/status

AuthBearer tokenRate limit30 changes / min per rooftop

Before you call it

Which action works depends on the promotion's current status:

Current status	`activate`	`pause`	`complete`
`draft`	Yes. Scheduled instead if its start date is ahead	No	No
`scheduled`	No: it goes live by itself on its start date	No	No
`active`	No	Yes	Yes
`paused`	Yes (resumes it)	No	Yes
`completed`	No	No	No

A promotion with no vehicles or no images can't be activated. A draft or scheduled promotion can't be completed; delete it instead. Anything not allowed returns 409 INVALID_STATUS_CHANGE, and message says why.

Counts toward the 30 changes a minute per rooftop.

Path parameters

Requiredalways send

Parameter	Type	Required	Description
`id`	integer	Required	The promotion id.

Request body

Parameter	Type	Required	Description
`action`	string	Required	`activate` (turn on, or resume a paused one), `pause` (stop for now) or `complete` (end for good; can't be undone).

Sample request

curl --request POST \
  --url 'https://api.spyne.ai/api/pv1/promotions/351/status' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "action": "pause" }'

import requests

url = "https://api.spyne.ai/api/pv1/promotions/351/status"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers, json={"action": "pause"})
print(response.status_code, response.json())

const response = await fetch("https://api.spyne.ai/api/pv1/promotions/351/status", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ action: "pause" }),
});
console.log(response.status, await response.json());

Sample response

{
  "success": true,
  "statusCode": 202,
  "message": "Promotion pause in progress",
  "data": {
    "id": "351",
    "action": "pause",
    "status": "paused"
  }
}

Response parameters (202)

Parameter	Type	Description
`data.id`	string	The promotion id, as sent in the path.
`data.action`	string	The action you sent.
`data.status`	string	The new status: `active`, `scheduled` (a draft with a future start), `paused` or `completed`.

Errors

Status	Code	When it happens
`400`	`INVALID_REQUEST`	`action` is missing or isn't `activate`, `pause` or `complete`.
`404`	`PROMOTION_NOT_FOUND`	No such promotion for this rooftop.
`409`	`INVALID_STATUS_CHANGE`	The action isn't allowed in the current status (see the table above).
`400`	`VALIDATION_FAILED`	Spyne refused the change.
`400`	`TEAM_NOT_RESOLVED`	The API key isn't linked to a rooftop.
`401`	`UNAUTHORIZED`	The API key is missing or wrong.
`429`	`RATE_LIMITED`	More than 30 changes this minute. Wait the seconds in `Retry-After`.
`502` / `503`	`SERVICE_UNAVAILABLE`	A Spyne service is briefly unavailable. Retry shortly.

What happens next

Retrieve the promotion to confirm the new status. A completed promotion can be deleted when you no longer need it.