Getting Started

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

Prerequisites

Before you begin, you need:

• A partner account on the test environment. Create a test account if you don't have one.
• A V2 API secret key for that test account, generated in the test Dashboard under API credentials.

The test environment is where you build and verify your integration. You only need a production account and a production key once your integration is ready to place real orders.

Environments

Printeers provides two environments. Each has its own Dashboard, its own partner accounts and its own API keys:

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

Secret keys are bound to one environment. A key created in the production Dashboard is rejected by the test API with 401 Unauthorized, and the other way around. Sign up separately on the test Dashboard and create a key there to use the test API; the two environments share no accounts, keys, products or orders.

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 with the secret key from your test account:

curl -i 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. The most common cause is using a key from the production Dashboard against the test API: create the key on dashboard.test-printeers.com instead.

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:

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. Secret keys are bound to one environment: the test API only accepts keys created on https://dashboard.test-printeers.com, the production API only keys from https://dashboard.printeers.com. Set a unique customIdentifier on every order you create so a retried request cannot create a duplicate order.

Next Steps

• Read the Organization Structure guide to understand accounts, stores, and brands.
• Browse the API Reference for detailed endpoint documentation.
• Read the API Versioning guide to understand our release cycle.
• Learn how to paginate through large result sets.