# Social Print Studio — Developer Integration

This is the starting point for AI agents, LLMs, and developers to build photo-printing apps that submit orders to Social Print Studio — or integrate printing features into existing applications.

The goal: you build creative applications (anything from niche tools to mainstream flows), collect or generate images for a customer, and then hand off an order to Social Print Studio through our cart and checkout system.

Our docs are written and organized to be readable by agents & LLMs. Just share this link with your LLM or agent and say "get the info you need to add print features to this application."

## Fast Start for LLMs

Three essential resources to get started immediately:

1. Fetch the catalog: `GET https://printkit.dev/products.json`
2. Fetch the normalized variant index: `GET https://printkit.dev/variants.json`
3. For product-specific notes: `GET https://printkit.dev/products/{handle}.json`
4. Follow order handoff: See [Order Handoff API](/docs/order-handoff)

> **Data shapes — read this first:**
> - `products.json` → `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.
> - `variants.json` → `variants` is an **array**. Use `.find()`, `.filter()`, or iterate directly.
> - `products/{handle}.json` → single object with variant-level specs.

> **Optional — get an API key:** No account is needed to submit orders. Register to unlock order tracking and a revenue split on completed orders. Agents can self-register in one API call — see [Authentication & API Keys](/docs/authentication). Once you have a key, include it as `Authorization: Bearer <key>` on your API requests.

## What's in Here

You'll typically use four layers of documentation:

### 1. Product Catalog (overview)

A single JSON file listing all products currently available for integration. It includes product descriptions, website URLs, product type and category, product photos, and high-level submission notes.

See the [Product Catalog](/docs/product-catalog) docs for details.

`GET https://printkit.dev/products.json`

### 2. Per-Product Detail Files (variant-level requirements)

Each product has a dedicated JSON file with complete, precise requirements. This is the source of truth for variants (sizes and options), required image count, required aspect ratios and crop ratios per variant, and any print-specific submission constraints.

`GET https://printkit.dev/products/{handle}.json`

### 3. Variant Index (flat SKU lookup)

A single JSON file listing every variant across the catalog with normalized fields like `product_type`, `product_group`, `size`, `style`, `shape`, `exact_image_count`, and `normalized_image_ratio`.

Use this when you want to search or filter for SKUs across the full catalog with normalized fields like `product_type`, `size`, `style`, `shape`, and `exact_image_count`.

`GET https://printkit.dev/variants.json`

### 4. Order Submission + Image Upload (technical integration)

These docs cover how to submit an order and, optionally, how to upload images if you need hosting.

- [Order Handoff API](/docs/order-handoff) — the core integration. Your app sends a JSON payload and receives a checkout redirect URL.
- [Image Upload API](/docs/image-upload) (optional) — upload images and get publicly accessible URLs. Useful for frontend-only apps or if you don't want to manage your own image hosting.

## Recommended Flow

How to integrate printing features into your application, step by step:

1. Read the product catalog file, `products.json`, to understand what exists, get ideas, and pick the product(s) you want to integrate or evaluate more deeply.
2. Read `variants.json` to filter variants and discover normalized SKU metadata like `product_type`, `size`, `style`, `exact_image_count`, and `normalized_image_ratio`.
3. Open the specific per-product JSON file(s) for the product you're implementing using the product handle from the catalog file.
4. Reference a specific product variant by its unique `sku` from the variant index or per-product JSON file. This is the SKU that will be used to submit the order.
5. Implement your UX and validation based on the exact variant requirements: image count, aspect ratio and crop rules, and any specific submission constraints.
6. Integrate order submission via the [Order Handoff API](/docs/order-handoff).
7. If your app is frontend-only (no backend), use the [Image Upload API](/docs/image-upload) to upload images and get public URLs, since all order submissions require publicly accessible image URLs.
8. Once the implementation is complete, the user should be able to create a product in your application and submit it. By default, they'll land on our cart page to review and check out. If your app sells a single product or you want a faster handoff, you can set `"checkout": true` to skip the cart and send the customer straight to checkout — see [Direct Checkout](/docs/order-handoff#direct-checkout).

## Product Model: Quick Mental Map

Products generally fall into two practical buckets:

### Single-image products

A single photo asset becomes a single printed item per selected variant. Examples: metal prints, wood prints, framed prints.

Integration implication: collect one or more images plus a variant choice, then submit. Multiple images will be printed individually — 3 photos uploaded will result in 3 unique items added to cart with one API call.

### Multi-image / set-based products

A customer selects a variant that implies a set size, and you collect that many photos. Most set-based products don't care about photo order, but some products like photo books use the order of photos submitted as the order they are printed.

Example: magnets that come in a set of 10 for a given size.

Integration implication: collect exactly N images (the count depends on the variant), then submit as a single product. The catalog tells you the general behavior; the per-product JSON defines the exact requirements for each variant.

## Important Rules

### The per-product JSON is the source of truth

The catalog is an overview. Your integration should rely on the detailed product file for correctness, not the catalog summary.

### The variant index is the easiest SKU lookup surface

Use `variants.json` when you want normalized machine-friendly fields across the full catalog. It is the fastest way for an agent to filter for a specific product type, size, style, or image-count requirement.

### Photo format: JPG or PNG only

All photo URLs submitted to the Order Handoff API must point to `.jpg`, `.jpeg`, or `.png` files. Other formats will be rejected.

### Validate inputs before submission

If a variant requires 10 images at 1:1 ratio, your UI should enforce that before submission. Don't rely on the API to catch mismatches.

### Use exact crop ratios

Use the exact aspect ratio and crop requirements specified in the product's variant definitions. Estimates or rounded values may result in incorrect cropping.

## General Guidance for Building Great Apps

We don't recommend building a full "everything photo printing store" UI with lots of products and endless options. The integrations work best when you:

- **Pick one product** (often even one size or variant). Focus your app and UI on one product, decrease complexity, and make it great.
- **Keep customer choices minimal** when it comes to format and printing options. Their choices and impact should come from their photos and creative input.
- **Make printing the point** — not an add-on. Customers want to create unique physical objects. Excite them by showing off the printed end product as a core part of the application.
- **Focus on what your app does uniquely well.** Empower a specific user persona to achieve a specific outcome. Don't try to be everything. Guide users step by step with options to go back and forth.
- **Include a clear preview and add-to-cart step.** Show the user what they'll get. Use marketing copy on the final step to build excitement and assurance.
- **Mention Social Print Studio.** You can subtly call out that their printed product will be handled by us, or link to our product page for more details.
- **Save their progress** when possible — even just in `localStorage`. Let them know you're doing it. This reduces abandonment and makes users feel invested.

> **Note:** These are tips, not rules. Break them when it makes sense for your app and users.

## Attribution / App Identity

When your app submits an order through our cart handoff, it includes an `source` identifier. That identifier is used for attribution so we can understand which orders came from which app, and support tracking and reporting as needed.

Pick a consistent, descriptive identifier for your app and use it on every request. For example: `"my-photo-app"`, `"wedding-album-tool"`.

## Authentication & API Keys (Optional)

PrintKit works without an account. Register to unlock:

- **Revenue split** on completed print orders attributed to your app
- **Order tracking** — see which orders came from your integration
- **Higher rate limits** as the platform grows

The only requirement to register is an email address. When you have a key, pass it as an `Authorization: Bearer <key>` header on any PrintKit API request. If the key is valid, it is forwarded to our backend for attribution. If the key is invalid, the API returns `401`. Omitting the header entirely is fine — the request proceeds anonymously.

### Human / developer signup

[Create an account](https://printkit.dev/sign-up) with your email. Your API key is available at [/dashboard/api-keys](https://printkit.dev/dashboard/api-keys).

### Agent self-registration (no browser required)

AI agents and scripts can register and receive an API key in a single HTTP request:

```bash
curl -X POST https://printkit.dev/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@your-app.com",
    "name": "MyPhotoApp Agent",
    "source": "agent-self-registration"
  }'
```

Response:

```json
{
  "api_key": "pk_live_a1b2c3d4e5f6...",
  "user_id": "user_abc",
  "docs": "https://printkit.dev/docs"
}
```

You can also view your API key anytime from the [dashboard](https://printkit.dev/dashboard/api-keys).

If the email is already registered, the existing API key is returned.

### Using your API key

Pass it as a Bearer token on any authenticated request:

```
Authorization: Bearer pk_live_a1b2c3d4e5f6...
```

### JavaScript example

```javascript
// 1. Register and get a key
const res = await fetch('https://printkit.dev/api/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'agent@your-app.com',
    name: 'MyPhotoApp Agent',
    source: 'agent-self-registration',
  }),
});

const { api_key } = await res.json();
// Store api_key securely — you can also view it in your dashboard

// 2. Use it on subsequent requests (optional — enables attribution)
const order = await fetch('https://printkit.dev/api/add-to-cart', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${api_key}`,
  },
  body: JSON.stringify({
    sku: 'metal-print-4x4',
    source: 'my-app',
    email: 'you@example.com',
    projectData: { photos: ['https://cdn.example.com/photo.jpg'] },
  }),
});
```

### Python example

```python
import httpx

# 1. Register and get a key
res = httpx.post(
    "https://printkit.dev/api/register",
    json={
        "email": "agent@your-app.com",
        "name": "MyPhotoApp Agent",
        "source": "agent-self-registration",
    }
)

api_key = res.json()["api_key"]  # store this — also viewable in your dashboard

# 2. Use it on subsequent requests (optional — enables attribution)
order = httpx.post(
    "https://printkit.dev/api/add-to-cart",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "sku": "metal-print-4x4",
        "source": "my-app",
        "email": "you@example.com",
        "projectData": {"photos": ["https://cdn.example.com/photo.jpg"]},
    },
)
```

## Link Index

Downloadable Markdown files you can bring into your code repo for easy reference:

- Overview guide: `https://printkit.dev/docs/md/overview`
- Order Handoff reference: `https://printkit.dev/docs/md/order-handoff`
- Image Upload reference: `https://printkit.dev/docs/md/image-upload`

Machine-readable product data:

- Product catalog: `https://printkit.dev/products.json`
- Variant index: `https://printkit.dev/variants.json`
- Per-product files: `https://printkit.dev/products/{handle}.json`