Purchases

Buy an item for the person if its price drops

Live

POST https://shopitup.ca/api/v1/price-watches

A price watch: ShopItUp buys the item for the person when its price is max_price or less and the total with shipping and tax is within max_total, holding their saved card (charged 24 hours later unless they cancel) and shipping to their saved address, within the spending limits they set — at most once, before it expires (up to 30 days). It does not reserve the item before it buys; if the item sells first the watch ends. The person is emailed when it is set (with a cancel link) and when it buys, ends or needs them. Same permission and stores as POST /purchases. Refused, among others, with already_at_price when the item is already at or under max_price (buy it now instead), already_watching, too_many_watches (25), store_requires_checkout_link, over_spending_limit, spending_limit_not_set, purchases_paused.

Access: purchase:write How to get a token
Returns: The price watch

Request

curl -X POST "https://shopitup.ca/api/v1/price-watches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_item_id": "5171",
    "max_price": 90,
    "max_total": 115
  }'

const response = await fetch("https://shopitup.ca/api/v1/price-watches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "catalog_item_id": "5171",
    "max_price": 90,
    "max_total": 115
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://shopitup.ca/api/v1/price-watches",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "catalog_item_id": "5171",
      "max_price": 90,
      "max_total": 115
    },
)

data = response.json()

Response

201 · The price watch

{
  "price_watch_id": 42,
  "status": "active",
  "catalog_item_id": "5171",
  "title": "(S) Arc'teryx Casual Cozy Outdoor Gray Fleece Turtleneck Pullover",
  "max_price": {
    "amount": "90.00",
    "currency": "CAD"
  },
  "max_total": {
    "amount": "115.00",
    "currency": "CAD"
  },
  "current_price": {
    "amount": "110.00",
    "currency": "CAD"
  },
  "outcome": null,
  "order_number": null,
  "expires_at": "2026-11-03T18:00:00Z",
  "created_at": "2026-10-04T18:00:00Z"
}

422 · The request is invalid; `fields` says which field and why

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid. See fields for what to fix.",
    "fields": {
      "per_page": [
        "The per page field must not be greater than 48."
      ]
    }
  }
}

401 · Missing, invalid or expired access token

{
  "error": {
    "code": "unauthorized",
    "message": "The access token is missing, invalid or expired."
  }
}

403 · The token does not carry the scope this endpoint needs

{
  "error": {
    "code": "insufficient_scope",
    "message": "This request needs a token with the catalog:read scope."
  }
}

429 · Too many requests; retry after the number of seconds in `Retry-After`

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 30 seconds."
  }
}

503 · A service the API depends on is briefly unavailable; retry after the number of seconds in `Retry-After`

{
  "error": {
    "code": "unavailable",
    "message": "A service the API depends on is briefly unavailable. Try again in a few seconds."
  }
}

Request body

JSON, sent with Content-Type: application/json.

catalog_item_id string Required
max_price number Required

Buy when the item's price is this or less (before shipping and tax).
max_total number Required

The most to spend in all, including shipping and tax.
days integer

1–30

Response

201 The price watch

price_watch_id integer
status string

One of active executing fulfilled item_sold needs_you cancelled expired
catalog_item_id string
title string
max_price Money
2 child attributes
- amount string Required
  
  Decimal string, two places
- currency string Required
  
  One of CAD
max_total Money
2 child attributes
- amount string Required
  
  Decimal string, two places
- currency string Required
  
  One of CAD
current_price Money
2 child attributes
- amount string Required
  
  Decimal string, two places
- currency string Required
  
  One of CAD
outcome string

Why it ended, when it did (e.g. bought, item_sold, over_your_total, card_declined, limits_lowered, assistant_disconnected, expired).
order_number string
expires_at string date-time
created_at string date-time

Status codes

201

The price watch

409

Refused; no watch was set

422

The request is invalid; fields says which field and why

401

Missing, invalid or expired access token

403

The token does not carry the scope this endpoint needs

429

Too many requests; retry after the number of seconds in Retry-After

503

A service the API depends on is briefly unavailable; retry after the number of seconds in Retry-After

Errors share one shape — see Errors and rate limits.