Server-to-server API
Build custom commerce experiences on Printlet
Connect any custom website or app to Printlet's catalog, artwork, preview, quoting, order, and fulfillment services. Your app owns the customer experience; Printlet handles production.
Introduction
How the API Integration works
API Integration is a server-to-server fulfillment channel for merchants whose storefront or application is custom-built. Your customer never calls Printlet directly: your backend discovers the catalog, submits artwork and placement choices, creates the order, and receives signed lifecycle events.
The integration boundary
Your application owns the storefront and checkout. Printlet receives production-ready instructions and sends fulfillment updates back.
Your customer
Custom experience
Designs a product and pays your business.
Your system
Merchant backend
Owns customer identity, pricing, checkout, tax, and COD verification.
Printlet platform
API Integration v1
Provides catalog, artwork ingestion, previews, quotes, orders, and events.
Printlet operations
Fulfillment
Prints, packs, ships, and updates the order lifecycle.
Merchant API requests
Signed webhooks return status, validation, and catalog changes
Use the preview endpoint to offer a lightweight configurator without embedding Printlet's full editor. Your app controls the interface while Printlet applies the product's print-area and safe-area rules.
From artwork to print file
Integrators select stable catalog IDs and presets; Printlet owns the print-safe transformation.
- 01Original artworkSend the untouched PNG, JPEG, or WebP file by secure upload or remote HTTPS URL.
- 02Catalog configurationChoose a variant, print area, technique, and named placement preset returned by Printlet.
- 03PreviewPrintlet applies configurator-equivalent placement rules and generates a customer-facing mockup.
- 04Production fileThe original remains attached to the order so Printlet can make safe production adjustments.
The artwork fills the selected print area. The placement preset positions that area inside the safe area; product rules can apply behavior such as phone-case vertical expansion.
Getting started
Quickstart
API Integration is available to all merchants. Create an API Integration store, verify your account email, and issue a test key before touching live fulfillment.
- 1
Create an installation. Choose API Integration as the store integration type. A store can use only one integration type.
- 2
Issue a test credential. After your Printlet account email is verified, open the credentials page and copy the one-time prnt_test_ key.
- 3
Discover the catalog. Request countries first, then products and product details. Persist returned IDs as opaque strings.
- 4
Submit and preview artwork. Upload the original print file, choose a print area and placement preset, then request a preview.
- 5
Quote and create the order. Use a unique Idempotency-Key for every POST and retain the returned Printlet IDs.
- 6
Verify webhooks. Validate every signature against the raw request body before processing lifecycle events.
Test the complete sequence in Postman
Import the ordered collection and staging environment, paste a test credential, then run the requests from catalog discovery through artwork, preview, quotes, orders, COD verification, and lifecycle events.
Core concepts
Authentication
Send your API key as a bearer token on every request. Keys are shown once, scoped to one installation and environment, and can be rotated or revoked from the Printlet dashboard.
Authorization: Bearer prnt_test_...
Content-Type: application/json
Idempotency-Key: 7b407941-6df8-4f3f-bf22-7afeccf08683Test and live environments
Test and live credentials run on Printlet's production-hosted infrastructure while remaining isolated by key, data, and side effects. A prnt_test_ key cannot trigger live fulfillment; a prnt_live_ key can.
| Environment | Credential | Fulfillment |
|---|---|---|
| Test | prnt_test_... | Simulated only |
| Live | prnt_live_... | Real production orders |
Build your integration
Catalog discovery
Discover countries, products, variants, print areas, techniques, placement presets, pricing, and shipping methods through the API. Do not hard-code catalog IDs. They are stable, non-editable identifiers and must be treated as opaque strings.
GET /catalog/countries
GET /catalog/products?country_id={country_id}
GET /catalog/products/{product_id}?country_id={country_id}
GET /catalog/shipping-methods?country_id={country_id}Subscribe to catalog-change webhooks and reconcile with GET /catalog/changes. Printlet also emails merchants before a breaking catalog removal.
Artwork and placement
Upload the untouched source file so Printlet's production team can adjust the print file when necessary. PNG, JPEG, and WebP are accepted up to 25 MiB and 10,000 by 10,000 pixels. Remote sources must use HTTPS and remain available until ingestion completes.
The artwork fills the selected print area. A named placement preset positions the print area inside the product's safe area. Integrators do not send arbitrary coordinates, scaling, rotation, or layers in v1. Product-specific behavior such as phone-case vertical expansion is returned by the catalog.
Preview generation
Create a preview with an accepted artwork, variant, print area, technique, and placement preset. Printlet uses the same placement rules as its configurator and returns the preview asynchronously, allowing custom apps to build a lightweight product configurator.
POST /previews
GET /previews/{preview_id}Quotes, orders, and merchant payment
The merchant owns the end-customer relationship, checkout price, tax collection, and customer-facing shipping rules. Printlet independently charges the merchant its quoted product and shipping cost for the submitted delivery address.
Merchants may enable automatic wallet fulfillment separately for orders whose end customer paid by card or COD. Otherwise, the order remains pending until the merchant funds the wallet or pays manually by card from the Printlet dashboard. Split shipments and partial fulfillment are not supported in v1.
Webhooks and event safety
Printlet signs each delivery with HMAC: a cryptographic fingerprint computed from the timestamp and exact raw request body using your webhook secret. Recompute it on your server, compare in constant time, reject timestamps older than five minutes, and deduplicate by event ID.
Delivery is at least once, so receivers must be idempotent. Return a successful 2xx response only after persisting the event. Use GET /events to reconcile anything missed.
Ship faster
Coding-agent handoff
This prompt includes the documentation, OpenAPI, reference, API base, endpoint sequence, security rules, and acceptance criteria.
Implement a production-ready server-to-server integration with Printlet API Integration v1.
AUTHORITATIVE PRINTLET RESOURCES
- Integration guide: https://printleteg.com/developers/api-integration
- OpenAPI 3.1 contract: https://printleteg.com/api/developer-docs/api-integration/openapi
- Interactive API reference: https://printleteg.com/developers/api-integration/reference
- Credential management: https://printleteg.com/dashboard/settings/integrations/api
- API base URL: https://printleteg.com/api/integrations/v1
Before writing code, fetch and read the integration guide and OpenAPI contract. Treat the OpenAPI document as the source of truth for request and response fields. If either URL cannot be fetched, stop and report the exact URL and HTTP error instead of guessing the contract.
SETUP
1. Ask me to create a test installation and obtain a one-time test key from the credential-management URL.
2. Expect PRINTLET_API_KEY in the server-side environment. Never request that I paste the secret into chat and never expose it to a browser, mobile app, repository, logs, error reports, or generated code.
3. Use this server-side configuration:
PRINTLET_API_BASE_URL=https://printleteg.com/api/integrations/v1
PRINTLET_API_KEY=<read from server environment>
PRINTLET_WEBHOOK_SECRET=<read from server environment>
4. Send Authorization: Bearer $PRINTLET_API_KEY on every API request.
5. Start with prnt_test_ credentials. Do not use live credentials until all acceptance tests pass.
IMPLEMENTATION SEQUENCE
1. Build a typed API client from the OpenAPI contract with timeouts and redacted structured errors.
2. Discover countries, products, product details, variants, print areas, techniques, placement presets, prices, and shipping methods. Never hard-code or derive Printlet IDs; persist them as opaque strings.
3. Upload the untouched original artwork using a direct upload intent or remote HTTPS ingestion. Wait for asynchronous validation to complete.
4. Let the user select only catalog-provided placement presets. The artwork fills the chosen print area; do not submit arbitrary coordinates, layers, scaling, or rotation in v1.
5. Create and poll a preview before checkout so the customer can see Printlet's configurator-equivalent mockup.
6. Create a quote using the recipient address and selected items, then create the order from validated resources.
7. Send a new UUID Idempotency-Key on every POST. Persist the key with the local operation and reuse that same key when retrying the same operation after a timeout.
8. Persist Printlet resource IDs and statuses. Treat pending resources as asynchronous until a webhook or GET response reaches a terminal state.
9. Implement webhook receipt using the exact raw request bytes. Verify Printlet's HMAC signature in constant time, reject timestamps older than five minutes, deduplicate event IDs, persist before returning 2xx, and make processing idempotent.
10. Reconcile missed events through GET /events and process catalog-change events before relying on changed catalog entities.
BUSINESS RULES
- The merchant owns the end-customer relationship, charges any retail amount, and controls customer-facing tax and shipping rules.
- Do not collect Printlet's fulfillment payment during customer checkout. The merchant pays Printlet from wallet balance or manually by card in the Printlet dashboard.
- Card-paid and COD customer orders can have separate automatic-wallet-fulfillment settings. Do not commit an unverified COD order unless the merchant's configuration explicitly allows it.
- Test and live credentials and data are isolated. A test key must never create live fulfillment side effects.
DELIVERABLES AND ACCEPTANCE TESTS
- Typed Printlet client isolated behind a small service interface.
- Server-only environment validation with secret redaction.
- Catalog sync/discovery, artwork upload and validation, preview, quote, order creation, order-status reconciliation, and verified webhook handling.
- Integration tests for invalid and revoked authentication, pagination, catalog discovery, artwork rejection, async polling, preview completion, quoting, idempotent order retries, webhook signature validation, stale/replayed events, test/live isolation, rate limits, and documented error responses.
- A short README naming the Printlet documentation and OpenAPI URLs above, required environment variables, local test commands, and the exact steps to switch from test to live safely.
Do not invent missing fields or behavior. Cite the relevant OpenAPI operationId when explaining each implemented API call.Credentials stay outside the prompt. The coding agent reads them from the application's server-side environment only. The prompt itself stays in English so coding agents can follow it.