printkk-print-on-demand

name

printkk-print-on-demand

description

Domain knowledge for using PrintKK print-on-demand API tools effectively. PrintKK is a print-on-demand platform that lets sellers create custom products, manage designs, upload images, and fulfill orders via API. Use this skill whenever the user wants to interact with PrintKK — browsing products, creating designs, placing orders, managing images, or building integrations with the PrintKK API. Also trigger when the user mentions "PrintKK", "print on demand", "POD fulfillment", custom product design workflows, or wants to automate their PrintKK store operations.

PrintKK

PrintKK is a print-on-demand platform that connects sellers with production and fulfillment for custom products — apparel, home decor, accessories, and more. Use the API to automate design creation, product browsing, order placement, and image management.

Base URL: https://api.printkk.com/pkk-openapi

API Scope & Limitations

The API covers internal PrintKK operations only:

• ✅ Image upload & management
• ✅ Design creation & editing
• ✅ Order creation, payment, tracking
• ✅ Product catalog browsing
• ❌ No publishing — you cannot publish designs to external sales channels (Shopify, Etsy, etc.) via API. Publishing must be done through the PrintKK Dashboard.
• ❌ No shop/store management — the API does not expose multi-shop operations. Although PrintKK accounts support multiple stores, the API operates at the account level without shop scoping.
• ❌ No print provider selection — PrintKK uses its own production network. Unlike marketplace-model platforms, there is no API for choosing print providers. Production routing is handled internally by PrintKK.

Authentication

All requests require an Api-Key header.

• Get your key: PrintKK Dashboard → Settings → Api Management
• Keys expire — validity extends 90 days per renewal
• Renewal only allowed when remaining validity ≤ 7 days
• Expired keys cannot be renewed; generate a new one

Api-Key: <your-api-key>

Response Format

All responses follow this structure:

{
  "code": 200,
  "success": true,
  "msg": "OK",
  "data": { ... }
}

Check success field first, not just HTTP status code.

Data Model

Product (catalog)          Image (media library)
  ├── productCode             ├── imageId
  ├── printAreas[]            ├── folderId
  └── specifications[]        └── keywords
         │                         │
         ▼                         ▼
      Design ◄────────────── uses imageId per printArea
        ├── designCode
        ├── designSpecifications[]
        │     └── designSpecificationCode
        └── taskId (async creation)
                │
                ▼
            Order
              ├── orderId
              ├── designSpecificationCode + quantity
              ├── shippingAddress
              └── shippingType priority list
                      │
                      ▼
                  Payment (wallet)

Key relationships:

• A Product is a catalog template (e.g. "Unisex T-Shirt"). You don't create products — you browse them.
• A Design applies your images to a Product's print areas. Creating a design is async — you get a taskId, then poll for completion.
• An Order references designSpecificationCode (a specific size/color variant of your design), NOT the product directly.
• Images must be uploaded before creating designs. The imageId returned from upload is used in design creation.

Core Workflows

Workflow 1: Create a Design and Place an Order

This is the most common end-to-end flow. Follow these steps in order — skipping steps will fail.

1. Browse products     GET  /api/v1/product/page
2. Get product detail  GET  /api/v1/product/{productCode}
   → Note the printAreas and their printAreaCodes
   → Note isWhole (1=full coverage, 0=fragment/placement)
3. Upload image        POST /api/v1/image
   → Returns imageId
4. Create design       POST /api/v1/design
   → Returns taskId (NOT designCode yet!)
5. Poll task status    GET  /api/v1/design/task/{taskId}
   → Wait for designTaskStatus = "completed"
   → Now you have designCode
6. Get design detail   GET  /api/v1/design/{designCode}
   → Get designSpecificationCode for the variant you want
7. Create order        POST /api/v1/order
   → Use designSpecificationCode + quantity
8. Pay with wallet     POST /api/v1/pay/wallet
   → orderId required, wallet must have sufficient balance

Workflow 2: Brand Design Flow

For sellers with branded product lines:

1. List brand groups       GET  /api/v1/design/brand-group/list
2. Browse brand designs    GET  /api/v1/design/brand/page
3. Create brand design     POST /api/v1/design/brand
   → Requires brandName (max 50 chars)
   → Same async flow: returns taskId, poll for completion

Workflow 3: Image Management

Create folder    POST   /api/v1/image/folder
List folders     GET    /api/v1/image/folder/list
Upload image     POST   /api/v1/image          (multipart/form-data)
Browse images    GET    /api/v1/image/page
Update metadata  PUT    /api/v1/image/{imageId}

Gotchas & Constraints

Design Creation is Async

This is the #1 mistake. POST /api/v1/design does NOT return a design — it returns a taskId. You must poll GET /api/v1/design/task/{taskId} until designTaskStatus is "completed" before you can use the design. Status progression: pending → generating → completed.

isWhole Matters

When creating a design, isWhole must match the product's print area type:

• 1 = whole (full-surface print, e.g. all-over print t-shirt)
• 0 = fragment (placement print, e.g. logo on chest)

Using the wrong value will produce incorrect output.

imageFillingMode

Each print area requires an imageFillingMode:

• cover — image fills the entire area, may crop edges
• contain — image fits within the area, may have blank space
• fill — image stretches to fill exactly, may distort

Shipping Type is a Priority List

shippingType in order creation is not a single choice — it's an ordered array of all three options. The order determines fallback priority:

"shippingType": ["economy", "standard", "express"]

All three values must be present. Put your preferred option first.

Order Can Only Be Modified When Pending

• Order Address Update and Order Cancel only work on orders with status pendingPayment
• Once paid (waitingForFulfillment and beyond), the order is locked

Design Immutability

Once a design has been ordered, exported, or published, its status becomes immutable. You can no longer update it — you'd need to create a new design.

Pagination Defaults

All paginated endpoints default to current=1, size=10, max size=50. If you need all records, loop through pages.

Image Upload Constraints

• Accepted formats: JPG, JPEG, PNG only
• Max file size: 100MB
• fileName max length: 50 characters
• Upload is multipart/form-data, not JSON

Order Status Lifecycle

pendingPayment → waitingForFulfillment → beingFulfilled → partiallyShipped → shipped → completed
       │
       └→ canceled → closed

Rate Limit

Default: 60 requests/minute. Exceeding this returns Too Many Requests. When polling design task status, add reasonable delays (2–3 seconds) between calls.

No Webhooks

PrintKK does not provide webhooks. To track order status or design task completion, you must poll the relevant endpoints. Design task polling is mandatory; order status polling is optional but recommended for automation.

Timestamps

All timestamps are in fixed UTC-8 timezone (does NOT follow daylight saving). Response format: MM/dd/yyyy HH:mm:ss. Date filter params in order pagination use yyyy-MM-dd HH:mm:ss format — note the inconsistency between input and output formats.

Product Types

Two product types exist:

• template — regular catalog products
• brand — brand-specific products (requires separate brand design flow)

Quick Reference: All Endpoints

Module	Method	Path	Summary
General	GET	/api/v1/general/ping	Health check
General	GET	/api/v1/general/time	Server timestamp
General	GET	/api/v1/general/country-list	Country list (ISO codes)
Auth	PUT	/api/v1/auth/renewal	Renew API key (≤7 days remaining)
Image	POST	/api/v1/image	Upload image (multipart)
Image	GET	/api/v1/image/page	List images (paginated)
Image	PUT	/api/v1/image/{imageId}	Update image metadata
Image	POST	/api/v1/image/folder	Create folder
Image	GET	/api/v1/image/folder/list	List all folders
Image	PUT	/api/v1/image/folder/{folderId}	Update folder
Image	DELETE	/api/v1/image/folder/{folderId}	Delete folder
Product	GET	/api/v1/product/category	Product categories
Product	GET	/api/v1/product/page	List products (paginated)
Product	GET	/api/v1/product/{productCode}	Product detail
Design	POST	/api/v1/design	Create design (async)
Design	GET	/api/v1/design/page	List designs (paginated)
Design	GET	/api/v1/design/{designCode}	Design detail
Design	PUT	/api/v1/design/{designCode}	Update design
Design	GET	/api/v1/design/task/{taskId}	Poll design task
Design	POST	/api/v1/design/brand	Create brand design
Design	GET	/api/v1/design/brand/page	List brand designs
Design	GET	/api/v1/design/brand-group/list	List brand groups
Order	POST	/api/v1/order	Create order
Order	GET	/api/v1/order/page	List orders (paginated)
Order	GET	/api/v1/order/{orderId}	Order detail
Order	PUT	/api/v1/order/address/{orderId}	Update address
Order	PUT	/api/v1/order/cancel/{orderId}	Cancel order
Order	POST	/api/v1/pay/wallet	Pay with wallet
Order	GET	/api/v1/pay/{orderId}	Query payment status