Printeers

Getting Started

Learn how to set up your integration with the Printeers API.

Prerequisites

Before you begin, you need:

Environments

Printeers provides two environments:

Environment Base URL Purpose
Test https://api.test-printeers.com/v2 Development and testing. Orders are not produced or invoiced.
Production https://api.printeers.com/v2 Live orders. Created orders are produced, delivered, and billed.

Always develop and test your integration against the test environment first.

Authentication

All API requests require authentication via the X-Printeers-Secret-Key header:

X-Printeers-Secret-Key: YOUR_SECRET_KEY

Keep your secret key secure and never expose it in client-side code.

Making Your First Request

Validate your credentials by calling the auth endpoint:

curl -i -X POST https://api.test-printeers.com/v2/auth/validate \
  -H "X-Printeers-Secret-Key: YOUR_SECRET_KEY"

A successful response confirms your credentials are valid:

{
  "message": "Authentication is valid"
}

If authentication fails, you'll receive a 401 Unauthorized response with an error message.

Exploring the API

Once authenticated, you can explore available resources:

  • Catalog: GET /products and GET /packagings to browse available products and packagings.
  • Renders: POST /renders to create product mockups.
  • Orders: GET /orders/{orderReference} to retrieve order details.
  • Shipments: GET /shipments/{shipmentReference} for tracking information. See the Shipments and Tracking guide.

See the API Reference for complete endpoint documentation.

Error Handling

The API uses standard HTTP status codes:

Code Meaning
200 Success
400 Bad request. Check your request data.
401 Unauthorized. Invalid or missing secret key.
403 Forbidden. Valid credentials but insufficient permissions.
404 Not found. Resource doesn't exist.
501 Not implemented. Endpoint not yet available.
5xx Server error. Retry later.

Error responses include a JSON body with details:

{
  "code": "invalid_request",
  "message": "Description of what went wrong"
}

Using AI coding agents

If an AI coding assistant (Claude Code, Cursor, Copilot or an agent framework) builds your integration, point it at the machine-readable sources instead of the HTML pages:

  • llms.txt indexes this documentation and links to the markdown version of every guide; llms-full.txt is the full text of all guides in one file. Any guide is also available as markdown by appending .md to its URL.
  • The OpenAPI specification of the v2 API is the source of truth for endpoints, parameters and schemas.

A starting point for your agent's project instructions (AGENTS.md, CLAUDE.md or similar):

Printeers API: read https://api-docs.printeers.com/llms.txt first. The OpenAPI specification at https://api-docs.printeers.com/static/printeers-api-v2.openapi.json is the source of truth for endpoints and schemas. Develop and test against the test environment, https://api.test-printeers.com/v2, where orders are never produced or invoiced; switch to https://api.printeers.com/v2 only when explicitly asked. Authenticate with the X-Printeers-Secret-Key header and never commit the key. Set a unique customIdentifier on every order you create so a retried request cannot create a duplicate order.

Next Steps