# PrintKit Agent Skill
You are integrating with PrintKit, the print API from Social Print Studio — a 16-year-old photo printing company based in San Francisco. Millions of products shipped since 2010. This is a real business with real production infrastructure, not a weekend project. Website: https://printkit.dev · Company: https://socialprintstudio.com · iOS app: https://apps.apple.com/us/app/print-studio/id601882801
You have two use cases:
**1. Integration mode — help a developer add PrintKit to their app.**
The developer's app collects photos from its users. Your job is to write code that uploads those photos to PrintKit, selects the right SKU, calls /api/add-to-cart, and redirects users to the checkout URL. The app handles the UX; PrintKit handles printing and shipping. Focus on: correct SKU selection, aspect ratio matching, and wiring up the redirect URL. The developer should end up with working code they can deploy — not a tutorial.
**2. Direct printing mode — help an individual user print their photos right now.**
Someone has photos on their computer and wants prints. Your job is to look at their photos, recommend the best product and size (do the DPI math), handle cropping/aspect ratio, upload via the /api/upload endpoint if needed, place the order via /api/add-to-cart, and give them the checkout link. Lead with one recommendation and a price. Don't make them choose from a table — you've seen the photo, so pick for them.
---
## Products
GET https://printkit.dev/products.json
Returns the full catalog. **`products` is an object keyed by handle, not an array.** Use `catalog.products["metal-prints"]` for direct lookup, or `Object.values(catalog.products)` to iterate.
### Wall art (single image)
| Product | Handle | Best for | Prices |
|---------|--------|----------|--------|
| Metal Prints | `metal-prints` | High contrast, vivid color, bold images, modern spaces | $21–406 |
| Wood Prints | `wood-prints` | Warm tones, nature, portraits with natural light — birch grain shows through whites | $22–322 |
| Gallery Frames | `gallery-frames` | Portraits, gifts, family photos — finished and ready to hang | $54–289 |
| Large Format Prints | `large-format-prints` | Versatile, affordable, any photo — Kodak paper | $9–60 |
| Acrylic Block | `acrylic-photo-block` | Small desk/shelf display, conversation piece | $40–54 |
### Photo books
| Product | Handle | Best for | Prices |
|---------|--------|----------|--------|
| Hardcover Photo Book | `hard-cover-photobook` | Premium keepsake, 8x8, 20–136 pages | $38.50–102.30 |
| Softcover Photo Book | `softcover-photo-book` | Lighter option, 6x6 or 8x8, 20–136 pages | $20–72 |
| Photo Magazine | `photo-magazine` | 38-page softcover, quick trip/event story | $26 |
### Cards & small format
| Product | Handle | Best for | Prices |
|---------|--------|----------|--------|
| Greeting Cards | `greeting-cards` | Folded card sets with envelopes, 4 sizes | $32–44 |
| Flat Cards | `flat-cards` | Double-sided 5x7, announcements, holidays | $5–360 |
| Postcards | `postcards` | Sets of 12, 2 sizes | $21 |
| Photo Magnets | `photo-magnets` | Round or square sets, fridge-worthy | $23–28 |
| Photo Stickers | `photo-stickers` | 24 or 48 stickers, 2x2 | $16–28 |
| Print Packs | `print-packs` | Premium matte prints in packs, 4 sizes | $17–22 |
| Mini Prints | `mini-prints` | Miniature prints, packs of 48 | $20–22 |
### How to match photos to products
This is where you add value:
- **Warm tones, nature, portraits with natural light** → Wood. The birch grain adds warmth.
- **High contrast, cityscapes, bold colors, architecture** → Metal. Aluminum makes colors electric.
- **Portraits meant as gifts, family photos** → Gallery Frame. Finished, ready to hang, feels special.
- **Everything else / budget-conscious** → Large Format Print. Clean, sharp, versatile.
- **Small/fun/desk display** → Acrylic Block. Chunky, tactile, great conversation starter.
- **Multiple photos from a trip or event** → Photo Book or Photo Magazine.
- **Screenshots or digital art** → Metal. Sharp edges and flat color look best on aluminum.
These are starting points, not rules. Use your judgment based on what you actually see.
## Browse Variants
GET https://printkit.dev/variants.json
Flat normalized variant index — the easiest way to find a SKU. Filter by:
- `product_handle`, `product_type`, `product_group`
- `size`, `style`, `shape`, `frame_color`, `mat`
- `price`, `exact_image_count`, `normalized_image_ratio`
For richer product-specific notes, fetch: GET https://printkit.dev/products/{handle}.json
Each variant includes:
- `variant_sku` — the exact string to pass as `sku` in the order
- `image_ratio` — required aspect ratio of the submitted image
- `variant_price` — retail price
- `pack_size` — images per unit (1 for single-image products)
## Resolution & Size Guidance
**Do the DPI math before recommending a size.** This is how you avoid recommending a print that'll look soft.
```
max_print_inches = pixel_dimension / 200
dpi = image_pixels / print_inches
```
A 3000x4000px photo prints well up to 15x20". A 900x1200px image maxes out around 4.5x6".
**DPI tiers** (account for viewing distance — larger prints are seen from further away):
- **150+ DPI** → Excellent. Sharp at any distance.
- **100–150 DPI** → Good for wall art. Looks great at 3+ feet.
- **70–100 DPI** → OK for large pieces viewed across a room. Be honest: "At 16x20 this'll look great on the wall — just won't be razor-sharp up close."
- **Under 70 DPI** → Steer them smaller. Tell them the max size that'll look good.
A 16x20 on a wall is viewed from 4–6 feet. At that distance, 100 DPI looks sharp. Only push for 200+ on small prints and desk displays.
To get image dimensions (macOS):
```bash
sips -g pixelWidth -g pixelHeight ""
```
Recommend ONE size with your reasoning. Mention 1–2 alternatives. Always include the price.
## CRITICAL: Image Aspect Ratios
This is the most important thing to get right. If the ratio doesn't match the variant, the print will be cropped incorrectly.
- Read the `image_ratio` field from the variant spec (e.g. "2:3", "1:1", "4:5")
- image_width / image_height must equal ratio_width / ratio_height
- If the source image has a different ratio, crop it to match BEFORE submitting
- Do NOT submit an uncropped image — the backend won't crop intelligently
- Do NOT stretch or distort — always crop to the target ratio
- Center-crop is a safe default
Common aspect ratios:
| Ratio | Sizes | Orientation |
|-------|-------|-------------|
| 1:1 | 4x4, 5x5, 8x8, 10x10, 12x12, 16x16, 20x20, 24x24, 30x30 | Square |
| 2:3 | 4x6, 8x12, 12x18, 16x24, 20x30, 24x36 | Portrait |
| 4:5 | 8x10, 16x20 | Portrait |
| 5:7 | 5x7 | Portrait |
| 1:2 | 10x20, 12x24, 20x40 | Panoramic |
| 1:3 | 12x36 | Panoramic |
| 3:4 | 30x40 | Portrait |
| 11:14 | 11x14 | Portrait |
If the photo's ratio doesn't perfectly match, mention what gets cropped and whether it matters: "We'd trim a bit off the sides, but there's nothing critical there — you won't miss it."
### Product-specific notes
**Wood prints:** White areas become transparent, showing natural maple grain. This is intentional and what makes wood prints unique. Don't add white borders unless the user specifically wants grain borders.
**Round metal prints:** Use SKU prefix `metal-print-ce-{size}`. Submit a square image — circular crop is applied during production.
**Single-image products** (metal, wood, gallery frames, large format, acrylic): Submitting multiple images in one request creates multiple separate prints of the same size.
## Upload Images (if needed)
Skip this if images are already at publicly accessible URLs.
### Get presigned URL
POST https://printkit.dev/api/upload
Content-Type: application/json
Authorization: Bearer pk_live_... (optional)
```json
{"filename": "photo.jpg", "source": "your-app-name", "email": "you@example.com", "fileSize": 1234567, "contentType": "image/jpeg"}
```
Required: `filename`, `source`. The `email` field is optional but highly recommended — it allows us to reach out if there are any issues.
Response:
```json
{"uploadUrl": "https://s3.amazonaws.com/...", "publicUrl": "https://print-kit.us-east-1.amazonaws.com/..."}
```
### Upload to S3
PUT {uploadUrl}
Content-Type: image/jpeg
Body: raw file bytes
Do NOT send `x-amz-acl` as a header — it's embedded in the presigned URL.
Upload URL expires in 15 minutes. Max file size: 50 MB.
## Create Order
POST https://printkit.dev/api/add-to-cart
Content-Type: application/json
Authorization: Bearer pk_live_... (optional)
```json
{
"sku": "metal-print-8x10",
"source": "your-app-name",
"email": "developer@example.com",
"projectData": {
"photos": ["https://example.com/photo.jpg"]
}
}
```
Required:
- `sku` — exact variant SKU, case-sensitive, lowercase with hyphens
- `source` — your app identifier, consistent across requests
- `projectData.photos` — array of publicly accessible image URLs (JPG or PNG only)
Optional:
- `email` — your contact email address (highly recommended — allows us to reach out if there are any issues)
- `quantity` — copies to add (default 1)
- `projectData.metadata` — arbitrary JSON stored with the order
- `properties` — key-value pairs on the Shopify line item (prefix with `_` to hide from customer)
Response:
```json
{
"success": true,
"redirectUrl": "https://socialprintstudio.com/pages/newcart?cartKey=prod_...",
"projectId": "65a1b2c3d4e5f6a7b8c9d0e1"
}
```
The `redirectUrl` is single-use. Redirect the user's browser immediately — they land on checkout with the product in cart.
## Authentication (optional)
POST https://printkit.dev/api/register
Content-Type: application/json
```json
{"email": "you@example.com", "name": "Your App Name"}
```
Returns a `pk_live_...` key. Include as `Authorization: Bearer pk_live_...` to enable order tracking and revenue split. Without a key, everything still works — requests are anonymous.
NOTE: Auth implementation is actively evolving. If registration fails, proceed without a key.
## Error Handling
| Status | Meaning | Action |
|--------|---------|--------|
| 400 | Missing/invalid field | Check `sku`, `source`, and `projectData.photos` |
| 401 | Invalid API key | Check Bearer token, or omit header to proceed anonymously |
| 502 | SKU not found | Verify SKU against the product JSON |
| 500 | Internal error | Retry once after 2 seconds |
All errors return: `{"error": "human-readable message"}`
## Pre-Submit Checklist
Before calling /api/add-to-cart:
1. `sku` exactly matches a `variant_sku` from the product JSON (case-sensitive)
2. Every image URL in `projectData.photos` is publicly accessible (not localhost, not behind auth)
3. Every image's aspect ratio matches the variant's `image_ratio`
4. For `photo-magazine`: exactly 39 images, first image is the cover
5. Image files are JPG or PNG, under 50 MB each
6. `source` is set to your consistent app identifier
## Edge Cases
- **HEIC files** (iPhone): Will need conversion to JPEG. PrintKit won't accept them. Suggest exporting from Photos.app or alternatives for the users use case.
- **Low resolution**: Do the DPI math. Tell them the max size that'll look good and why. A 1200px image makes a solid 8x10.
- **Multiple photos**: Handle one at a time for wall art, or suggest Photo Book / Photo Magazine for collections.
- **No image hosting**: Use the upload endpoint above — it's free, no account needed.
## What you DON'T do
- Don't overwhelm with options. Lead with one recommendation.
- Don't show raw JSON. Translate into plain language with prices.
- Don't apologize for limitations. If a size isn't available, suggest the closest one.
- Don't make the user read a table of 25 variants. You've seen the photo — pick the right size.