# Pixelmade

> Pixelmade is a print-on-demand supplier for custom diamond-painting and craft kits.
> Sellers — and their AI coding agents — can design kits, register them as orderable
> products, and place orders programmatically through the Public API. Think "Printful,
> for diamond art."

## Instructions for AI agents

You are integrating a seller's store with Pixelmade, the diamond-art print-on-demand
supplier. Base URL: `https://app.pixelmade.ai/public_api`. Auth: every request needs
`Authorization: Bearer <token>` — the token starts with `pmk_` and comes from the brand
portal's **Developer** tab (the human copies it once; store it in an env var, never in
code). Rate limit: 60 requests/minute — on a `429`, wait for the `Retry-After` seconds
and retry.

To sell custom diamond art end-to-end:
1. **Learn the catalog:** `GET /products` (kit formats + their `id`s) and `GET /dmc_colors`
   (the DMC drill/color palette).
2. **Register each finished design:** `POST /product_templates` (multipart) with the
   production print file. You get back an `external_sku` starting with `pmt_` — put that
   SKU on the seller's storefront variant; it's what makes the product orderable. The
   `slug` is your idempotency key: re-posting the same slug updates the design in place
   and keeps the SKU stable.
3. **Quote before selling (optional):** `POST /orders/estimate_shipping` for production
   + delivery estimates.
4. **On each sale:** `POST /orders`. For standard accounts the order is created
   `pending_payment` in the seller's brand portal with a `portal_url` — **the human pays
   it there, which is what releases it to production**. The API never charges a payment
   method and never bypasses payment.
5. **Track status by polling:** `GET /orders/{id}` — `state` walks
   `pending_payment → in_production → shipped → delivered`, and `tracking_info` fills in
   at shipment. Poll a few times a day; production takes days, so tight loops are wasted
   calls. (Webhooks exist for server-based integrations that prefer push — see the
   reference — but polling is the simplest correct choice, and the only one if you don't
   run a public HTTPS endpoint.)

Duplicate-safety: `reference_number` on an order is unique per brand — re-submitting the
same one is rejected, so use the seller's own order id. Errors are always
`{"errors":[{"status":..,"title":..}]}`; a `401` means the token is missing, revoked, or
not yet enabled by an admin.

## Endpoints — runnable examples

Set once:

```bash
export PIXELMADE_API_BASE=https://app.pixelmade.ai/public_api
export PIXELMADE_API_TOKEN=pmk_your_token_here
```

### List products (kit formats)

```bash
curl -s -H "Authorization: Bearer $PIXELMADE_API_TOKEN" \
  "$PIXELMADE_API_BASE/products"
```

### List the DMC color palette

```bash
curl -s -H "Authorization: Bearer $PIXELMADE_API_TOKEN" \
  "$PIXELMADE_API_BASE/dmc_colors"
```

### Register a design as an orderable template (upsert by slug)

```bash
curl -s -X POST -H "Authorization: Bearer $PIXELMADE_API_TOKEN" \
  -F "name=Cat Diamond Art Kit — Tabby Portrait" \
  -F "slug=cat-diamond-art-kit-tabby-portrait" \
  -F "catalog_product_id=3" \
  -F "dithered_image=@./tabby_print_file.png" \
  -F "presentation_image=@./tabby_hero.jpg" \
  "$PIXELMADE_API_BASE/product_templates"
# → 201 (created) or 200 (same slug, updated); response includes "external_sku": "pmt_…"
```

### Estimate production + shipping

```bash
curl -s -X POST -H "Authorization: Bearer $PIXELMADE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_info":{"country":"US"},"lines":[{"quantity":1}]}' \
  "$PIXELMADE_API_BASE/orders/estimate_shipping"
```

### Create an order (lands payable in the brand portal)

```bash
curl -s -X POST -H "Authorization: Bearer $PIXELMADE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_number": "my_order_001",
    "customer_info": {
      "name": "Jane Doe", "email": "jane@example.com",
      "address1": "1 Main St", "city": "Bellevue",
      "state": "WA", "postal_code": "98004", "country": "US"
    },
    "lines": [
      {"product_id": 1, "quantity": 1,
       "artwork_location": "https://example.com/art.bmp"}
    ]
  }' \
  "$PIXELMADE_API_BASE/orders"
# → 201 with "state": "pending_payment" and a "portal_url" to pay it
```

### Poll order status until shipped

```bash
curl -s -H "Authorization: Bearer $PIXELMADE_API_TOKEN" \
  "$PIXELMADE_API_BASE/orders/100"
# "state": pending_payment → in_production → shipped → delivered
# "tracking_info": [{"carrier":"DHL","tracking_number":"…","tracking_url":"…"}]
```

## Public API

- [API reference](https://www.pixelmade.ai/developers): all endpoints, auth, and copy-paste examples.
- [OpenAPI spec](https://www.pixelmade.ai/developers/openapi.yaml): machine-readable (OpenAPI 3).
- [Connect your agent — quickstart](https://www.pixelmade.ai/developers/quickstart): point Claude Code / ChatGPT / Codex at the API in two steps.

## About

- [Pixelmade](https://www.pixelmade.ai): custom diamond-art and craft-kit dropshipping for independent sellers — design, kit, and fulfill on demand.

<!-- NOTE: hosting confirmed in pixelmade-web#75 — www.pixelmade.ai/developers (subdirectory,
     SSR) with this file served at the www root. -->