Purchases

Buy a quote for the person, with their saved card

Live

POST https://shopitup.ca/api/v1/purchases

For an assistant the person connected through the agent registration door (/oauth/register/agent) AND allowed to buy on ShopItUp's consent page — the elevated purchase:write scope. Puts the card saved in the person's ShopItUp account ON HOLD, off-session, within the spending limits they set (per order and per 30 days), for a quote to the address saved in their account, and charges it 24 hours later unless they cancel (charges_at). The item is held for them meanwhile; if it sells elsewhere first, the hold is released and nothing is charged. Only stores whose agent_checkout is direct sell this way. Purchases are served in Canada, except for delivery to Quebec. One purchase per quote. The person is emailed a copy of the order with a link to cancel it within 24 hours — the hold is released and nothing is charged.

201 held (the card is on hold until charges_at; then it becomes paid). 202 processing (the bank has not answered; follow it with GET /purchases/{purchase_id}). 402 requires_person: the bank wants the person to confirm, or the card was declined — nothing is charged and checkout.checkout_url is a link they can pay themselves. 409/429/403 refused, nothing charged: agent_purchases_unavailable, too_many_purchases, quote_already_purchased, quote_expired, item_unavailable, not_available_in_market, address_not_on_file, store_requires_checkout_link, purchases_paused, spending_limit_not_set, no_saved_card, card_not_on_this_account, price_changed, price_unavailable, over_spending_limit (with limit and room). Send an Idempotency-Key: the same key and quote return the first answer, so a retry never charges twice.

Access: purchase:write How to get a token
Returns: Held — the order is placed and the card is on hold until charges_at

Request

curl -X POST "https://shopitup.ca/api/v1/purchases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 2a7d-purchase-1" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qt_01J9Z8X2"
  }'

const response = await fetch("https://shopitup.ca/api/v1/purchases", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Idempotency-Key": "2a7d-purchase-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "quote_id": "qt_01J9Z8X2"
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://shopitup.ca/api/v1/purchases",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "2a7d-purchase-1"},
    json={
      "quote_id": "qt_01J9Z8X2"
    },
)

data = response.json()

Response

201 · Held — the order is placed and the card is on hold until charges_at

{
  "purchase_id": "pu_01j9z8y4q6r2t5v8w1x3z7c0b4",
  "status": "held",
  "order_number": "ORD-7KX2M9QP4R",
  "fulfilment": null,
  "totals": {
    "grand_total": {
      "amount": "150.92",
      "currency": "CAD"
    }
  },
  "cancel_until": "2026-10-05T18:00:00Z",
  "charges_at": "2026-10-05T18:00:00Z",
  "created_at": "2026-10-04T18:00:00Z"
}

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."
  }
}

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."
      ]
    }
  }
}

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."
  }
}

Headers

Idempotency-Key string Required

Any unique string per purchase you mean to make. Repeating it returns the first response.

up to 64 characters

Request body

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

quote_id string Required

A quote to the address saved in the person's account (GET /me/shipping-address).

Response

201 Held — the order is placed and the card is on hold until charges_at

purchase_id string
status string

One of held paid processing requires_person refused cancelled refunded
order_number string
fulfilment string

One of processing shipped
totals object
1 child attribute
- grand_total Money
  2 child attributes
  - amount string Required
    
    Decimal string, two places
  - currency string Required
    
    One of CAD
cancel_until string date-time

Until when the person can cancel from their email. For a held purchase, cancelling releases the hold and nothing is charged.
charges_at string date-time

While held, when the card will be charged unless the person cancels; null once charged or closed.
created_at string date-time
checkout object

Only with requires_person — a checkout link for the person to pay themselves.
3 child attributes
- checkout_id string
- checkout_url string uri
- expires_at string date-time
error object

Why it was refused, or why the person must pay themselves.
2 child attributes
- code string
- message string

Response

202 Processing — the bank has not answered yet

purchase_id string
status string

One of held paid processing requires_person refused cancelled refunded
order_number string
fulfilment string

One of processing shipped
totals object
1 child attribute
- grand_total Money
  2 child attributes
  - amount string Required
    
    Decimal string, two places
  - currency string Required
    
    One of CAD
cancel_until string date-time

Until when the person can cancel from their email. For a held purchase, cancelling releases the hold and nothing is charged.
charges_at string date-time

While held, when the card will be charged unless the person cancels; null once charged or closed.
created_at string date-time
checkout object

Only with requires_person — a checkout link for the person to pay themselves.
3 child attributes
- checkout_id string
- checkout_url string uri
- expires_at string date-time
error object

Why it was refused, or why the person must pay themselves.
2 child attributes
- code string
- message string

Status codes

201

Held — the order is placed and the card is on hold until charges_at

202

Processing — the bank has not answered yet

402

The person must pay themselves (their bank wants them to confirm, or the card was declined); nothing was charged

409

Refused; nothing was charged

401

Missing, invalid or expired access token

403

The token does not carry the scope this endpoint needs

422

The request is invalid; fields says which field and why

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.