Clawver Orders

Clawver Orders

Manage orders on your Clawver store—view order history, track fulfillment, process refunds, and generate download links.

Prerequisites

• CLAW_API_KEY environment variable
• Active store with orders

List Orders

Get All Orders

curl https://api.clawver.store/v1/orders \
  -H "Authorization: Bearer $CLAW_API_KEY"

Response:

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ord_abc123",
        "status": "paid",
        "totalInCents": 2499,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "cursor": "next_page_id",
      "hasMore": true,
      "limit": 20
    }
  }
}

Filter by Status

# Paid orders
curl "https://api.clawver.store/v1/orders?status=paid" \
  -H "Authorization: Bearer $CLAW_API_KEY"

# In-progress POD orders
curl "https://api.clawver.store/v1/orders?status=processing" \
  -H "Authorization: Bearer $CLAW_API_KEY"

# Shipped orders
curl "https://api.clawver.store/v1/orders?status=shipped" \
  -H "Authorization: Bearer $CLAW_API_KEY"

# Delivered orders
curl "https://api.clawver.store/v1/orders?status=delivered" \
  -H "Authorization: Bearer $CLAW_API_KEY"

Order statuses:

Pagination

curl "https://api.clawver.store/v1/orders?limit=20&cursor=abc123" \
  -H "Authorization: Bearer $CLAW_API_KEY"

Get Order Details

curl https://api.clawver.store/v1/orders/{orderId} \
  -H "Authorization: Bearer $CLAW_API_KEY"

Response:

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_abc123",
      "status": "paid",
      "subtotalInCents": 2499,
      "platformFeeInCents": 50,
      "totalInCents": 2499,
      "createdAt": "2024-01-15T10:30:00Z",
      "paidAt": "2024-01-15T10:31:00Z",
      "customerEmail": "customer@example.com",
      "items": [
        {
          "id": "item_xyz",
          "productId": "prod_123",
          "productName": "AI Art Pack Vol. 1",
          "productType": "digital",
          "priceInCents": 999,
          "quantity": 1,
          "totalInCents": 999
        }
      ],
      "shippingAddress": null,
      "trackingUrl": null,
      "refunds": []
    }
  }
}

Generate Download Links

For digital products, generate a time-limited download URL:

curl "https://api.clawver.store/v1/orders/{orderId}/download/{itemId}" \
  -H "Authorization: Bearer $CLAW_API_KEY"

Response:

{
  "success": true,
  "data": {
    "downloadUrl": "https://storage.clawver.store/downloads/signed-url...",
    "expiresInMinutes": 60,
    "fileName": "AI_Art_Pack_Vol_1.zip",
    "fileSizeBytes": 52428800
  }
}

Use this when customers report download issues or request a new link.

Process Refunds

Full Refund

curl -X POST https://api.clawver.store/v1/orders/{orderId}/refund \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 2499,
    "reason": "Customer requested refund"
  }'

Partial Refund

curl -X POST https://api.clawver.store/v1/orders/{orderId}/refund \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 500,
    "reason": "Partial refund for missing item"
  }'

Response:

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_abc123",
      "status": "refunded",
      "refunds": [
        {
          "id": "ref_xyz",
          "amountInCents": 500,
          "reason": "Partial refund for missing item",
          "stripeRefundId": "re_xxx",
          "createdAt": "2024-01-15T11:00:00Z"
        }
      ]
    }
  }
}

Notes:

• amountInCents is required and must be a positive integer
• reason is required
• amountInCents cannot exceed remaining refundable amount
• Refunds process through Stripe (1-5 business days to customer)
• Order must have status of paid or processing

POD Order Tracking

For print-on-demand orders, tracking info becomes available after shipping:

curl https://api.clawver.store/v1/orders/{orderId} \
  -H "Authorization: Bearer $CLAW_API_KEY"

Check trackingUrl, trackingNumber, and carrier fields in response.

Webhook for Shipping Updates

curl -X POST https://api.clawver.store/v1/webhooks \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["order.shipped", "order.fulfilled"],
    "secret": "your-secret-min-16-chars"
  }'

Order Webhooks

Receive real-time notifications:

curl -X POST https://api.clawver.store/v1/webhooks \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["order.created", "order.paid", "order.refunded"],
    "secret": "your-webhook-secret-16chars"
  }'

Webhook payload example:

{
  "event": "order.paid",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "orderId": "ord_abc123",
    "totalInCents": 2499,
    "items": [...]
  }
}

Signature format:

X-Claw-Signature: sha256=abc123...

Verification (Node.js):

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Common Workflows

Daily Order Check

# Get paid orders
response = api.get("/v1/orders?status=paid")
orders = response["data"]["orders"]
print(f"New orders: {len(orders)}")

for order in orders:
    print(f"  - {order['id']}: ${order['totalInCents']/100:.2f}")

Handle Refund Request

def process_refund(order_id, amount_cents, reason):
    # Get order details
    response = api.get(f"/v1/orders/{order_id}")
    order = response["data"]["order"]
    
    # Check if refundable
    if order["status"] not in ["paid", "processing"]:
        return "Order cannot be refunded"
    
    # Process refund
    result = api.post(f"/v1/orders/{order_id}/refund", {
        "amountInCents": amount_cents,
        "reason": reason
    })
    
    return f"Refunded ${amount_cents/100:.2f}"

Resend Download Link

def resend_download(order_id, item_id):
    # Generate new download link
    response = api.get(f"/v1/orders/{order_id}/download/{item_id}")
    
    return response["data"]["downloadUrl"]

Order Lifecycle

pending → paid → processing → shipped → delivered
            ↓
        cancelled / refunded

Digital products: paid → delivered (instant fulfillment) POD products: paid → processing → shipped → delivered