Purchases

Record and track purchases tied to contest entries

On this page

Purchases

Track purchases made by contest participants. Purchases can award points to entries based on your contest's purchase tracking configuration.

Record Purchase

POST/api/v1/contests/:contestId/purchases
Private API Key Required

Record a purchase for a contest participant. The participant will be awarded points based on the contest's purchase tracking settings. Duplicate purchases (same orderId) are detected and will not award points twice.

Path Parameters

contestIdstring required

The unique contest identifier

Request Body

emailstring required

Email address of the purchaser (must match an existing entry)

orderIdstring required

Unique order identifier from your system

amountnumber required

Purchase amount (must be greater than 0)

currencystring

Currency code (default: 'USD')

Request

curl -X POST https://blitzrocket.com/api/v1/contests/clx1abc123/purchases \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "orderId": "order-12345",
    "amount": 49.99,
    "currency": "USD"
  }'

const contestId = "clx1abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/purchases`,
  {
    method: "POST",
    headers: {
      "x-api-key": "your_private_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "[email protected]",
      orderId: "order-12345",
      amount: 49.99,
      currency: "USD",
    }),
  }
);

const { data } = await response.json();
console.log(`Purchase recorded: ${data.pointsAwarded} points awarded`);

import requests

contest_id = "clx1abc123"
response = requests.post(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/purchases",
    headers={
        "x-api-key": "your_private_key_here",
        "Content-Type": "application/json"
    },
    json={
        "email": "[email protected]",
        "orderId": "order-12345",
        "amount": 49.99,
        "currency": "USD"
    }
)

data = response.json()["data"]
print(f"Purchase recorded: {data['pointsAwarded']} points awarded")

Response (201 Created)

{
  "success": true,
  "data": {
    "purchaseId": "purchase_xyz789",
    "entryId": "entry_abc123",
    "pointsAwarded": 50,
    "alreadyExists": false,
    "message": "Purchase recorded successfully"
  }
}

Response (200 - Duplicate)

If a purchase with the same orderId already exists, the API returns a 200 status to indicate it was already processed:

{
  "success": true,
  "data": {
    "purchaseId": "purchase_xyz789",
    "entryId": "entry_abc123",
    "pointsAwarded": 0,
    "alreadyExists": true,
    "message": "Purchase already recorded"
  }
}

Response Fields

purchaseIdstring

Unique identifier for the purchase record

entryIdstring

The entry that the purchase was associated with

pointsAwardednumber

Points awarded for this purchase (0 if duplicate)

alreadyExistsboolean

Whether this purchase was already recorded

messagestring

Human-readable status message

Error Responses

StatusErrorDescription
400Invalid request bodyMissing or invalid email, orderId, or amount
400Amount must be positiveThe amount value must be greater than 0
403Private key requiredThis endpoint requires a private API key
404Contest not foundNo contest exists with the given ID

Integration Example

Here's a complete example of integrating purchase tracking with a Shopify webhook:

app.post("/webhooks/shopify/order-created", async (req, res) => {
  const order = req.body;

  try {
    const response = await fetch(
      `https://blitzrocket.com/api/v1/contests/${CONTEST_ID}/purchases`,
      {
        method: "POST",
        headers: {
          "x-api-key": process.env.BLITZROCKET_PRIVATE_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          email: order.email,
          orderId: order.id.toString(),
          amount: parseFloat(order.total_price),
          currency: order.currency,
        }),
      }
    );

    const data = await response.json();
    console.log("Purchase tracked:", data);
    res.status(200).send("OK");
  } catch (error) {
    console.error("Failed to track purchase:", error);
    res.status(500).send("Error");
  }
});

from flask import Flask, request
import requests
import os

app = Flask(__name__)

@app.route("/webhooks/shopify/order-created", methods=["POST"])
def handle_order():
    order = request.get_json()

    try:
        response = requests.post(
            f"https://blitzrocket.com/api/v1/contests/{CONTEST_ID}/purchases",
            headers={
                "x-api-key": os.environ["BLITZROCKET_PRIVATE_KEY"],
                "Content-Type": "application/json"
            },
            json={
                "email": order["email"],
                "orderId": str(order["id"]),
                "amount": float(order["total_price"]),
                "currency": order["currency"]
            }
        )

        data = response.json()
        print(f"Purchase tracked: {data}")
        return "OK", 200
    except Exception as e:
        print(f"Failed to track purchase: {e}")
        return "Error", 500