Papello API Documentation

Welcome to the Papello Print on Demand API documentation. Our API provides comprehensive print-on-demand services for businesses and developers, allowing you to create quotes, manage orders, handle shipping, and integrate with various e-commerce platforms.

Getting Started

Register Dashboard Account

Create your free account at dash.papello.com to access your API keys and manage your orders.

Generate API Keys

Generate both test and live API keys from your dashboard to start making authenticated requests.

Make Your First Request

Start with a simple quote request to understand the API structure and response format.

Base URL

API Base URL

https://api.papello.com

Environments (Test/Live)

Papello provides separate test and live environments to ensure safe development and testing before going into production.

Test Environment

API Key Prefix: test_

Use for development and testing. Orders placed with test keys are not fulfilled and no charges are made.

•No actual printing or shipping
•All API endpoints available
•Perfect for integration testing

Live Environment

API Key Prefix: live_

Use for production orders. Orders placed with live keys are processed and fulfilled.

•Real printing and shipping
•Actual charges apply
•Production-ready

Authentication

All API requests require authentication using Bearer tokens. You'll receive both test and live API keys upon registration in your Papello Dashboard.

Authentication Header

Authorization: Bearer YOUR_API_KEY

Example Request

Authenticated Request Example

curl -X GET "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Orders

The Orders API allows you to create, retrieve, and manage print orders with comprehensive product and shipping details.

Create Order

Endpoint: POST /v1/orders

Create Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORDER-123",
    "amountPaid": 59.89,
    "packingSlip": "https://example.com/packingslip.pdf",
    "shipping": {
      "firstName": "John",
      "lastName": "Doe", 
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "London",
      "state": "Greater London",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "shippingMethod": "Standard"
    },
    "items": [{
      "sku": "PP-ENAMUG-12OZ-W",
      "printReadyFile": "https://example.com/artwork.png",
      "quantity": 1
    }]
  }'

Response Example

Note: The response includes a holdUntil field showing when the order will automatically be released to production if no manual release occurs. Release times can be set in the order settings in the dashboard.

Create Order Response

{
    "orderId": "PPA-01070420",
    "orderReference": "order-1756415824773-4cppfw",
    "status": "processing",
    "createdAt": "2025-08-28T21:17:04.773Z",
    "mode": "test",
    "userId": "userId",
    "userEmail": "example@example.com",
    "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "GB",
        "city": "122 Main Street",
        "address1": "Apt 4b",
        "postcode": "SW1A 1AA",
        "currency": "GBP",
        "state": "London"
    },
    "currency": "GBP",
    "shipping": {
        "firstName": "John",
        "lastName": "Doe",
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "London",
        "postcode": "SW1A 1AA",
        "country": "GB",
        "requestedShippingMethod": "Standard",
        "shippingMethod": "RM Tracked 48"
    },
    "items": [
        {
            "sku": "PP-ENAMUG-12OZ-W",
            "quantity": 1,
            "price": 5.4,
            "description": "12oz Enamel Mug White with stainless steel rim\t",
            "originalPrice": 6,
            "subscriptionDiscount": {
                "percentage": 10,
                "amount": 0.6
            },
            "printReadyFile": "https://example.com/image.png"
        }
    ],
    "subtotal": 5.4,
    "shippingBasePrice": 4.4,
    "shippingAdditionalFee": 0,
    "totalShippingCost": 4.4,
    "insert": {
        "type": "packing_slip_colour",
        "description": "Colour Packing Slip Insert",
        "cost": 0.25,
        "imageUrl": "https://example.com/insert-image.jpg",
        "originalCost": 0.5,
        "subscriptionDiscount": {
            "percentage": 50,
            "amount": 0.25
        }
    },
    "duties": 0,
    "tax": {
        "amount": 2.01,
        "rate": 20,
        "jurisdiction": "GB",
        "breakdown": [
            {
                "amount": 2.01,
                "rate": 20,
                "jurisdiction": "GB",
                "type": "vat",
                "reason": "standard_rated",
                "taxable_amount": 10.05
            }
        ]
    },
    "total": {
        "amount": 12.06
    },
    "holdUntil": "2025-08-28T21:17:04.773Z",
    "orderDelay": "immediate",
    "merchantReference": "REF1234",
    "amountPaid": 12,
    "packingSlip": "https://example.com/packaging-slip.pdf"
}

Create Order with Multiple Items

Endpoint: POST /v1/orders

Create an order containing multiple different products in a single order.

Multiple Items Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORD-123456789",
    "amountPaid": 59.89,
    "packingSlip": "https://example.com/packingslip.pdf",
    "shipping": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "London",
      "postcode": "11111",
      "country": "US",
      "phone": "+44123456789",
      "shippingMethod": "Standard"
    },
    "items": [
      {
        "sku": "PP-EAM-A5",
        "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg",
        "quantity": 1
      }, 
      {
        "sku": "PP-EAM-A4",
        "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg",
        "quantity": 1
      }
    ]
  }'

Create Order with Multiple Print Areas

Endpoint: POST /v1/orders

Create an order for products that have more than one print area (e.g. front + back, inside card).

Multiple Print Areas Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORD-123456789",
    "amountPaid": 4.00,
    "packingSlip": "https://example.com/packingslip.pdf",
    "shipping": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "shippingMethod": "Standard"
    },
    "items": [{
      "sku": "PP-GRE-A5-V-ENVELOPE",
      "quantity": 1,
      "price": 1.45,
      "printReadyFiles": [
        {
          "name": "Front & Back",
          "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg"
        },
        {
          "name": "Inside Card",
          "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg"
        }
      ]
    }]
  }'

Get Orders

Endpoint: GET /v1/orders

Get Orders Request

curl -X GET "https://api.papello.com/v1/orders?page=1&limit=10&status=processing" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Get Orders Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "orderId": "PPA-01069647",
        "orderReference": "order-1747328967347-wgw3qr",
        "createdAt": "2025-05-15T14:22:47.347Z",
        "status": "processing",
        "mode": "test",
        "userEmail": "customer@example.com",
        "subtotal": 35,
        "totalShippingCost": 4.4,
        "total": {
          "amount": 46.4
        },
        "items": [{
          "sku": "PP-CF-MOUNT-PSM-A4-BF",
          "printReadyFile": "https://example.com/artwork.jpg",
          "quantity": 1,
          "price": 35
        }],
        "shipping": {
          "firstName": "John",
          "lastName": "Doe",
          "address1": "123 Main St",
          "city": "London",
          "postcode": "SW1A 1AA",
          "country": "GB",
          "shippingMethod": "RM Tracked 48"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 42,
      "items_per_page": 10,
      "has_more": true
    }
  }
}

Order Actions

Manage your orders with various actions including updates, releases, and cancellations.

Update Recipient on Order

Endpoint: PUT /v1/orders/{orderId}

Update recipient shipping details on a pending order.

Update Recipient Request

curl -X PUT "https://api.papello.com/v1/orders/PPA-01069647" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "firstName": "Johnny",
      "lastName": "Doe",
      "address1": "132 Main St",
      "address2": "Apt 4444B",
      "state": "Greater London",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "phone": "+44123456789"
    }
  }'

Update Shipping Method

Endpoint: PUT /v1/orders/{orderId}

Update the shipping method on a pending order.

Update Shipping Method Request

curl -X PUT "https://api.papello.com/v1/orders/PPA-01069647" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "shippingMethod": "Express"
    }
  }'

Update Response Example

Update Order Response

{
  "orderId": "{orderId}",
  "orderReference": "{orderReference}",
  "status": "pending",
  "createdAt": "2025-08-29T12:07:45.159Z",
  "mode": "live",
  "userId": "{userId}",
  "userEmail": "test@example.com",
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "country": "GB",
    "city": "122 Main Street",
    "address1": "Apt 4b",
    "postcode": "SW1A 1AA",
    "currency": "GBP",
    "state": "London"
  },
  "currency": "GBP",
  "shipping": {
    "firstName": "Johnny",
    "lastName": "Doe",
    "country": "GB",
    "requestedShippingMethod": "Express",
    "city": "London",
    "phone": "+44123456789",
    "address2": "Apt 4444B",
    "address1": "132 Main St",
    "shippingMethod": "UPS Domestic Express",
    "postcode": "SW1A 1AA",
    "state": "Greater London",
    "estimatedDelivery": "3-5 working days"
  },
  "items": [...],
  "subtotal": 5.4,
  "totalShippingCost": 4.4,
  "tax": {...},
  "total": {
    "amount": 12.06
  },
  "holdUntil": "2025-08-28T21:17:04.773Z",
  "orderDelay": "immediate",
  "merchantReference": "REF1234",
  "duties": 0,
  "amountPaid": 12,
  "updatedAt": "2025-08-31T18:39:48.080Z"
}

Important Notes

•Orders can only be updated while they are in "pending" status
•Once an order moves to processing, updates are no longer possible
•Price recalculations happen automatically based on updated shipping options

Release Order

Endpoint: POST /v1/orders/{orderId}/release

Release a pending order to production. Orders can be set to hold for a specified time to allow for changes before automatic release. Release times can be set in the order settings in the dashboard.

Release Order Request

curl -X POST "https://api.papello.com/v1/orders/PPA-01069647/release" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Release Order Response

{
  "success": true,
  "data": {
    "orderId": "{orderId}",
    "orderReference": "{orderReference}",
    "status": "processing",
    "message": "Order successfully released for processing",
    "releasedAt": "2025-08-31T18:48:38.866Z",
    "paymentStatus": "success"
  }
}

Cancel Order

Endpoint: POST /v1/orders/{orderId}/cancel

Cancel a pending order. Only orders in "pending" status can be cancelled.

Cancel Order Request

curl -X POST "https://api.papello.com/v1/orders/PPA-01069647/cancel" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Cancel Order Response

{
  "success": true,
  "data": {
    "orderId": "{orderId}",
    "orderReference": "{orderReference}",
    "status": "cancelled",
    "message": "Order successfully cancelled",
    "cancelledAt": "2025-08-31T18:45:59.690Z"
  }
}

Quotes

Generate accurate pricing quotes for potential orders without payment processing. Includes pricing breakdown, shipping costs, taxes, and duties.

Generate Quote

Endpoint: POST /v1/quote

Generate Quote Request

curl -X POST "https://api.papello.com/v1/quote" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "country": "US",
      "shippingMethod": "Standard"
    },
    "items": [{
      "sku": "PP-EAM-5x7",
      "quantity": 1
    }]
  }'

Generate Quote with Multiple Items

Endpoint: POST /v1/quote

Get pricing for multiple different products in a single quote request.

Multiple Items Quote Request

curl -X POST "https://api.papello.com/v1/quote" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "country": "US",
      "shippingMethod": "Standard"
    },
    "items": [
      {
        "sku": "PP-EAM-A5",
        "quantity": 1
      },
      {
        "sku": "PP-EAM-A4",
        "quantity": 2
      },
      {
        "sku": "PP-ENAMUG-12OZ-W",
        "quantity": 1
      }
    ]
  }'

Response Example

Generate Quote Response

{
  "success": true,
  "data": {
    "currency": "GBP",
    "conversionRate": 1.0,
    "pricing": {
      "subtotal": 3.00,
      "shipping": 6.27,
      "insertCharge": 0.50,
      "duties": 0.78,
      "tax": 0.00,
      "total": 10.55
    },
    "pricingBreakdown": {
      "items": [{
        "sku": "PP-EAM-5x7",
        "quantity": 1,
        "basePrice": 3.00,
        "additionalPrintFees": 0.00,
        "totalPerItem": 3.00,
        "totalForQuantity": 3.00
      }],
      "shipping": {
        "methodName": "RM Tracked International US",
        "methodId": 114,
        "cost": 6.27,
        "estimatedDelivery": "3-5 working days*"
      },
      "tax": {
        "amount": 0.00,
        "rate": 0,
        "jurisdiction": "GB"
      }
    },
    "metadata": {
      "mode": "live",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  }
}

Catalogue

Browse the Papello product catalogue programmatically. These read-only endpoints let you discover collections, list products within a collection, and retrieve enabled variation SKUs for a product.

Use this three-step flow before placing orders or generating quotes:

List collections — pick a collection slug
List products in that collection — pick a product slug
List variations for that product — pick a SKU for POST /v1/quote or POST /v1/orders

All catalogue endpoints require the same Bearer token authentication as the rest of the public API. Both test_ and live_ API keys work identically for catalogue reads.

Base URL

API Base URL

https://api.papello.com

Authentication

Authentication Header

Authorization: Bearer YOUR_API_KEY

Rate Limits

Rate limits apply per API key owner (not per IP):

Endpoint	Limit
`GET /v1/catalogue/collections`	60 requests / minute
`GET /v1/catalogue/collections/:slug/products`	30 requests / minute
`GET /v1/catalogue/products/:slug/variations`	30 requests / minute

If you exceed the limit, the API returns HTTP 429 with:

Rate Limit Error Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down and try again shortly."
  }
}

Caching

Responses include a Cache-Control header allowing clients to cache for up to 5 minutes:

Cache-Control Header

Cache-Control: max-age=300, stale-while-revalidate=60

Catalogue data is also cached server-side for 5 minutes, so repeated requests for the same resource are fast and stable.

Slugs

Collection and product :slug path parameters are the SEO canonical URL slugs from the Papello CMS (for example mugs, greeting-cards, 12oz-enamel-mug). They are not numeric IDs.

There is no global "list all products" or "list all variations" endpoint by design — products are always scoped to a collection, and variations are always scoped to a single product.

List Collections

Endpoint: GET /v1/catalogue/collections

Returns all product collections in the Papello catalogue.

List Collections Request

curl -X GET "https://api.papello.com/v1/catalogue/collections" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

List Collections Response

{
  "data": [
    {
      "slug": "mugs",
      "title": "Mugs",
      "image": {
        "url": "https://cms.papello.com/uploads/mugs_collection_abc123.jpg",
        "thumbnail": "https://cms.papello.com/uploads/thumbnail_mugs_collection_abc123.jpg"
      }
    },
    {
      "slug": "greeting-cards",
      "title": "Greeting Cards",
      "image": {
        "url": "https://cms.papello.com/uploads/greeting_cards_def456.jpg",
        "thumbnail": "https://cms.papello.com/uploads/thumbnail_greeting_cards_def456.jpg"
      }
    },
    {
      "slug": "wall-art",
      "title": "Wall Art",
      "image": null
    }
  ]
}

Response Fields

Field	Type	Description
`data`	array	List of collections
`data[].slug`	string	Collection slug — use in `GET /v1/catalogue/collections/:slug/products`
`data[].title`	string	Display name
`data[].image`	object \| null	Collection image URLs
`data[].image.url`	string	Full-size image URL
`data[].image.thumbnail`	string	Thumbnail image URL

List Products by Collection

Endpoint: GET /v1/catalogue/collections/:slug/products

Returns products belonging to a single collection. Variations/SKUs are not included — use the variations endpoint for those.

Path Parameters

Parameter	Description
`slug`	Collection slug from `GET /v1/catalogue/collections` (e.g. `mugs`)

List Products by Collection Request

curl -X GET "https://api.papello.com/v1/catalogue/collections/mugs/products" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

List Products by Collection Response

{
  "data": [
    {
      "slug": "12oz-enamel-mug",
      "title": "12oz Enamel Mug",
      "subtitle": "White with stainless steel rim",
      "thumbnail": "https://cms.papello.com/uploads/enamel_mug_thumb.jpg"
    },
    {
      "slug": "11oz-ceramic-mug",
      "title": "11oz Ceramic Mug",
      "subtitle": "Gloss white finish",
      "thumbnail": "https://cms.papello.com/uploads/ceramic_mug_thumb.jpg"
    }
  ],
  "collection": {
    "title": "Mugs",
    "slug": "mugs"
  }
}

Response Fields

Field	Type	Description
`data`	array	Products in the collection
`data[].slug`	string	Product slug — use in `GET /v1/catalogue/products/:slug/variations`
`data[].title`	string	Product name
`data[].subtitle`	string \| null	Short product description
`data[].thumbnail`	string \| null	Product thumbnail image URL
`collection.title`	string	Parent collection name
`collection.slug`	string	Parent collection slug

Error: Collection Not Found

HTTP 404 if the collection slug does not exist:

Collection Not Found Error

{
  "statusCode": 404,
  "message": "Collection not found: invalid-slug",
  "error": "Not Found"
}

List Variations by Product

Endpoint: GET /v1/catalogue/products/:slug/variations

Returns enabled variations (SKUs) for a single product. Use the returned sku values with POST /v1/quote, POST /v1/orders, or GET /validate-sku.

Path Parameters

Parameter	Description
`slug`	Product slug from `GET /v1/catalogue/collections/:slug/products` (e.g. `12oz-enamel-mug`)

List Variations by Product Request

curl -X GET "https://api.papello.com/v1/catalogue/products/12oz-enamel-mug/variations" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example — Single Print Area

List Variations Response (Single Print Area)

{
  "data": [
    {
      "sku": "PP-ENAMUG-12OZ-W",
      "description": "12oz Enamel Mug White with stainless steel rim",
      "printArea": {
        "artworkWidth": 2400,
        "artworkHeight": 960
      }
    },
    {
      "sku": "PP-ENAMUG-12OZ-B",
      "description": "12oz Enamel Mug Black with stainless steel rim",
      "printArea": {
        "artworkWidth": 2400,
        "artworkHeight": 960
      }
    }
  ],
  "product": {
    "title": "12oz Enamel Mug",
    "slug": "12oz-enamel-mug"
  }
}

Response Example — Multiple Print Areas

Products with more than one print area (e.g. greeting cards with front/back and inside) include a multiPrintArea array. When placing orders for these products, use printReadyFiles instead of a single printReadyFile — see Create Order with Multiple Print Areas in the Orders section.

List Variations Response (Multiple Print Areas)

{
  "data": [
    {
      "sku": "PP-GRE-A5-V-ENVELOPE",
      "description": "A5 Greetings Card (Include Envelope)",
      "printArea": {
        "artworkWidth": 3508,
        "artworkHeight": 2480
      },
      "multiPrintArea": [
        {
          "name": "Front/Back",
          "additionalPrintFee": null,
          "requiredView": true,
          "artworkWidth": 3508,
          "artworkHeight": 2480
        },
        {
          "name": "Inside",
          "additionalPrintFee": 0.25,
          "requiredView": false,
          "artworkWidth": 3508,
          "artworkHeight": 2480
        }
      ]
    }
  ],
  "product": {
    "title": "A5 Greeting Card",
    "slug": "a5-greeting-card"
  }
}

Response Fields

Field	Type	Description
`data`	array	Enabled variations for the product
`data[].sku`	string	Papello SKU — use in quotes and orders
`data[].description`	string	Variation description
`data[].printArea`	object \| null	Primary artwork dimensions in pixels
`data[].printArea.artworkWidth`	number	Artwork width (px)
`data[].printArea.artworkHeight`	number	Artwork height (px)
`data[].multiPrintArea`	array	Present when the product has multiple print views
`data[].multiPrintArea[].name`	string	Print area name (matches order `printReadyFiles[].name`)
`data[].multiPrintArea[].additionalPrintFee`	number \| null	Extra charge for this print area, if any
`data[].multiPrintArea[].requiredView`	boolean	Whether this view is required
`data[].multiPrintArea[].artworkWidth`	number \| null	View-specific width (px)
`data[].multiPrintArea[].artworkHeight`	number \| null	View-specific height (px)
`product.title`	string	Parent product name
`product.slug`	string	Parent product slug

Error: Product Not Found

HTTP 404 if the product slug does not exist:

Product Not Found Error

{
  "statusCode": 404,
  "message": "Product not found: invalid-slug",
  "error": "Not Found"
}

Catalogue vs SKU Validation

These endpoints complement Product Details (SKU Validation) (GET /validate-sku?sku={sku}):

	Catalogue API	SKU Validation
Purpose	Browse and discover products	Validate a specific SKU before ordering
Scope	Collections → products → variations	Single SKU lookup
Returns pricing	No	Yes (`Price`, subscription discount)
Returns print areas	Yes (dimensions + multi-area names)	Yes (detailed `printAreas` array)
Best for	Building product pickers, integrations, storefronts	Pre-flight checks before order creation

Recommended flow:

GET /v1/catalogue/collections
GET /v1/catalogue/collections/:slug/products
GET /v1/catalogue/products/:slug/variations
GET /validate-sku?sku={sku} — optional, for pricing and detailed print-area metadata
POST /v1/quote or POST /v1/orders

Important Notes

•Catalogue endpoints return JSON directly (no { "success": true, "data": ... } wrapper).
•Only enabled variations are returned from the variations endpoint.
•Disabled or draft CMS entries are excluded automatically.
•For order placement, artwork files must still meet the file requirements in Product Details (SKU Validation) (JPG/JPEG/PNG, 300 DPI minimum).
•There is no endpoint to fetch all products across every collection, or all variations globally.

Product Details (SKU Validation)

Validate product SKUs and retrieve detailed product information before placing orders.

Validate SKU

Endpoint: GET /validate-sku?sku={variationSku}

Validate a product SKU and get detailed information including print areas and pricing.

SKU Validation Request

curl -X GET "https://api.papello.com/validate-sku?sku=PP-GRE-A5-V-ENVELOPE" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

SKU Validation Response

{
  "Description": "A5 Greetings Card (Include Envelope)",
  "SKU": "PP-GRE-A5-V-ENVELOPE",
  "Price": 1.45,
  "plusSubDiscount": 20,
  "product_size": {
    "Name": "29.7x21cm / 11.7x8.3\" (A5 Folded)",
    "ArtworkWidth": 3508,
    "ArtworkHeight": 2480
  },
  "printAreas": [
    {
      "name": "Front/Back"
    },
    {
      "name": "Inside",
      "additionalPrintFee": 0.25
    }
  ]
}

SKU Validation

All product SKUs should be validated before creating orders. Invalid SKUs will result in order creation failures.

Common SKU Examples

PP-EAM-5x7- 5x7 Enhanced Archival Matte
PP-CF-MOUNT-PSM-A4-BF- A4 Black Frame Mount
PP-ENAMUG-12OZ-W- 12oz White Enamel Mug

File Requirements

Print-Ready Files

•Supported formats: JPG, JPEG, PNG
•Minimum resolution: 300 DPI
•Color mode: RGB or CMYK (sRGB is recommended)

Packing Slips

•Supported formats: PDF
•File size limit: 10MB

Webhooks

Receive real-time notifications about order status changes and important events in your order lifecycle.

Webhook Configuration

Configure webhook endpoints in your Papello Dashboard to receive event notifications.

Available Events

order.shipped- When order is shipped with full tracking information

Webhook Event Example

Order Shipped Webhook

{
  "event": "order.shipped",
  "timestamp": "2025-09-25T11:50:35.787Z",
  "data": {
    "orderId": "PPA-01069729",
    "orderReference": "order-1748092696225-4hmp76",
    "status": "shipped",
    "shippingInfo": {
      "trackingNumber": "1234567890GB",
      "carrier": "Royal Mail",
      "service": "Tracked 48",
      "shipDate": "2025-09-25T10:20:35.787Z",
      "updatedAt": "2025-09-25T11:50:35.787Z"
    }
  }
}

Order Status

Track and monitor order progress through various status stages from creation to delivery.

Get Order Status

Endpoint: GET /v1/orders/{orderId}

Get Order Status Request

curl -X GET "https://api.papello.com/v1/orders/PPA-01069647" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Get Order Status Response

{
    "orderId": "{orderId}",
    "orderReference": "{orderReference}",
    "status": "in-production",
    "createdAt": "2025-08-28T21:17:04.773Z",
    "mode": "test",
    "userId": "userId",
    "userEmail": "example@example.com",
    "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "GB",
        "city": "122 Main Street",
        "address1": "Apt 4b",
        "postcode": "SW1A 1AA",
        "currency": "GBP",
        "state": "London"
    },
    "currency": "GBP",
    "shipping": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "GB",
        "requestedShippingMethod": "Standard",
        "address2": "Apt 4B",
        "city": "London",
        "address1": "123 Main St",
        "shippingMethod": "RM Tracked 48",
        "postcode": "SW1A 1AA"
    },
    "items": [
        {
            "quantity": 1,
            "originalPrice": 6,
            "printReadyFile": "https://example.com/image.png",
            "price": 5.4,
            "description": "12oz Enamel Mug White with stainless steel rim\t",
            "sku": "PP-ENAMUG-12OZ-W",
            "subscriptionDiscount": {
                "amount": 0.6,
                "percentage": 10
            }
        }
    ],
    "subtotal": 5.4,
    "shippingBasePrice": 4.4,
    "shippingAdditionalFee": 0,
    "totalShippingCost": 4.4,
    "tax": {
        "amount": 2.01,
        "rate": 20,
        "jurisdiction": "GB",
        "breakdown": [
            {
                "reason": "standard_rated",
                "amount": 2.01,
                "type": "vat",
                "rate": 20,
                "taxable_amount": 10.05,
                "jurisdiction": "GB"
            }
        ]
    },
    "total": {
        "amount": 12.06
    },
    "holdUntil": "2025-08-28T21:17:04.773Z",
    "orderDelay": "immediate",
    "merchantReference": "REF1234",
    "duties": 0,
    "storeId": null,
    "insert": {
        "description": "Colour Packing Slip Insert",
        "originalCost": 0.5,
        "cost": 0.25,
        "type": "packing_slip_colour",
        "subscriptionDiscount": {
            "amount": 0.25,
            "percentage": 50
        },
        "imageUrl": "https://example.com/insert-image.jpg"
    },
    "_dutiesDetails": {
        "calculationTimestamp": "2025-08-28T21:17:04.977Z",
        "amount": 0,
        "shippingCountry": "GB",
        "breakdown": [
            {
                "productTitle": "Enamel Mugs",
                "dutiableBase": 0,
                "reason": "No tariff data for country",
                "bufferAmount": 0,
                "baseDutiesAmount": 0,
                "bufferPercentage": 2.5,
                "dutiesAmount": 0,
                "tariffData": null,
                "sku": "PP-ENAMUG-12OZ-W"
            }
        ]
    },
    "amountPaid": 12,
    "packingSlip": "https://example.com/packaging-slip.pdf"
}

Order Status Types

pending

Order created, updates can be made before processing

held

Order held for manual review

processing

Order being processed

in-production

Order in production

printed

Order has been printed

completed

Order finished and shipped

cancelled

Order cancelled

Errors

The Papello API uses conventional HTTP response codes and returns detailed error information to help you debug issues.

Response Format

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

HTTP Status Codes

200 Success

400 Bad Request (invalid parameters)

401 Unauthorized (invalid API key)

403 Forbidden (insufficient permissions)

404 Not Found

429 Too Many Requests (rate limit exceeded)

500 Internal Server Error

Common Error Codes

INVALID_API_KEY

The provided API key is invalid or expired

INVALID_SKU

The provided SKU does not exist

INVALID_SHIPPING_METHOD

The shipping method is not available for the destination

ORDER_NOT_FOUND

The specified order ID does not exist

ORDER_NOT_UPDATEABLE

The order cannot be updated in its current status

RATE_LIMIT_EXCEEDED

Catalogue (or other throttled) endpoint called too frequently for your API key

Order Flow

Understanding the complete order lifecycle from creation to delivery.

Discover Products

Browse the catalogue to find a valid SKU:

Catalogue Discovery

# 1. List collections
curl -X GET "https://api.papello.com/v1/catalogue/collections" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

# 2. List products in a collection
curl -X GET "https://api.papello.com/v1/catalogue/collections/mugs/products" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

# 3. List SKUs for a product
curl -X GET "https://api.papello.com/v1/catalogue/products/12oz-enamel-mug/variations" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Create Quote

Generate pricing with POST /v1/quote

Quote Request

curl -X POST "https://api.papello.com/v1/quote" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -d '{"items": [{"sku": "PP-EAM-5x7", "quantity": 1}], "shipping": {"country": "GB"}}'

Create Order

Place order with POST /v1/orders

Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -d '{"shipping": {...}, "items": [{"sku": "PP-EAM-5x7", "printReadyFile": "...", "quantity": 1}]}'

Order Processing

Order moves through: pending → processing → completed

Monitor with GET /v1/orders/{orderId}

Shipping Notification

Receive webhook with tracking information

Webhook Event

{
  "event": "order.shipped",
  "orderId": "PPA-01069647",
  "trackingNumber": "TRK123456789",
  "carrier": "Royal Mail"
}

Delivery

Customer receives product, order marked as delivered

Help and Support

Get help with API integration, troubleshooting, and technical questions.

Email Support

Get direct help from our technical team

help@papello.com

Postman Collection

Test and explore the API interactively

View Collection

Dashboard

Manage API keys and view order history

dash.papello.com

Supported Currencies

AUD, BRL, GBP, CAD, DKK, EUR, HKD, INR, JPY, MYR, MXN, NZD, NOK, SGD, ZAR, KRW, SEK, CHF, THB, AED, USD

Default: New accounts default to GBP currency. You can change this in your account settings.

Shipping Methods

•Budget: Budget shipping service (cheapest)
•Standard: Regular shipping service
•Express: Expedited shipping service (faster delivery)

Mugs

Loading product details

Papello API Documentation

Getting Started

Register Dashboard Account

Create your free account at dash.papello.com to access your API keys and manage your orders.

Generate API Keys

Generate both test and live API keys from your dashboard to start making authenticated requests.

Make Your First Request

Start with a simple quote request to understand the API structure and response format.

Base URL

API Base URL

https://api.papello.com

Environments (Test/Live)

Papello provides separate test and live environments to ensure safe development and testing before going into production.

Test Environment

API Key Prefix: test_

Use for development and testing. Orders placed with test keys are not fulfilled and no charges are made.

•No actual printing or shipping
•All API endpoints available
•Perfect for integration testing

Live Environment

API Key Prefix: live_

Use for production orders. Orders placed with live keys are processed and fulfilled.

•Real printing and shipping
•Actual charges apply
•Production-ready

Authentication

All API requests require authentication using Bearer tokens. You'll receive both test and live API keys upon registration in your Papello Dashboard.

Authentication Header

Authorization: Bearer YOUR_API_KEY

Example Request

Authenticated Request Example

curl -X GET "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Orders

The Orders API allows you to create, retrieve, and manage print orders with comprehensive product and shipping details.

Create Order

Endpoint: POST /v1/orders

Create Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORDER-123",
    "amountPaid": 59.89,
    "packingSlip": "https://example.com/packingslip.pdf",
    "shipping": {
      "firstName": "John",
      "lastName": "Doe", 
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "London",
      "state": "Greater London",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "shippingMethod": "Standard"
    },
    "items": [{
      "sku": "PP-ENAMUG-12OZ-W",
      "printReadyFile": "https://example.com/artwork.png",
      "quantity": 1
    }]
  }'

Response Example

Create Order Response

{
    "orderId": "PPA-01070420",
    "orderReference": "order-1756415824773-4cppfw",
    "status": "processing",
    "createdAt": "2025-08-28T21:17:04.773Z",
    "mode": "test",
    "userId": "userId",
    "userEmail": "example@example.com",
    "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "GB",
        "city": "122 Main Street",
        "address1": "Apt 4b",
        "postcode": "SW1A 1AA",
        "currency": "GBP",
        "state": "London"
    },
    "currency": "GBP",
    "shipping": {
        "firstName": "John",
        "lastName": "Doe",
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "London",
        "postcode": "SW1A 1AA",
        "country": "GB",
        "requestedShippingMethod": "Standard",
        "shippingMethod": "RM Tracked 48"
    },
    "items": [
        {
            "sku": "PP-ENAMUG-12OZ-W",
            "quantity": 1,
            "price": 5.4,
            "description": "12oz Enamel Mug White with stainless steel rim\t",
            "originalPrice": 6,
            "subscriptionDiscount": {
                "percentage": 10,
                "amount": 0.6
            },
            "printReadyFile": "https://example.com/image.png"
        }
    ],
    "subtotal": 5.4,
    "shippingBasePrice": 4.4,
    "shippingAdditionalFee": 0,
    "totalShippingCost": 4.4,
    "insert": {
        "type": "packing_slip_colour",
        "description": "Colour Packing Slip Insert",
        "cost": 0.25,
        "imageUrl": "https://example.com/insert-image.jpg",
        "originalCost": 0.5,
        "subscriptionDiscount": {
            "percentage": 50,
            "amount": 0.25
        }
    },
    "duties": 0,
    "tax": {
        "amount": 2.01,
        "rate": 20,
        "jurisdiction": "GB",
        "breakdown": [
            {
                "amount": 2.01,
                "rate": 20,
                "jurisdiction": "GB",
                "type": "vat",
                "reason": "standard_rated",
                "taxable_amount": 10.05
            }
        ]
    },
    "total": {
        "amount": 12.06
    },
    "holdUntil": "2025-08-28T21:17:04.773Z",
    "orderDelay": "immediate",
    "merchantReference": "REF1234",
    "amountPaid": 12,
    "packingSlip": "https://example.com/packaging-slip.pdf"
}

Create Order with Multiple Items

Endpoint: POST /v1/orders

Create an order containing multiple different products in a single order.

Multiple Items Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORD-123456789",
    "amountPaid": 59.89,
    "packingSlip": "https://example.com/packingslip.pdf",
    "shipping": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "London",
      "postcode": "11111",
      "country": "US",
      "phone": "+44123456789",
      "shippingMethod": "Standard"
    },
    "items": [
      {
        "sku": "PP-EAM-A5",
        "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg",
        "quantity": 1
      }, 
      {
        "sku": "PP-EAM-A4",
        "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg",
        "quantity": 1
      }
    ]
  }'

Create Order with Multiple Print Areas

Endpoint: POST /v1/orders

Create an order for products that have more than one print area (e.g. front + back, inside card).

Multiple Print Areas Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORD-123456789",
    "amountPaid": 4.00,
    "packingSlip": "https://example.com/packingslip.pdf",
    "shipping": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "shippingMethod": "Standard"
    },
    "items": [{
      "sku": "PP-GRE-A5-V-ENVELOPE",
      "quantity": 1,
      "price": 1.45,
      "printReadyFiles": [
        {
          "name": "Front & Back",
          "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg"
        },
        {
          "name": "Inside Card",
          "printReadyFile": "https://cdn.papello.com/POSTER_22_6430163d52.jpg"
        }
      ]
    }]
  }'

Get Orders

Endpoint: GET /v1/orders

Get Orders Request

curl -X GET "https://api.papello.com/v1/orders?page=1&limit=10&status=processing" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Get Orders Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "orderId": "PPA-01069647",
        "orderReference": "order-1747328967347-wgw3qr",
        "createdAt": "2025-05-15T14:22:47.347Z",
        "status": "processing",
        "mode": "test",
        "userEmail": "customer@example.com",
        "subtotal": 35,
        "totalShippingCost": 4.4,
        "total": {
          "amount": 46.4
        },
        "items": [{
          "sku": "PP-CF-MOUNT-PSM-A4-BF",
          "printReadyFile": "https://example.com/artwork.jpg",
          "quantity": 1,
          "price": 35
        }],
        "shipping": {
          "firstName": "John",
          "lastName": "Doe",
          "address1": "123 Main St",
          "city": "London",
          "postcode": "SW1A 1AA",
          "country": "GB",
          "shippingMethod": "RM Tracked 48"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 42,
      "items_per_page": 10,
      "has_more": true
    }
  }
}

Order Actions

Manage your orders with various actions including updates, releases, and cancellations.

Update Recipient on Order

Endpoint: PUT /v1/orders/{orderId}

Update recipient shipping details on a pending order.

Update Recipient Request

curl -X PUT "https://api.papello.com/v1/orders/PPA-01069647" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "firstName": "Johnny",
      "lastName": "Doe",
      "address1": "132 Main St",
      "address2": "Apt 4444B",
      "state": "Greater London",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "phone": "+44123456789"
    }
  }'

Update Shipping Method

Endpoint: PUT /v1/orders/{orderId}

Update the shipping method on a pending order.

Update Shipping Method Request

curl -X PUT "https://api.papello.com/v1/orders/PPA-01069647" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "shippingMethod": "Express"
    }
  }'

Update Response Example

Update Order Response

{
  "orderId": "{orderId}",
  "orderReference": "{orderReference}",
  "status": "pending",
  "createdAt": "2025-08-29T12:07:45.159Z",
  "mode": "live",
  "userId": "{userId}",
  "userEmail": "test@example.com",
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "country": "GB",
    "city": "122 Main Street",
    "address1": "Apt 4b",
    "postcode": "SW1A 1AA",
    "currency": "GBP",
    "state": "London"
  },
  "currency": "GBP",
  "shipping": {
    "firstName": "Johnny",
    "lastName": "Doe",
    "country": "GB",
    "requestedShippingMethod": "Express",
    "city": "London",
    "phone": "+44123456789",
    "address2": "Apt 4444B",
    "address1": "132 Main St",
    "shippingMethod": "UPS Domestic Express",
    "postcode": "SW1A 1AA",
    "state": "Greater London",
    "estimatedDelivery": "3-5 working days"
  },
  "items": [...],
  "subtotal": 5.4,
  "totalShippingCost": 4.4,
  "tax": {...},
  "total": {
    "amount": 12.06
  },
  "holdUntil": "2025-08-28T21:17:04.773Z",
  "orderDelay": "immediate",
  "merchantReference": "REF1234",
  "duties": 0,
  "amountPaid": 12,
  "updatedAt": "2025-08-31T18:39:48.080Z"
}

Important Notes

•Orders can only be updated while they are in "pending" status
•Once an order moves to processing, updates are no longer possible
•Price recalculations happen automatically based on updated shipping options

Release Order

Endpoint: POST /v1/orders/{orderId}/release

Release a pending order to production. Orders can be set to hold for a specified time to allow for changes before automatic release. Release times can be set in the order settings in the dashboard.

Release Order Request

curl -X POST "https://api.papello.com/v1/orders/PPA-01069647/release" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Release Order Response

{
  "success": true,
  "data": {
    "orderId": "{orderId}",
    "orderReference": "{orderReference}",
    "status": "processing",
    "message": "Order successfully released for processing",
    "releasedAt": "2025-08-31T18:48:38.866Z",
    "paymentStatus": "success"
  }
}

Cancel Order

Endpoint: POST /v1/orders/{orderId}/cancel

Cancel a pending order. Only orders in "pending" status can be cancelled.

Cancel Order Request

curl -X POST "https://api.papello.com/v1/orders/PPA-01069647/cancel" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Cancel Order Response

{
  "success": true,
  "data": {
    "orderId": "{orderId}",
    "orderReference": "{orderReference}",
    "status": "cancelled",
    "message": "Order successfully cancelled",
    "cancelledAt": "2025-08-31T18:45:59.690Z"
  }
}

Quotes

Generate accurate pricing quotes for potential orders without payment processing. Includes pricing breakdown, shipping costs, taxes, and duties.

Generate Quote

Endpoint: POST /v1/quote

Generate Quote Request

curl -X POST "https://api.papello.com/v1/quote" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "country": "US",
      "shippingMethod": "Standard"
    },
    "items": [{
      "sku": "PP-EAM-5x7",
      "quantity": 1
    }]
  }'

Generate Quote with Multiple Items

Endpoint: POST /v1/quote

Get pricing for multiple different products in a single quote request.

Multiple Items Quote Request

curl -X POST "https://api.papello.com/v1/quote" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping": {
      "country": "US",
      "shippingMethod": "Standard"
    },
    "items": [
      {
        "sku": "PP-EAM-A5",
        "quantity": 1
      },
      {
        "sku": "PP-EAM-A4",
        "quantity": 2
      },
      {
        "sku": "PP-ENAMUG-12OZ-W",
        "quantity": 1
      }
    ]
  }'

Response Example

Generate Quote Response

{
  "success": true,
  "data": {
    "currency": "GBP",
    "conversionRate": 1.0,
    "pricing": {
      "subtotal": 3.00,
      "shipping": 6.27,
      "insertCharge": 0.50,
      "duties": 0.78,
      "tax": 0.00,
      "total": 10.55
    },
    "pricingBreakdown": {
      "items": [{
        "sku": "PP-EAM-5x7",
        "quantity": 1,
        "basePrice": 3.00,
        "additionalPrintFees": 0.00,
        "totalPerItem": 3.00,
        "totalForQuantity": 3.00
      }],
      "shipping": {
        "methodName": "RM Tracked International US",
        "methodId": 114,
        "cost": 6.27,
        "estimatedDelivery": "3-5 working days*"
      },
      "tax": {
        "amount": 0.00,
        "rate": 0,
        "jurisdiction": "GB"
      }
    },
    "metadata": {
      "mode": "live",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  }
}

Catalogue

Browse the Papello product catalogue programmatically. These read-only endpoints let you discover collections, list products within a collection, and retrieve enabled variation SKUs for a product.

Use this three-step flow before placing orders or generating quotes:

List collections — pick a collection slug
List products in that collection — pick a product slug
List variations for that product — pick a SKU for POST /v1/quote or POST /v1/orders

All catalogue endpoints require the same Bearer token authentication as the rest of the public API. Both test_ and live_ API keys work identically for catalogue reads.

Base URL

API Base URL

https://api.papello.com

Authentication

Authentication Header

Authorization: Bearer YOUR_API_KEY

Rate Limits

Rate limits apply per API key owner (not per IP):

Endpoint	Limit
`GET /v1/catalogue/collections`	60 requests / minute
`GET /v1/catalogue/collections/:slug/products`	30 requests / minute
`GET /v1/catalogue/products/:slug/variations`	30 requests / minute

If you exceed the limit, the API returns HTTP 429 with:

Rate Limit Error Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down and try again shortly."
  }
}

Caching

Responses include a Cache-Control header allowing clients to cache for up to 5 minutes:

Cache-Control Header

Cache-Control: max-age=300, stale-while-revalidate=60

Catalogue data is also cached server-side for 5 minutes, so repeated requests for the same resource are fast and stable.

Slugs

Collection and product :slug path parameters are the SEO canonical URL slugs from the Papello CMS (for example mugs, greeting-cards, 12oz-enamel-mug). They are not numeric IDs.

There is no global "list all products" or "list all variations" endpoint by design — products are always scoped to a collection, and variations are always scoped to a single product.

List Collections

Endpoint: GET /v1/catalogue/collections

Returns all product collections in the Papello catalogue.

List Collections Request

curl -X GET "https://api.papello.com/v1/catalogue/collections" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

List Collections Response

{
  "data": [
    {
      "slug": "mugs",
      "title": "Mugs",
      "image": {
        "url": "https://cms.papello.com/uploads/mugs_collection_abc123.jpg",
        "thumbnail": "https://cms.papello.com/uploads/thumbnail_mugs_collection_abc123.jpg"
      }
    },
    {
      "slug": "greeting-cards",
      "title": "Greeting Cards",
      "image": {
        "url": "https://cms.papello.com/uploads/greeting_cards_def456.jpg",
        "thumbnail": "https://cms.papello.com/uploads/thumbnail_greeting_cards_def456.jpg"
      }
    },
    {
      "slug": "wall-art",
      "title": "Wall Art",
      "image": null
    }
  ]
}

Response Fields

Field	Type	Description
`data`	array	List of collections
`data[].slug`	string	Collection slug — use in `GET /v1/catalogue/collections/:slug/products`
`data[].title`	string	Display name
`data[].image`	object \| null	Collection image URLs
`data[].image.url`	string	Full-size image URL
`data[].image.thumbnail`	string	Thumbnail image URL

List Products by Collection

Endpoint: GET /v1/catalogue/collections/:slug/products

Returns products belonging to a single collection. Variations/SKUs are not included — use the variations endpoint for those.

Path Parameters

Parameter	Description
`slug`	Collection slug from `GET /v1/catalogue/collections` (e.g. `mugs`)

List Products by Collection Request

curl -X GET "https://api.papello.com/v1/catalogue/collections/mugs/products" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

List Products by Collection Response

{
  "data": [
    {
      "slug": "12oz-enamel-mug",
      "title": "12oz Enamel Mug",
      "subtitle": "White with stainless steel rim",
      "thumbnail": "https://cms.papello.com/uploads/enamel_mug_thumb.jpg"
    },
    {
      "slug": "11oz-ceramic-mug",
      "title": "11oz Ceramic Mug",
      "subtitle": "Gloss white finish",
      "thumbnail": "https://cms.papello.com/uploads/ceramic_mug_thumb.jpg"
    }
  ],
  "collection": {
    "title": "Mugs",
    "slug": "mugs"
  }
}

Response Fields

Field	Type	Description
`data`	array	Products in the collection
`data[].slug`	string	Product slug — use in `GET /v1/catalogue/products/:slug/variations`
`data[].title`	string	Product name
`data[].subtitle`	string \| null	Short product description
`data[].thumbnail`	string \| null	Product thumbnail image URL
`collection.title`	string	Parent collection name
`collection.slug`	string	Parent collection slug

Error: Collection Not Found

HTTP 404 if the collection slug does not exist:

Collection Not Found Error

{
  "statusCode": 404,
  "message": "Collection not found: invalid-slug",
  "error": "Not Found"
}

List Variations by Product

Endpoint: GET /v1/catalogue/products/:slug/variations

Returns enabled variations (SKUs) for a single product. Use the returned sku values with POST /v1/quote, POST /v1/orders, or GET /validate-sku.

Path Parameters

Parameter	Description
`slug`	Product slug from `GET /v1/catalogue/collections/:slug/products` (e.g. `12oz-enamel-mug`)

List Variations by Product Request

curl -X GET "https://api.papello.com/v1/catalogue/products/12oz-enamel-mug/variations" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example — Single Print Area

List Variations Response (Single Print Area)

{
  "data": [
    {
      "sku": "PP-ENAMUG-12OZ-W",
      "description": "12oz Enamel Mug White with stainless steel rim",
      "printArea": {
        "artworkWidth": 2400,
        "artworkHeight": 960
      }
    },
    {
      "sku": "PP-ENAMUG-12OZ-B",
      "description": "12oz Enamel Mug Black with stainless steel rim",
      "printArea": {
        "artworkWidth": 2400,
        "artworkHeight": 960
      }
    }
  ],
  "product": {
    "title": "12oz Enamel Mug",
    "slug": "12oz-enamel-mug"
  }
}

Response Example — Multiple Print Areas

List Variations Response (Multiple Print Areas)

{
  "data": [
    {
      "sku": "PP-GRE-A5-V-ENVELOPE",
      "description": "A5 Greetings Card (Include Envelope)",
      "printArea": {
        "artworkWidth": 3508,
        "artworkHeight": 2480
      },
      "multiPrintArea": [
        {
          "name": "Front/Back",
          "additionalPrintFee": null,
          "requiredView": true,
          "artworkWidth": 3508,
          "artworkHeight": 2480
        },
        {
          "name": "Inside",
          "additionalPrintFee": 0.25,
          "requiredView": false,
          "artworkWidth": 3508,
          "artworkHeight": 2480
        }
      ]
    }
  ],
  "product": {
    "title": "A5 Greeting Card",
    "slug": "a5-greeting-card"
  }
}

Response Fields

Field	Type	Description
`data`	array	Enabled variations for the product
`data[].sku`	string	Papello SKU — use in quotes and orders
`data[].description`	string	Variation description
`data[].printArea`	object \| null	Primary artwork dimensions in pixels
`data[].printArea.artworkWidth`	number	Artwork width (px)
`data[].printArea.artworkHeight`	number	Artwork height (px)
`data[].multiPrintArea`	array	Present when the product has multiple print views
`data[].multiPrintArea[].name`	string	Print area name (matches order `printReadyFiles[].name`)
`data[].multiPrintArea[].additionalPrintFee`	number \| null	Extra charge for this print area, if any
`data[].multiPrintArea[].requiredView`	boolean	Whether this view is required
`data[].multiPrintArea[].artworkWidth`	number \| null	View-specific width (px)
`data[].multiPrintArea[].artworkHeight`	number \| null	View-specific height (px)
`product.title`	string	Parent product name
`product.slug`	string	Parent product slug

Error: Product Not Found

HTTP 404 if the product slug does not exist:

Product Not Found Error

{
  "statusCode": 404,
  "message": "Product not found: invalid-slug",
  "error": "Not Found"
}

Catalogue vs SKU Validation

These endpoints complement Product Details (SKU Validation) (GET /validate-sku?sku={sku}):

	Catalogue API	SKU Validation
Purpose	Browse and discover products	Validate a specific SKU before ordering
Scope	Collections → products → variations	Single SKU lookup
Returns pricing	No	Yes (`Price`, subscription discount)
Returns print areas	Yes (dimensions + multi-area names)	Yes (detailed `printAreas` array)
Best for	Building product pickers, integrations, storefronts	Pre-flight checks before order creation

Recommended flow:

GET /v1/catalogue/collections
GET /v1/catalogue/collections/:slug/products
GET /v1/catalogue/products/:slug/variations
GET /validate-sku?sku={sku} — optional, for pricing and detailed print-area metadata
POST /v1/quote or POST /v1/orders

Important Notes

•Catalogue endpoints return JSON directly (no { "success": true, "data": ... } wrapper).
•Only enabled variations are returned from the variations endpoint.
•Disabled or draft CMS entries are excluded automatically.
•For order placement, artwork files must still meet the file requirements in Product Details (SKU Validation) (JPG/JPEG/PNG, 300 DPI minimum).
•There is no endpoint to fetch all products across every collection, or all variations globally.

Product Details (SKU Validation)

Validate product SKUs and retrieve detailed product information before placing orders.

Validate SKU

Endpoint: GET /validate-sku?sku={variationSku}

Validate a product SKU and get detailed information including print areas and pricing.

SKU Validation Request

curl -X GET "https://api.papello.com/validate-sku?sku=PP-GRE-A5-V-ENVELOPE" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

SKU Validation Response

{
  "Description": "A5 Greetings Card (Include Envelope)",
  "SKU": "PP-GRE-A5-V-ENVELOPE",
  "Price": 1.45,
  "plusSubDiscount": 20,
  "product_size": {
    "Name": "29.7x21cm / 11.7x8.3\" (A5 Folded)",
    "ArtworkWidth": 3508,
    "ArtworkHeight": 2480
  },
  "printAreas": [
    {
      "name": "Front/Back"
    },
    {
      "name": "Inside",
      "additionalPrintFee": 0.25
    }
  ]
}

SKU Validation

All product SKUs should be validated before creating orders. Invalid SKUs will result in order creation failures.

Common SKU Examples

PP-EAM-5x7- 5x7 Enhanced Archival Matte
PP-CF-MOUNT-PSM-A4-BF- A4 Black Frame Mount
PP-ENAMUG-12OZ-W- 12oz White Enamel Mug

File Requirements

Print-Ready Files

•Supported formats: JPG, JPEG, PNG
•Minimum resolution: 300 DPI
•Color mode: RGB or CMYK (sRGB is recommended)

Packing Slips

•Supported formats: PDF
•File size limit: 10MB

Webhooks

Receive real-time notifications about order status changes and important events in your order lifecycle.

Webhook Configuration

Configure webhook endpoints in your Papello Dashboard to receive event notifications.

Available Events

order.shipped- When order is shipped with full tracking information

Webhook Event Example

Order Shipped Webhook

{
  "event": "order.shipped",
  "timestamp": "2025-09-25T11:50:35.787Z",
  "data": {
    "orderId": "PPA-01069729",
    "orderReference": "order-1748092696225-4hmp76",
    "status": "shipped",
    "shippingInfo": {
      "trackingNumber": "1234567890GB",
      "carrier": "Royal Mail",
      "service": "Tracked 48",
      "shipDate": "2025-09-25T10:20:35.787Z",
      "updatedAt": "2025-09-25T11:50:35.787Z"
    }
  }
}

Order Status

Track and monitor order progress through various status stages from creation to delivery.

Get Order Status

Endpoint: GET /v1/orders/{orderId}

Get Order Status Request

curl -X GET "https://api.papello.com/v1/orders/PPA-01069647" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Response Example

Get Order Status Response

{
    "orderId": "{orderId}",
    "orderReference": "{orderReference}",
    "status": "in-production",
    "createdAt": "2025-08-28T21:17:04.773Z",
    "mode": "test",
    "userId": "userId",
    "userEmail": "example@example.com",
    "billing": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "GB",
        "city": "122 Main Street",
        "address1": "Apt 4b",
        "postcode": "SW1A 1AA",
        "currency": "GBP",
        "state": "London"
    },
    "currency": "GBP",
    "shipping": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "GB",
        "requestedShippingMethod": "Standard",
        "address2": "Apt 4B",
        "city": "London",
        "address1": "123 Main St",
        "shippingMethod": "RM Tracked 48",
        "postcode": "SW1A 1AA"
    },
    "items": [
        {
            "quantity": 1,
            "originalPrice": 6,
            "printReadyFile": "https://example.com/image.png",
            "price": 5.4,
            "description": "12oz Enamel Mug White with stainless steel rim\t",
            "sku": "PP-ENAMUG-12OZ-W",
            "subscriptionDiscount": {
                "amount": 0.6,
                "percentage": 10
            }
        }
    ],
    "subtotal": 5.4,
    "shippingBasePrice": 4.4,
    "shippingAdditionalFee": 0,
    "totalShippingCost": 4.4,
    "tax": {
        "amount": 2.01,
        "rate": 20,
        "jurisdiction": "GB",
        "breakdown": [
            {
                "reason": "standard_rated",
                "amount": 2.01,
                "type": "vat",
                "rate": 20,
                "taxable_amount": 10.05,
                "jurisdiction": "GB"
            }
        ]
    },
    "total": {
        "amount": 12.06
    },
    "holdUntil": "2025-08-28T21:17:04.773Z",
    "orderDelay": "immediate",
    "merchantReference": "REF1234",
    "duties": 0,
    "storeId": null,
    "insert": {
        "description": "Colour Packing Slip Insert",
        "originalCost": 0.5,
        "cost": 0.25,
        "type": "packing_slip_colour",
        "subscriptionDiscount": {
            "amount": 0.25,
            "percentage": 50
        },
        "imageUrl": "https://example.com/insert-image.jpg"
    },
    "_dutiesDetails": {
        "calculationTimestamp": "2025-08-28T21:17:04.977Z",
        "amount": 0,
        "shippingCountry": "GB",
        "breakdown": [
            {
                "productTitle": "Enamel Mugs",
                "dutiableBase": 0,
                "reason": "No tariff data for country",
                "bufferAmount": 0,
                "baseDutiesAmount": 0,
                "bufferPercentage": 2.5,
                "dutiesAmount": 0,
                "tariffData": null,
                "sku": "PP-ENAMUG-12OZ-W"
            }
        ]
    },
    "amountPaid": 12,
    "packingSlip": "https://example.com/packaging-slip.pdf"
}

Order Status Types

pending

Order created, updates can be made before processing

held

Order held for manual review

processing

Order being processed

in-production

Order in production

printed

Order has been printed

completed

Order finished and shipped

cancelled

Order cancelled

Errors

The Papello API uses conventional HTTP response codes and returns detailed error information to help you debug issues.

Response Format

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

HTTP Status Codes

200 Success

400 Bad Request (invalid parameters)

401 Unauthorized (invalid API key)

403 Forbidden (insufficient permissions)

404 Not Found

429 Too Many Requests (rate limit exceeded)

500 Internal Server Error

Common Error Codes

INVALID_API_KEY

The provided API key is invalid or expired

INVALID_SKU

The provided SKU does not exist

INVALID_SHIPPING_METHOD

The shipping method is not available for the destination

ORDER_NOT_FOUND

The specified order ID does not exist

ORDER_NOT_UPDATEABLE

The order cannot be updated in its current status

RATE_LIMIT_EXCEEDED

Catalogue (or other throttled) endpoint called too frequently for your API key

Order Flow

Understanding the complete order lifecycle from creation to delivery.

Discover Products

Browse the catalogue to find a valid SKU:

Catalogue Discovery

# 1. List collections
curl -X GET "https://api.papello.com/v1/catalogue/collections" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

# 2. List products in a collection
curl -X GET "https://api.papello.com/v1/catalogue/collections/mugs/products" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

# 3. List SKUs for a product
curl -X GET "https://api.papello.com/v1/catalogue/products/12oz-enamel-mug/variations" \
  -H "Authorization: Bearer test_YOUR_API_KEY"

Create Quote

Generate pricing with POST /v1/quote

Quote Request

curl -X POST "https://api.papello.com/v1/quote" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -d '{"items": [{"sku": "PP-EAM-5x7", "quantity": 1}], "shipping": {"country": "GB"}}'

Create Order

Place order with POST /v1/orders

Order Request

curl -X POST "https://api.papello.com/v1/orders" \
  -H "Authorization: Bearer test_YOUR_API_KEY" \
  -d '{"shipping": {...}, "items": [{"sku": "PP-EAM-5x7", "printReadyFile": "...", "quantity": 1}]}'

Order Processing

Order moves through: pending → processing → completed

Monitor with GET /v1/orders/{orderId}

Shipping Notification

Receive webhook with tracking information

Webhook Event

{
  "event": "order.shipped",
  "orderId": "PPA-01069647",
  "trackingNumber": "TRK123456789",
  "carrier": "Royal Mail"
}

Delivery

Customer receives product, order marked as delivered

Help and Support

Get help with API integration, troubleshooting, and technical questions.

Email Support

Get direct help from our technical team

help@papello.com

Postman Collection

Test and explore the API interactively

View Collection

Dashboard

Manage API keys and view order history

dash.papello.com

Supported Currencies

AUD, BRL, GBP, CAD, DKK, EUR, HKD, INR, JPY, MYR, MXN, NZD, NOK, SGD, ZAR, KRW, SEK, CHF, THB, AED, USD

Default: New accounts default to GBP currency. You can change this in your account settings.

Shipping Methods

•Budget: Budget shipping service (cheapest)
•Standard: Regular shipping service
•Express: Expedited shipping service (faster delivery)