{"info":{"_postman_id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","name":"Printora Partner API","description":"

Printora Partner Integration API

The Printora Partner API allows partners to create custom print sessions where end-users can design and order personalized products using their own images.

🚀 Quick Start

Integration Flow

Create Session - Partner creates a session with an image URL via API
\n
User Redirect - User visits the redirect URL and is automatically logged in
\n
User Customizes - User selects products and customizes their design (via Printora frontend)
\n
Checkout - User completes checkout, order is created
\n
Webhook Notification - Partner receives webhook notification about the order
\n
Retrieve Orders - Partner can retrieve order details and tracking via API
\n

🔐 Authentication

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

Authorization: Bearer sk_test_printora_partner_demo_12345678\n\n

API Key Format:

Test mode: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxx
\n
Live mode: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx
\n

🌍 Base URLs

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

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

📚 Available Endpoints

Session Management

POST /api/v1/partner-session - Create a new partner session

Order Management

GET /api/v1/partners/:partnerId/orders - List all orders for the partner

Webhook Management

GET /api/v1/webhooks/logs - View webhook delivery logs
\n
POST /api/v1/webhooks/resend - Manually resend a webhook
\n
POST /api/v1/webhooks/retry - Retry a failed webhook delivery
\n

⚠️ Important Notes

API Scope

This API is designed exclusively for partner backend integration.

Partners CAN:

✅ Create print sessions for end-users
\n
✅ Retrieve orders created through their sessions
\n
✅ Manage webhook deliveries and view logs
\n

Partners CANNOT:

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

Session Lifecycle

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

🔔 Webhooks

Partners receive webhook notifications for the following events:

order.created - When a user completes checkout
\n
order.paid - When payment is confirmed
\n
order.shipped - When the order is shipped
\n
order.delivered - When the order is delivered
\n
order.cancelled - When an order is cancelled
\n

Webhook Payload Example:

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

📊 Rate Limits

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

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

Rate limit headers are included in every response:

X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 45\nX-RateLimit-Reset: 1738234567\n\n

🛠️ Support

Need help with the integration?

Email: support@printora.ai
\n
Documentation: View complete documentation →
\n

📖 Getting Started

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

Version: 1.0
Last Updated: February 2026
Status: ✅ Production Ready

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Printora Partner Integration API","slug":"printora-partner-integration-api"}],"owner":"31908428","collectionId":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","publishedId":"2sBXcHhJd9","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-02-27T06:02:29.000Z"},"item":[{"name":"Session Management","item":[{"name":"Create Session","id":"a423878f-6c5c-469d-b38b-f600f5ef5236","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"idempotency-key","value":"","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"imageUrl\": \"https://picsum.photos/3000/3000\",\r\n// \"userData\": {\r\n// \"email\": \"a1slcfrfmd@xkxkud.com\",\r\n// \"name\": \"John Simon\",\r\n// \"firstName\": \"John\",\r\n// \"lastName\": \"Simon\"\r\n// },\r\n \"failedUrl\" : \"https://shopee.co.id\",\r\n \"successUrl\" : \"https://favos.app\"\r\n}","options":{"raw":{"language":"json"}}},"url":"/api/v1/partner-session","description":"

Create Partner Session

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

📥 Request

Endpoint: POST /api/v1/partner-session

Description: Create a design session for a customer. Returns a redirect URL to Printora checkout page.

Authentication: Required

Headers:

Authorization: Bearer YOUR_API_KEY\nIdempotency-Key: 550e8400-e29b-41d4-a716-446655440000\nContent-Type: application/json\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Idempotency-Key`	Yes	Unique key to prevent duplicate session creation (UUID recommended)
`Content-Type`	Yes	Must be `application/json`

📥 Request Body

Request Body:

{\n  \"imageUrl\": \"https://partner.com/customer-design.png\",\n  \"userData\": {\n    \"email\": \"customer@example.com\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"name\": \"John Doe\"\n  },\n  \"successUrl\": \"https://partner.com/order-success\",\n  \"failedUrl\": \"https://partner.com/order-failed\"\n}\n\n

📥 Request Body Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`imageUrl`	String	Yes	URL of customer's design image (must be publicly accessible)
`userData`	Object	No	Customer information (optional, improves checkout UX)
`userData.email`	String	No	Customer email - pre-fills checkout form
`userData.firstName`	String	No	Customer first name - pre-fills checkout form
`userData.lastName`	String	No	Customer last name - pre-fills checkout form
`userData.name`	String	No	Customer display name
`successUrl`	String	Yes	Redirect URL after successful payment
`failedUrl`	String	Yes	Redirect URL after failed payment
`idempotencyKey`	String	No	Unique key to prevent duplicate session creation

Why include userData****? (Optional, but recommended)

Providing customer information improves the checkout experience:

✅ Faster checkout - Email and name are pre-filled at checkout
\n
✅ Reduced friction - Customer doesn't re-enter information they already provided on your site
\n
✅ Better UX - Seamless flow from your platform to Printora
\n

Privacy & Security:

Customer data is only used for order processing and fulfillment
\n
Data is not shared with third parties
\n
Customer can update information during checkout if needed
\n
User accounts are created automatically AFTER successful payment (not during session creation)
\n
If userData is not provided, customer will enter information manually at checkout
\n

📤 Response Fields

Success Response (201 Created)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`success`	Boolean	`true` if session created successfully, `false` if error
`data.sessionId`	String (UUID)	Unique identifier for this partner session (use for tracking)
`data.redirectUrl`	String (URL)	Full URL to redirect customer to Printora checkout page. Direct the customer to this URL to complete the order.
`data.imageUrl`	String (URL)	Echo of the customer's design image URL you provided
`data.createdAt`	String (ISO8601)	Timestamp when session was created

Response Example:

{\n  \"success\": true,\n  \"data\": {\n    \"sessionId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"redirectUrl\": \"https://printora.ai/en/print/daeb7111155d08bc92abe7aabf27782e5ceae0626a5ce2cbad9c99d75a1adf37\",\n    \"imageUrl\": \"https://partner.com/customer-design.png\",\n    \"createdAt\": \"2026-01-31T10:00:00.000Z\"\n  }\n}\n\n

Idempotent Response (409 Conflict)

If you send the same idempotencyKey twice, you'll get the existing session:

{\n  \"success\": true,\n  \"data\": {\n    \"sessionId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"redirectUrl\": \"https://printora.ai/en/print/daeb7111155d08bc92abe7aabf27782e5ceae0626a5ce2cbad9c99d75a1adf37\",\n    \"imageUrl\": \"https://partner.com/customer-design.png\",\n    \"createdAt\": \"2026-01-31T10:00:00.000Z\"\n  }\n}\n\n

🚫 Error Responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Description
400	`INVALID_IMAGE_URL`	Image URL is invalid or not accessible
400	`successUrl is required`	successUrl is required and must be a valid URL
400	`failedUrl is required`	failedUrl is required and must be a valid URL
401	`INVALID_API_KEY`	Partner API key is invalid or revoked
409	`DUPLICATE_SESSION`	Session with this idempotency_key already exists (returns existing session)
429	`RATE_LIMIT_EXCEEDED`	Too many requests, rate limit exceeded

Example Error Response:

{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_IMAGE_URL\",\n    \"message\": \"Image URL must be a valid HTTPS URL\"\n  }\n}\n\n

💡 Example Use Case

Scenario: Photo printing service wants to let users print their Instagram photos

Partner fetches image from user's Instagram
\n
Partner calls this endpoint with image URL and user's email
\n
Partner redirects user to redirect_url
\n
User selects product, customizes design, and completes checkout
\n
Partner receives webhook notification when order is placed
\n

⏱️ Session Expiry & Token Validity

Redirect URL validity: 15 minutes from creation
\n
Active session duration: 24 hours after user first accesses the URL
\n
Token validity: Token becomes invalid after order is created
\n

Token Lifecycle States

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

State	`isValid`	`isCompleted`	Description
New Session	`true`	`false`	Token is ready to use
After Order Created	`false`	`true`	Token was used, cannot be reused

Important: Each session token can only be used for ONE order. After order is created, the token becomes invalid.

🔗 How It Works

Flow Overview

┌─────────────┐                    ┌─────────────┐\n│   Partner   │                    │   Printora   │\n│   Server    │                    │   Backend    │\n└──────┬──────┘                    └──────┬──────┘\n       │                                  │\n       │  1. POST /api/v1/partner-session    │\n       │     { imageUrl, userData, ... }    │\n       ├─────────────────────────────────>│\n       │                                  │\n       │  2. Generate session + token       │\n       │                                  │\n       │<─────────────────────────────────┤\n       │  {                               │\n       │    sessionId: \"uuid\",             │\n       │    redirectUrl: \"https://...\",   │\n       │  }                               │\n       │                                  │\n       │  3. Partner redirects user       │\n       ├─────────────────────────────────>│\n       │                                  │\n       │  4. User validates token          │\n       │     GET /api/v1/partner-session/   │\n       │          by-token/:token           │\n       │                                  │\n       │  5. User customizes & checks out  │\n       │                                  │\n       │  6. Token becomes INVALID         │\n       │     (marked as completed)        │\n       │                                  │\n       │  7. Partner receives webhook      │\n       │     order.paid with order details  │\n       │                                  │\n\n

Step-by-Step Process:

Partner creates session
\n
- POST to /api/v1/partner-session with image URL
  \n
- Gets redirectUrl with temporary token
  \n
- Gets sessionId for tracking
  \n
\n
Partner redirects user
\n
- User visits https://printora.ai/en/print/{token}
  \n
- Frontend validates token by calling GET /api/v1/partner-session/by-token/:token
  \n
\n
User customizes product
\n
- Frontend displays partner's image
  \n
- User customizes the product
  \n
\n
User completes checkout
\n
- User fills checkout form (pre-filled if userData was provided)
  \n
- User completes payment
  \n
\n
Token becomes invalid
\n
- After order is created, isValid becomes false
  \n
- Token cannot be reused for another order
  \n
\n
Partner receives notification
\n
- Partner gets order.paid webhook with order details
\n

\n\n

GET /api/v1/partner-session/by-token/:token - Validate session token and check if still usable
\n
GET /api/v1/partner-session/:sessionId - Get session details by session ID
\n
GET /api/v1/partners/orders - Get all orders created from partner sessions
\n
GET /api/v1/partners/webhook-logs - View webhook delivery logs
\n
POST /api/v1/partners/webhook-logs/resend - Manually resend webhook by order
\n
POST /api/v1/partners/webhook-logs/:webhookLogId/retry - Retry failed webhook delivery
\n

📝 Full Example

JavaScript/Node.js Example

// Step 1: Create partner session\nconst response = await fetch('https://printora-be-staging.vercel.app/api/v1/partner-session', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY',\n    'Content-Type': 'application/json',\n    'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000'\n  },\n  body: JSON.stringify({\n    imageUrl: 'https://partner.com/design.png',\n    userData: {\n      email: 'customer@example.com',\n      firstName: 'John',\n      lastName: 'Doe'\n    },\n    successUrl: 'https://partner.com/success',\n    failedUrl: 'https://partner.com/failed'\n  })\n});\nconst result = await response.json();\n// Step 2: Redirect user to Printora\nif (result.success) {\n  // Redirect user to complete their order\n  window.location.href = result.data.redirectUrl;\n  // Or save session ID for tracking\n  localStorage.setItem('partnerSessionId', result.data.sessionId);\n}\n\n

cURL Example

curl -X POST https://printora-be-staging.vercel.app/api/v1/partner-session \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\n    \"imageUrl\": \"https://partner.com/design.png\",\n    \"userData\": {\n      \"email\": \"customer@example.com\",\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\"\n    },\n    \"successUrl\": \"https://partner.com/success\",\n    \"failedUrl\": \"https://partner.com/failed\"\n  }'\n\n

📊 Response Data Usage

For Partner Backend:

sessionId - Use for tracking and analytics
\n
redirectUrl - Direct user to this URL
\n
Extract temporary token: redirectUrl.split('/').pop()
\n

For Frontend (Printora):

Validate token before allowing checkout
\n
Display partner's image
\n
Pre-fill user data if provided
\n
Show error if token is invalid
\n

For Partner Dashboard:

Track session conversions
\n
Monitor which sessions resulted in orders
\n
Calculate conversion rates
\n

\n","urlObject":{"path":["api","v1","partner-session"],"host":[""],"query":[],"variable":[]}},"response":[],"_postman_id":"a423878f-6c5c-469d-b38b-f600f5ef5236"}],"id":"f5b7ef89-3f8a-4c6f-88fc-001cbf2f467f","description":"

Session Management

Partner creates sessions for end-users to customize products with their images.

What is a Partner Session?

A partner session is a temporary workspace where end-users can:

Upload or use a pre-provided image
\n
Select products (t-shirts, mugs, etc.)
\n
Customize their design
\n
Complete checkout
\n

Session Lifecycle

pending → active → completed
↓ ↓
expired cancelled

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description
`pending`	Session created, user hasn't visited redirect URL yet
`active`	User is currently in the editor/customization flow
`completed`	User completed checkout, order created
`expired`	Session expired (24 hours) without completion
`cancelled`	User cancelled the session

Session Expiry

Redirect URL: 15 minutes from creation
\n
Active session: 24 hours after first access
\n

Available Endpoints

POST Create Session - Partner creates new session

\n","_postman_id":"f5b7ef89-3f8a-4c6f-88fc-001cbf2f467f","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","name":"Printora Partner API","type":"collection"}}},{"name":"Order","item":[{"name":"List","id":"43806f30-db94-40ac-9261-99040554bd9a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/api/v1/partners/orders?limit=10","description":"

Get Partner Orders

Retrieves a list of all orders created through partner sessions. Orders are sorted by creation date (newest first).

🔍 Query Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Default	Description
`limit`	integer	❌ Optional	`20`	Number of orders to return (max: 100)
`offset`	integer	❌ Optional	`0`	Number of orders to skip for pagination
`status`	string	❌ Optional	-	Filter by order status (e.g., `pending`, `paid`, `shipped`, `delivered`)

Status Values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description
`pending`	Order created, awaiting payment
`paid`	Payment confirmed
`processing`	Order in production
`shipped`	Order shipped to customer
`delivered`	Order delivered
`cancelled`	Order cancelled

📤 Response Fields

Success Response (200 OK)

{\n  \"success\": true,\n  \"data\": {\n    \"orders\": [...],\n    \"pagination\": {...}\n  }\n}\n\n

Order Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`id`	string (UUID)	Unique order identifier
`orderNumber`	string	Human-readable order number (e.g., `PRT-1738234567890-ABC123`)
`status`	string	Current order status
`totalAmount`	number	Total order amount
`currency`	string	Currency code (e.g., `USD`)
`source`	string	Always `\"partner\"` for partner orders
`partnershipHistoryId`	string (UUID)	Session ID that created this order
`createdAt`	string (ISO 8601)	Order creation timestamp
`updatedAt`	string (ISO 8601)	Last update timestamp

Pagination Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`total`	integer	Total number of orders matching filter
`limit`	integer	Number of orders returned in this response
`offset`	integer	Number of orders skipped
`hasMore`	boolean	Whether more orders are available

💡 Example Use Cases

Pagination Example

Get first page (20 orders):

GET /api/v1/partners/orders?limit=20&offset=0\n\n

Get second page:

GET /api/v1/partners/orders?limit=20&offset=20\n\n

Get third page:

GET /api/v1/partners/orders?limit=20&offset=40\n\n

Filter by Status

Get only paid orders:

GET /api/v1/partners/orders?status=paid\n\n

Get only shipped orders:

GET /api/v1/partners/orders?status=shipped&limit=50\n\n

⚠️ Error Responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Description
401	`INVALID_API_KEY`	Partner API key is invalid or revoked
400	`VALIDATION_ERROR`	Invalid query parameters (e.g., limit > 100)
429	`RATE_LIMIT_EXCEEDED`	Too many requests

\n\n

POST /api/v1/partner-session - Create session that generates orders
\n
GET /api/v1/partners/webhook-logs - View webhook notifications for orders
\n

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","name":"Printora Partner API","type":"collection"}},"urlObject":{"path":["api","v1","partners","orders"],"host":[""],"query":[{"key":"limit","value":"10"}],"variable":[]}},"response":[],"_postman_id":"43806f30-db94-40ac-9261-99040554bd9a"}],"id":"5f63426b-9438-43e3-a627-afff4ea0dd08","_postman_id":"5f63426b-9438-43e3-a627-afff4ea0dd08","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","name":"Printora Partner API","type":"collection"}}},{"name":"Webhook","item":[{"name":"Logs","id":"ab653ddc-cae2-4871-a085-ccfbeb49e2ce","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"/api/v1/partners/webhook-logs?limit=10","description":"

Get Webhook Logs

Retrieves webhook delivery logs for all events sent to your partner webhook endpoint. Useful for debugging webhook deliveries and viewing failed notifications.

🔍 Query Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Default	Description
`limit`	integer	❌ Optional	`20`	Number of logs to return (max: 100)
`offset`	integer	❌ Optional	`0`	Number of logs to skip for pagination
`status`	string	❌ Optional	-	Filter by delivery status
`event_type`	string	❌ Optional	-	Filter by event type (e.g., `order.created`, `order.paid`)

Delivery Status Values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description
`pending`	Webhook queued, not yet sent
`sent`	Webhook successfully delivered
`failed`	Webhook delivery failed
`retrying`	Webhook is being retried

Event Type Values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Event Type	Description
`order.created`	New order created
`order.paid`	Order payment confirmed
`order.shipped`	Order shipped to customer
`order.delivered`	Order delivered to customer
`order.cancelled`	Order cancelled

📤 Response Fields

Success Response (200 OK)

{\n  \"success\": true,\n  \"data\": {\n    \"logs\": [...],\n    \"pagination\": {...}\n  }\n}\n\n

Webhook Log Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`id`	string (UUID)	Unique log identifier
`eventType`	string	Event type (e.g., `order.created`)
`status`	string	Delivery status (`pending`, `sent`, `failed`, `retrying`)
`httpStatusCode`	integer	HTTP status code from webhook endpoint (e.g., `200`, `500`)
`attemptCount`	integer	Number of delivery attempts
`lastAttemptAt`	string (ISO 8601)	Timestamp of last delivery attempt
`nextRetryAt`	string (ISO 8601)	When next retry will occur (if retrying)
`responseData`	object	Response body from webhook endpoint
`errorMessage`	string	Error message if delivery failed
`orderId`	string (UUID)	Associated order ID
`partnershipHistoryId`	string (UUID)	Associated session ID
`createdAt`	string (ISO 8601)	Log creation timestamp

Pagination Object

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`total`	integer	Total number of logs matching filter
`limit`	integer	Number of logs returned in this response
`offset`	integer	Number of logs skipped
`hasMore`	boolean	Whether more logs are available

💡 Example Use Cases

Get Recent Failed Webhooks

GET /api/v1/partners/webhook-logs?status=failed&limit=20\n\n

Get All Webhooks for Specific Order

GET /api/v1/partners/webhook-logs?event_type=order.created\n\n

Get Webhooks Sent in Last Hour

GET /api/v1/partners/webhook-logs?limit=100\n\n

(Then filter by timestamp in your application)

Pagination Example

# First 50 logs\nGET /api/v1/partners/webhook-logs?limit=50&offset=0\n# Next 50 logs\nGET /api/v1/partners/webhook-logs?limit=50&offset=50\n\n

🐛 Debugging Use Case

Scenario: Partner reports they didn't receive webhook for an order.

Steps to debug:

Call GET /api/v1/partners/webhook-logs?event_type=order.created
\n
Look for log with orderId matching the order
\n
Check status:
\n
- sent → Webhook was delivered successfully, check partner endpoint
  \n
- failed → Check errorMessage for failure reason
  \n
- retrying → Webhook will be retried automatically
  \n
\n
Use retry endpoint to manually retry failed webhooks
\n

⚠️ Error Responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Description
401	`INVALID_API_KEY`	Partner API key is invalid or revoked
400	`VALIDATION_ERROR`	Invalid query parameters (e.g., limit > 100)
429	`RATE_LIMIT_EXCEEDED`	Too many requests

\n\n

POST /api/v1/partners/webhook-logs/resend - Manually resend a webhook
\n
POST /api/v1/partners/webhook-logs/:webhookLogId/retry - Retry a failed webhook
\n
GET /api/v1/partners/orders - Get orders that generated these webhooks
\n

\n","urlObject":{"path":["api","v1","partners","webhook-logs"],"host":[""],"query":[{"key":"limit","value":"10"}],"variable":[]}},"response":[],"_postman_id":"ab653ddc-cae2-4871-a085-ccfbeb49e2ce"},{"name":"Resend","id":"f483f6a9-ac90-4058-9984-ba66c3080811","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"orderId\": \"84a3e710-c532-4d09-9b89-e41e80337eab\",\r\n \"eventType\": \"order.paid\"\r\n}","options":{"raw":{"language":"json"}}},"url":"/api/v1/partners/webhook-logs/resend","description":"

Resend Webhook

Manually resend a webhook notification for a specific order or session. Useful for retrying failed webhooks or resending notifications for testing.

📥 Request Body Parameters

sessionId (string, UUID, optional)

Session ID that created the order
\n
Use this if you don't know the order ID
\n

orderId (string, UUID, optional)

Order ID to resend webhook for
\n
Use this if you know the order ID
\n

eventType (string, required)

Type of event to resend
\n
Must be one of: order.created, order.paid, order.shipped, order.delivered
\n

⚠️ Validation Rules

Exactly ONE of sessionId OR orderId must be provided
\n
Both cannot be provided together
\n
eventType is always required
\n

📤 Response Fields

Success Response (200 OK)

{\n  \"success\": true,\n  \"data\": {\n    \"webhookLogId\": \"uuid\",\n    \"eventType\": \"order.created\",\n    \"status\": \"pending\",\n    \"message\": \"Webhook queued for delivery\"\n  }\n}\n\n

💡 Example Use Cases

Resend Order Created Webhook by Session ID

{\n  \"sessionId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"eventType\": \"order.created\"\n}\n\n

Resend Order Paid Webhook by Order ID

{\n  \"orderId\": \"ord_abc123\",\n  \"eventType\": \"order.paid\"\n}\n\n

Resend Order Shipped Webhook

{\n  \"orderId\": \"ord_abc123\",\n  \"eventType\": \"order.shipped\"\n}\n\n

🐛 Use Case: Debugging Failed Webhook

Scenario: Partner reports they didn't receive order.created webhook for a session.

Steps:

Check logs: GET /api/v1/partners/webhook-logs?event_type=order.created
\n
Find the log with matching partnershipHistoryId
\n
{ \"sessionId\": \"session-uuid-from-logs\", \"eventType\": \"order.created\"}
\n
Check logs again to confirm webhook was sent
\n

⚠️ Error Responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Description
400	`VALIDATION_ERROR`	Neither sessionId nor orderId provided, or both provided
400	`VALIDATION_ERROR`	Invalid eventType value
404	`ORDER_NOT_FOUND`	Order not found or does not belong to this partner
401	`INVALID_API_KEY`	Partner API key is invalid or revoked
429	`RATE_LIMIT_EXCEEDED`	Too many requests

\n\n

GET /api/v1/partners/webhook-logs - View webhook delivery logs
\n
POST /api/v1/partners/webhook-logs/:webhookLogId/retry - Retry specific failed webhook
\n
GET /api/v1/partners/orders - Get orders to find order IDs
\n

\n","urlObject":{"path":["api","v1","partners","webhook-logs","resend"],"host":[""],"query":[],"variable":[]}},"response":[],"_postman_id":"f483f6a9-ac90-4058-9984-ba66c3080811"},{"name":"Retry","id":"7da79e49-731e-4127-823f-7649a1660a0c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"/api/v1/partners/webhook-logs/:webhookLogId/retry","description":"

Retry Failed Webhook

Retry a specific failed webhook delivery using the webhook log ID. This endpoint will attempt to redeliver the webhook to your endpoint.

🎯 When to Use This Endpoint

Use this endpoint when:

Webhook delivery failed (status: failed)
\n
Webhook is in retry loop (status: retrying)
\n
You want to immediately retry instead of waiting for automatic retry
\n

Note: Do not use this endpoint for webhooks with status sent (already successful).

📥 URL Parameters

webhookLogId (string, UUID, required)

The unique identifier of the webhook log entry
\n
Obtain this from GET /api/v1/partners/webhook-logs response
\n

📤 Response Fields

Success Response (200 OK) - Retry Queued

{\n  \"success\": true,\n  \"data\": {\n    \"webhookLogId\": \"uuid\",\n    \"eventType\": \"order.created\",\n    \"status\": \"pending\",\n    \"message\": \"Webhook queued for retry\"\n  }\n}\n\n

Success Response (200 OK) - Already Sent

{\n  \"success\": true,\n  \"data\": {\n    \"webhookLogId\": \"uuid\",\n    \"eventType\": \"order.created\",\n    \"status\": \"sent\",\n    \"message\": \"Webhook already successfully delivered\"\n  }\n}\n\n

Error Response (404 - Not Found)

{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"WEBHOOK_NOT_FOUND\",\n    \"message\": \"Webhook log not found\"\n  }\n}\n\n

💡 Example Use Cases

Retry a Failed Webhook

Step 1: Get webhook logs

GET /api/v1/partners/webhook-logs?status=failed\n\n

Step 2: Find the log ID from response

{\n  \"logs\": [\n    {\n      \"id\": \"log-abc123\",\n      \"eventType\": \"order.created\",\n      \"status\": \"failed\",\n      \"errorMessage\": \"Connection timeout\"\n    }\n  ]\n}\n\n

Step 3: Retry using the log ID

POST /api/v1/partners/webhook-logs/log-abc123/retry\n\n

Step 4: Check logs again to confirm success

GET /api/v1/partners/webhook-logs?event_type=order.created\n\n

🔄 Difference from Resend Endpoint

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Feature	Resend Endpoint	Retry Endpoint
URL	`/webhook-logs/resend`	`/webhook-logs/:id/retry`
Input	`sessionId` or `orderId` + `eventType`	`webhookLogId`
Use Case	Resend any event for an order/session	Retry specific failed delivery
When to Use	Testing, missed notifications	Debugging failed deliveries
Creates New Log	Yes (new webhook log entry)	No (updates existing log)

🐛 Debugging Workflow

Scenario: Webhook failed to deliver, you want to retry it.

Complete workflow:

Get failed webhooks: GET /api/v1/partners/webhook-logs?status=failed
\n
Copy id from the failed log
\n
Call retry: POST /api/v1/partners/webhook-logs/{id}/retry
\n
Wait a few seconds for retry attempt
\n
Check logs: GET /api/v1/partners/webhook-logs
\n
Verify status changed from failed to sent or still failed
\n
If still failed, check errorMessage for details
\n

⚠️ Error Responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Description
404	`WEBHOOK_NOT_FOUND`	Webhook log not found or doesn't belong to this partner
400	`VALIDATION_ERROR`	Invalid webhook log ID format
401	`INVALID_API_KEY`	Partner API key is invalid or revoked
429	`RATE_LIMIT_EXCEEDED`	Too many requests

📊 Automatic Retry Behavior

Note: The system automatically retries failed webhooks up to 5 times with exponential backoff:

Retry 1: 1 minute after failure
\n
Retry 2: 5 minutes
\n
Retry 3: 15 minutes
\n
Retry 4: 1 hour
\n
Retry 5: 3 hours
\n

Use this endpoint to manually trigger a retry instead of waiting for automatic retry schedule.

\n\n

GET /api/v1/partners/webhook-logs - View all webhook logs
\n
POST /api/v1/partners/webhook-logs/resend - Resend webhook (create new log)
\n
GET /api/v1/partners/orders - Get order information
\n

\n","urlObject":{"path":["api","v1","partners","webhook-logs",":webhookLogId","retry"],"host":[""],"query":[],"variable":[{"id":"764aeac3-b45f-455c-9db4-48d516725ce2","type":"any","value":"b5334e65-2cd4-4d47-8135-e7b602f98c5d","key":"webhookLogId"}]}},"response":[],"_postman_id":"7da79e49-731e-4127-823f-7649a1660a0c"}],"id":"d6622a58-c667-4108-b234-24d0f7087299","_postman_id":"d6622a58-c667-4108-b234-24d0f7087299","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","id":"a23c6a65-a099-40ab-9208-4f8cc8f6877f","name":"Printora Partner API","type":"collection"}}}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]}},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"d4a3b827-da8b-4196-b902-c000e9c34439"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"b65561b7-6164-49ff-89eb-8432f98dc794"}}],"variable":[{"id":"d221bf9a-b283-45f0-b75d-689454ea2a16","key":"url_staging","value":""},{"id":"7073fa74-256b-45fc-8064-084a929f1635","key":"url_prod","value":""},{"id":"c0571795-49ea-47b1-8cca-badfd5a1aa8f","key":"PARTNER_API_KEY","value":""},{"id":"7bab1843-1b44-469e-be02-b47a77d523d3","key":"PARTNER_ID","value":""},{"id":"27336c12-1e11-4c99-bafb-59e7a22adf3c","key":"SESSION_ID","value":""},{"id":"27eaa5d5-6dc1-4a36-9773-0c50f7be7f33","key":"SESSION_TOKEN","value":""}]}

Printora Partner Integration API

🚀 Quick Start

Integration Flow

🔐 Authentication

🌍 Base URLs

📚 Available Endpoints

Session Management

Order Management

Webhook Management

⚠️ Important Notes

API Scope

Session Lifecycle

🔔 Webhooks

📊 Rate Limits

🛠️ Support

📖 Getting Started

Create Partner Session

📥 Request

📥 Request Body

📥 Request Body Parameters

📤 Response Fields

Success Response (201 Created)

Idempotent Response (409 Conflict)

🚫 Error Responses

💡 Example Use Case

⏱️ Session Expiry & Token Validity

Token Lifecycle States

🔗 How It Works

Flow Overview

Step-by-Step Process:

🔗 Related Endpoints

📝 Full Example

JavaScript/Node.js Example

cURL Example

📊 Response Data Usage

For Partner Backend:

For Frontend (Printora):

For Partner Dashboard:

Session Management

What is a Partner Session?

Session Lifecycle

Session Expiry

Available Endpoints

Get Partner Orders

🔍 Query Parameters

Status Values

📤 Response Fields

Success Response (200 OK)

Order Object

Pagination Object

💡 Example Use Cases

Pagination Example

Filter by Status

⚠️ Error Responses

🔗 Related Endpoints

Get Webhook Logs

🔍 Query Parameters

Delivery Status Values

Event Type Values

📤 Response Fields

Success Response (200 OK)

Webhook Log Object

Pagination Object

💡 Example Use Cases

Get Recent Failed Webhooks

Get All Webhooks for Specific Order

Get Webhooks Sent in Last Hour

Pagination Example

🐛 Debugging Use Case

⚠️ Error Responses

🔗 Related Endpoints

Resend Webhook

📥 Request Body Parameters

⚠️ Validation Rules

📤 Response Fields

Success Response (200 OK)

💡 Example Use Cases

Resend Order Created Webhook by Session ID

Resend Order Paid Webhook by Order ID

Resend Order Shipped Webhook