Printora Partner Integration Example

A complete example implementation demonstrating how to integrate with the Printora Partner API. This project showcases the full integration flow including session creation, webhook handling, and order management.

Live Demo

Try it now: printora-example-integration.vercel.app/ai-image-app

This demo app ("DreamCanvas") simulates an AI image generation platform that integrates with Printora. Click any image, then click "Print on Product" to see the full partner integration in action.

How the Demo Works (End-to-End Flow)

User browses gallery — DreamCanvas shows a gallery of AI-generated images
User clicks an image — A detail modal opens showing the image, prompt, and creator info

User clicks "Print on Product" — The app calls Printora's Partner API:

POST https://api-staging.printora.ai/api/v1/partner-session
Body: { image_url, user_data: { email, name } }
Headers: { x-api-key: PRINTORA_API_KEY }

API returns a session token — A unique redirect URL is generated
User is redirected to Printora Editor — Opens staging.printora.ai/en/print/<token> in a new tab
User selects a product — Chooses from T-Shirts, Hoodies, Mugs, Posters, Home Decor
Design is previewed on product — The partner's image is rendered on the selected product mockup
User can customize & order — Select color, size, and complete checkout through Printora

The partner (DreamCanvas) receives webhook notifications for order lifecycle events (created, paid, shipped, delivered).

What This Example Demonstrates

This example integration shows how to:

Create Partner Sessions - Generate sessions with customer images and data, receiving redirect URLs for Printora's design editor
Handle Webhook Events - Receive and verify webhook events for order lifecycle updates (created, paid, shipped, delivered)
Order Dashboard - View and manage orders created through partner sessions

Integration Flow

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Your App      │    │  Printora API    │    │  Printora App   │
│                 │    │                  │    │                 │
│ 1. Create       │───▶│ 2. Generate      │───▶│ 3. Design &     │
│    Session      │    │    Session       │    │    Customize    │
│                 │    │                  │    │                 │
│ 5. Receive      │◀───│ 4. Send          │◀───│ Complete        │
│    Webhook      │    │    Webhook       │    │ Checkout        │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Requirements

Prerequisites

Before running this example, you need:

Node.js 20.9.0 or higher
npm, yarn, pnpm, or bun package manager
Printora Partner Credentials:
- API Key (PRINTORA_API_KEY)
- Webhook Secret (PRINTORA_WEBHOOK_SECRET)

Getting Printora Credentials

Register at the Printora Partner Dashboard to become a partner
Receive your partner API credentials:
- API Key (starts with pk_test_ for test environment)
- Webhook Secret (starts with whsec_)

Environment Variables

Create a .env.local file in the project root with the following variables:

# Required: Your Printora API credentials
PRINTORA_API_KEY=pk_test_your_api_key_here
PRINTORA_API_URL=https://api-staging.printora.ai
PRINTORA_WEBHOOK_SECRET=whsec_your_webhook_secret_here

# Required: Your application URL (for callbacks)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Optional: Environment
NODE_ENV=development

Note: See .env.example for a template.

Getting Started

Installation

Clone the repository:

git clone <your-repo-url>
cd example-integration

Install dependencies:

npm install
# or
yarn install
# or
pnpm install
# or
bun install

Set up environment variables:

cp .env.example .env.local

Edit .env.local and add your Printora credentials.

Run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 in your browser.

Project Structure

example-integration/
├── app/
│   ├── page.tsx              # Landing page (partner API docs overview)
│   ├── ai-image-app/         # DreamCanvas demo (AI gallery → Print on Product)
│   │   └── page.tsx          # Full demo with gallery, modal, session creation
│   ├── create-session/       # Session creation demo (simple form)
│   ├── dashboard/            # Order management dashboard
│   ├── callback/             # Success/failure pages
│   └── api/
│       └── webhooks/         # Webhook endpoint
├── components/
│   └── ui/                   # Reusable UI components
├── lib/
│   └── printora.ts           # Printora API client
└── docs/
    └── WEBHOOK-INTEGRATION.md # Detailed webhook documentation

Features

1. Session Creation

Create a partner session with customer data:

const response = await fetch('/api/partners/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': PRINTORA_API_KEY,
  },
  body: JSON.stringify({
    image_url: 'https://example.com/customer-image.jpg',
    user_data: {
      email: 'customer@example.com',
      name: 'Customer Name',
    },
  }),
});

2. Webhook Handling

Receive secure webhook events with signature verification:

// Webhook endpoint receives events:
// - order.created
// - order.paid
// - order.shipped
// - order.delivered

See docs/WEBHOOK-INTEGRATION.md for detailed webhook documentation.

API Reference

Authentication

All API requests require authentication using your Partner API Key in the Authorization header:

Authorization: Bearer partner_test_api_key_example

API Key Format:

Test mode: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxx
Live mode: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

Note: Replace the x characters with your actual API key received from Printora.

Base URLs

Environment	Base URL
Production	`https://api.printora.ai`
Staging	`https://api-staging.printora.ai`

Partner API Endpoints

Session Management

Create Partner Session

POST /api/v1/partner-session

Creates a new partner session and returns a redirect URL for the end-user.

Request Body:

{
  "image_url": "https://example.com/customer-image.jpg",
  "user_data": {
    "email": "customer@example.com",
    "name": "Customer Name"
  }
}

Response (201 Created):

{
  "session_id": "cc8930e4-621a-4a94-a483-34dd9de8ee90",
  "redirect_url": "https://printora.ai/customize?session=xxx",
  "image_url": "https://example.com/customer-image.jpg",
  "created_at": "2026-02-27T10:30:00Z"
}

Order Management

Get Partner Orders

GET /api/v1/partners/:partnerId/orders

Retrieve all orders created through your partner sessions.

Query Parameters:

Parameter	Type	Description
`limit`	number	Number of orders to return (default: 20)
`offset`	number	Number of orders to skip (default: 0)
`status`	string	Filter by order status

Response:

{
  "orders": [
    {
      "order_id": "ord_abc123",
      "session_id": "sess_x1y2z3",
      "status": "processing",
      "total_amount": 29.99,
      "currency": "USD",
      "created_at": "2026-02-27T10:40:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Webhook Events

Your webhook endpoint will receive notifications for the following events:

Event	Description
`order.created`	When a user completes checkout
`order.paid`	When payment is confirmed
`order.shipped`	When the order is shipped
`order.delivered`	When the order is delivered
`order.cancelled`	When an order is cancelled

Webhook Payload Example:

{
  "sessionId": "cc8930e4-621a-xxxxx-xxxxx",
  "event": "order.created",
  "data": {
    "order_id": "ord_abc123",
    "session_id": "sess_x1y2z3",
    "status": "pending",
    "total_amount": 29.99,
    "currency": "USD"
  },
  "timestamp": "2026-01-30T10:40:00Z"
}

Rate Limits

Metric	Limit
Requests per minute	60
Requests per day	10,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1738234567

Session Lifecycle

Understanding the session flow is important for integration:

Redirect URL expiry: 15 minutes from creation
Session expiry: 24 hours after user first accesses the redirect URL
Session statuses: pending → active → completed / expired / cancelled

API Scope

This API is designed exclusively for partner backend integration.

Partners CAN:

✅ Create print sessions for end-users
✅ Retrieve orders created through their sessions

Partners CANNOT:

❌ Access cart endpoints (internal frontend use only)
❌ Access checkout endpoints (internal frontend use only)
❌ Access user authentication or product management endpoints

Postman Collection

A complete Postman collection with all endpoints is available for testing:

View Postman Documentation →

Getting Started with Postman

Import the collection - Click "Run in Postman" on the documentation page
Set up your environment - Select the appropriate environment (Staging/Production)
Configure your API key - Update the PARTNER_API_KEY variable
Test the flow - Start with "Create Session" to test the integration
Review responses - Check the response examples to understand the data structure
Implement webhooks - Set up your webhook endpoint to receive order notifications

Deployment

Deploy to Vercel

The easiest way to deploy is using Vercel:

npm run deploy:vercel

Or push to your Git repository and import into Vercel.

Important: Add your environment variables in Vercel's dashboard:

PRINTORA_API_KEY
PRINTORA_API_URL
PRINTORA_WEBHOOK_SECRET
NEXT_PUBLIC_APP_URL

Other Platforms

This Next.js app can be deployed to any platform that supports Next.js:

Vercel (recommended)
Netlify
AWS Amplify
Railway
Render
Self-hosted

Documentation

Support

For issues or questions:

Check the Printora Integration Documentation
Contact Printora support
Open an issue in this repository

License

This example code is provided as-is for integration purposes.

Tech Stack

Framework: Next.js 16
Language: TypeScript
Styling: Tailwind CSS
UI Components: Radix UI
Validation: Zod
Environment: @t3-oss/env-nextjs

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
app		app
components		components
docs		docs
lib		lib
public		public
types		types
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

Printora Partner Integration Example

Live Demo

How the Demo Works (End-to-End Flow)

What This Example Demonstrates

Integration Flow

Requirements

Prerequisites

Getting Printora Credentials

Environment Variables

Getting Started

Installation

Project Structure

Features

1. Session Creation

2. Webhook Handling

API Reference

Authentication

Base URLs

Partner API Endpoints

Session Management

Order Management

Webhook Events

Rate Limits

Session Lifecycle

API Scope

Postman Collection

Getting Started with Postman

Deployment

Deploy to Vercel

Other Platforms

Documentation

Support

License

Tech Stack

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages