PapelloAPI Docs

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

1

Register Dashboard Account

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

2

Generate API Keys

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

3

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"
    }
  }
}

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 Response
{
  "success": true,
  "data": { ... }
}

Error Response

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

Order Flow

Understanding the complete order lifecycle from creation to delivery.

1

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"}}'
2

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}]}'
3

Order Processing

Order moves through: pending → processing → completed

Monitor with GET /v1/orders/{orderId}

4

Shipping Notification

Receive webhook with tracking information

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

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)