PhotoPrintAgent MCP
An official MCP server enabling AI agents to browse photo print products, upload images, preview crops, obtain live pricing quotes, and manage orders for U.S. home delivery. It supports guest checkout and authenticated account access, handling payments via credit card or crypto (Base/Solana) while requiring explicit human approval before order placement.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
An account and API key are optional.Use an MCP client that supports remote Streamable HTTP and OAuth, guest or bearer-token access.
MCP endpoint (Streamable HTTP)
https://photoprintagent.com/mcpWhat you can do with it
- Browse available photo print sizes and products
- Upload images and preview crop adjustments
- Get live delivery quotes and pricing
- Track order status and delivery progress
Source and maintenance
Vendor evidenceRegistry 2.4.0
Protocol and capabilities
- Server
- PhotoPrintAgent 2.4.0
- MCP protocol
- 2025-06-18
- Tools
- 30 advertised
- Resources
- Not advertised
- Resource templates
- Not advertised
- Prompts
- Not advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
30 advertised
get_checkout_options — Get Checkout Options
Advertised read-only
Public account and guest authentication instructions, current order terms URL/version, and required acceptance field.
get_checkout_options input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
}get_checkout_options output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"terms",
"account",
"guest",
"guideUrl"
],
"properties": {
"guest": {
"type": "object",
"required": [
"endpoint",
"method",
"mcpTool",
"accountRequired",
"paymentMethods"
],
"properties": {
"method": {
"type": "string",
"const": "POST"
},
"mcpTool": {
"type": "string",
"const": "start_guest_checkout"
},
"endpoint": {
"type": "string"
},
"paymentMethods": {
"type": "array",
"items": {
"enum": [
"card",
"x402"
],
"type": "string"
}
},
"accountRequired": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"terms": {
"type": "object",
"required": [
"url",
"version",
"acceptanceField"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"version": {
"type": "string"
},
"acceptanceField": {
"type": "string",
"const": "termsAccepted"
}
},
"additionalProperties": false
},
"account": {
"type": "object",
"required": [
"signInUrl",
"firebaseConfigUrl",
"instructions"
],
"properties": {
"signInUrl": {
"type": "string",
"format": "uri"
},
"instructions": {
"type": "string"
},
"oauthMetadataUrl": {
"type": "string",
"format": "uri"
},
"firebaseConfigUrl": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
},
"guideUrl": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
}get_checkout_options annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}start_guest_checkout — Start Guest Checkout
Open-world
Public: mint a private guest credential once. No account, payment or print is created. Save it in a secret store.
start_guest_checkout input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
}start_guest_checkout output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"token",
"guestApiKey",
"checkoutUntil",
"expiresAt",
"tokenType",
"instructions"
],
"properties": {
"token": {
"type": "string"
},
"expiresAt": {
"$ref": "#/properties/checkoutUntil"
},
"tokenType": {
"type": "string",
"const": "Bearer"
},
"guestApiKey": {
"type": "string"
},
"instructions": {
"type": "string"
},
"checkoutUntil": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
}
},
"additionalProperties": false
}start_guest_checkout annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}create_agent_key — Create Agent Key
Open-world
Mint a 90-day account key using a verified Firebase ID token in Authorization. Guests and existing agent keys cannot mint keys.
create_agent_key input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
}create_agent_key output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"key",
"id",
"expiresAt"
],
"properties": {
"id": {
"type": "string"
},
"key": {
"type": "string"
},
"expiresAt": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
}
},
"additionalProperties": false
}create_agent_key annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}list_products — List Products
Advertised read-onlyOpen-world
Public paginated product catalog, print specifications, and availability. Follow nextOffset until null. availableOnly defaults to true; false includes unavailable public products with explicit available flags. Filters cover query, category, finish, dimensions and known unit price range. capabilities distinguishes API support from current orderability. productCode and sku are PhotoPrintAgent seller codes for customer listings and search; id remains the API identifier for uploads and quotes. Each product supplies artwork dimensions, minimum/maximum image counts, ordered slot labels, bleed and rotation rules. These apply to all active supported products, including multi-image designs. Artwork minimumDpi values are print quality guidance, not an upload rejection threshold: accept smaller valid images, resize them, and treat reduced quality as a nonblocking warning. Admin Only products are never listed. Pass a returned products[].id as productId when uploading and quoting; omission selects the original photo-4x6 product. Price depends on the items and destination; call quote_prints for an authoritative total.
list_products input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1
},
"query": {
"type": "string",
"maxLength": 100
},
"finish": {
"type": "string",
"maxLength": 80
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0
},
"category": {
"type": "string",
"maxLength": 80
},
"widthInches": {
"type": "number",
"maximum": 1000,
"exclusiveMinimum": 0
},
"heightInches": {
"type": "number",
"maximum": 1000,
"exclusiveMinimum": 0
},
"availableOnly": {
"type": "boolean",
"default": true
},
"maxPriceCents": {
"type": "integer",
"minimum": 0
},
"minPriceCents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}list_products output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"product",
"orderingAvailable",
"googleEnabled",
"xEnabled",
"x402Available",
"paymentNetwork",
"solanaAvailable",
"x402PayTo",
"support"
],
"properties": {
"total": {
"type": "number"
},
"product": {
"type": "object",
"required": [
"id",
"title",
"countries",
"maxPhotos",
"maxPrints",
"specs"
],
"properties": {
"id": {
"type": "string",
"const": "photo-4x6"
},
"sku": {
"type": "string"
},
"specs": {
"type": "object",
"required": [
"widthInches",
"heightInches",
"landscapePixels",
"portraitPixels",
"recommendedDpi",
"minimumDpi",
"colorSpace",
"outputFormat",
"maxFileBytes",
"maxInputPixels",
"acceptedMimeTypes",
"acceptedExtensions",
"imageHandling",
"aspectRatio",
"cropRules",
"priceMode"
],
"properties": {
"cropRules": {
"type": "string"
},
"priceMode": {
"type": "string",
"const": "quote_required"
},
"colorSpace": {
"type": "string",
"const": "sRGB"
},
"minimumDpi": {
"type": "number"
},
"aspectRatio": {
"type": "string"
},
"widthInches": {
"type": "number"
},
"heightInches": {
"type": "number"
},
"maxFileBytes": {
"type": "number"
},
"outputFormat": {
"type": "string",
"const": "image/jpeg"
},
"imageHandling": {
"type": "object",
"required": [
"resolutionPolicy",
"animationPolicy",
"multipagePolicy",
"transparencyPolicy",
"colorPolicy",
"svgPolicy",
"unsupportedPolicy",
"helpUrl"
],
"properties": {
"helpUrl": {
"type": "string"
},
"svgPolicy": {
"type": "string"
},
"colorPolicy": {
"type": "string"
},
"animationPolicy": {
"type": "string"
},
"multipagePolicy": {
"type": "string"
},
"resolutionPolicy": {
"type": "string"
},
"unsupportedPolicy": {
"type": "string"
},
"transparencyPolicy": {
"type": "string"
}
},
"additionalProperties": false
},
"maxInputPixels": {
"type": "number"
},
"portraitPixels": {
"type": "array",
"items": {
"type": "number"
}
},
"recommendedDpi": {
"type": "number"
},
"landscapePixels": {
"type": "array",
"items": {
"type": "number"
}
},
"acceptedMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"acceptedExtensions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"title": {
"type": "string"
},
"countries": {
"type": "array",
"items": {
"type": "string",
"const": "US"
}
},
"maxPhotos": {
"type": "integer"
},
"maxPrints": {
"type": "integer"
},
"productCode": {
"type": "string"
}
},
"additionalProperties": false
},
"support": {
"type": "string"
},
"products": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"description",
"widthInches",
"heightInches"
],
"properties": {
"id": {
"type": "string"
},
"sku": {
"type": "string"
},
"size": {
"type": "string"
},
"title": {
"type": "string"
},
"finish": {
"type": "string"
},
"artwork": {
"type": "object",
"required": [
"widthPixels",
"heightPixels",
"minImages",
"maxImages",
"minimumDpi",
"allowRotate",
"labels",
"bleed",
"issues"
],
"properties": {
"bleed": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"issues": {
"type": "array",
"items": {
"type": "string"
}
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"calendar": {
"type": "object",
"required": [
"layout",
"months"
],
"properties": {
"layout": {
"type": "string",
"const": "alternating-photo-grid"
},
"months": {
"enum": [
12,
18
],
"type": "number"
}
},
"additionalProperties": false
},
"maxImages": {
"type": "integer"
},
"minImages": {
"type": "integer"
},
"minimumDpi": {
"type": "number"
},
"allowRotate": {
"type": "boolean"
},
"composition": {
"type": "object",
"required": [
"id",
"width",
"height",
"background",
"slots"
],
"properties": {
"id": {
"type": "string"
},
"slots": {
"type": "array",
"items": {
"type": "object",
"required": [
"x",
"y",
"width",
"height"
],
"properties": {
"x": {
"type": "integer"
},
"y": {
"type": "integer"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"background": {
"type": "string"
}
},
"additionalProperties": false
},
"widthPixels": {
"type": "integer"
},
"heightPixels": {
"type": "integer"
},
"qualityGuidance": {
"type": "object",
"required": [
"recommendedDpi",
"minimumDpiIsRejectionThreshold",
"fitModes",
"fitDescription"
],
"properties": {
"fitModes": {
"type": "array",
"items": {
"type": "string"
}
},
"fitDescription": {
"type": "string"
},
"recommendedDpi": {
"type": "number"
},
"minimumDpiIsRejectionThreshold": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"preview": {
"type": "object",
"additionalProperties": {}
},
"category": {
"type": "string"
},
"shipping": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"enum": [
"provider",
"flat",
"per_item"
],
"type": "string"
},
"amountCents": {
"type": "integer",
"default": 0,
"maximum": 100000,
"minimum": 0
},
"multipleItemAmountCents": {
"anyOf": [
{
"$ref": "#/properties/products/items/properties/shipping/properties/amountCents"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
"adminOnly": {
"type": "boolean"
},
"available": {
"type": "boolean"
},
"description": {
"type": "string"
},
"productCode": {
"type": "string",
"pattern": "^PPA[A-F0-9]{12}$"
},
"widthInches": {
"type": "number"
},
"heightInches": {
"type": "number"
},
"unitPriceCents": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
{
"type": "null"
}
],
"description": "Integer USD cents"
},
"unavailableReason": {
"type": "string"
}
},
"additionalProperties": true
}
},
"xEnabled": {
"type": "boolean"
},
"x402PayTo": {
"type": [
"string",
"null"
]
},
"nextOffset": {
"type": [
"number",
"null"
]
},
"capabilities": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"supported",
"availableToOrder",
"productCount"
],
"properties": {
"supported": {
"type": "boolean"
},
"productCount": {
"type": "number"
},
"availableToOrder": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"googleEnabled": {
"type": "boolean"
},
"x402Available": {
"type": "boolean"
},
"paymentNetwork": {
"type": "string"
},
"catalogProducts": {
"type": "array",
"items": {
"$ref": "#/properties/products/items"
}
},
"solanaAvailable": {
"type": "boolean"
},
"deliveryEstimate": {
"type": "string"
},
"priceFilterBasis": {
"type": "string"
},
"orderingAvailable": {
"type": "boolean"
}
},
"additionalProperties": false
}list_products annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}create_upload — Create Upload
Advertised read-only
Get the authenticated binary upload endpoint and product/crop headers. Pass productId from list_products for every image. Upload each required image separately; retain the returned IDs in slot order. Crops and resolution checks use that product’s artwork specifications, not a universal 4x6 size. POST the image bytes separately; never put base64 or remote image URLs in MCP. For recoverable uploads, send a stable Idempotency-Key on POST and check GET /api/uploads/{key} after a lost response. Retry the same bytes and options with the same key; never retry payment as an upload recovery step. SDK: https://photoprintagent.com/sdk/photo-upload.mjs. No storage is allocated until upload. JPEG, PNG/APNG, WebP, GIF, HEIC/HEIF, TIFF, AVIF, BMP and self-contained SVG are supported. Read acceptedMimeTypes, acceptedExtensions and imageHandling for frame/page selection, transparency, and limits. Use application/octet-stream when MIME type is unavailable. Unsupported encodings must be converted before upload.
create_upload input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"default": 50,
"maximum": 100,
"minimum": 0
},
"y": {
"type": "number",
"default": 50,
"maximum": 100,
"minimum": 0
},
"fit": {
"enum": [
"cover",
"contain"
],
"type": "string",
"default": "cover"
},
"orientation": {
"enum": [
"landscape",
"portrait"
],
"type": "string",
"default": "landscape"
}
},
"additionalProperties": false
},
"productId": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}create_upload output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"uploadUrl",
"method",
"authorization",
"headers",
"acceptedMimeTypes",
"acceptedExtensions",
"imageHandling",
"maxFileBytes",
"maxInputPixels",
"helpUrl",
"responseSchemaUrl"
],
"properties": {
"method": {
"type": "string",
"const": "POST"
},
"artwork": {
"type": "object",
"required": [
"widthPixels",
"heightPixels",
"minImages",
"maxImages",
"minimumDpi",
"allowRotate",
"labels",
"bleed",
"issues"
],
"properties": {
"bleed": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"issues": {
"type": "array",
"items": {
"type": "string"
}
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"calendar": {
"type": "object",
"required": [
"layout",
"months"
],
"properties": {
"layout": {
"type": "string",
"const": "alternating-photo-grid"
},
"months": {
"enum": [
12,
18
],
"type": "number"
}
},
"additionalProperties": false
},
"maxImages": {
"type": "integer"
},
"minImages": {
"type": "integer"
},
"minimumDpi": {
"type": "number"
},
"allowRotate": {
"type": "boolean"
},
"composition": {
"type": "object",
"required": [
"id",
"width",
"height",
"background",
"slots"
],
"properties": {
"id": {
"type": "string"
},
"slots": {
"type": "array",
"items": {
"type": "object",
"required": [
"x",
"y",
"width",
"height"
],
"properties": {
"x": {
"type": "integer"
},
"y": {
"type": "integer"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"background": {
"type": "string"
}
},
"additionalProperties": false
},
"widthPixels": {
"type": "integer"
},
"heightPixels": {
"type": "integer"
},
"qualityGuidance": {
"type": "object",
"required": [
"recommendedDpi",
"minimumDpiIsRejectionThreshold",
"fitModes",
"fitDescription"
],
"properties": {
"fitModes": {
"type": "array",
"items": {
"type": "string"
}
},
"fitDescription": {
"type": "string"
},
"recommendedDpi": {
"type": "number"
},
"minimumDpiIsRejectionThreshold": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"headers": {
"type": "object",
"required": [
"X-Photo-Options"
],
"properties": {
"X-Product-Id": {
"type": "string"
},
"X-Photo-Options": {
"type": "string"
}
},
"additionalProperties": false
},
"helpUrl": {
"type": "string",
"format": "uri"
},
"uploadUrl": {
"type": "string",
"format": "uri"
},
"maxFileBytes": {
"type": "integer"
},
"authorization": {
"type": "string",
"const": "Bearer: use your existing account or guest credential"
},
"imageHandling": {
"type": "object",
"required": [
"resolutionPolicy",
"animationPolicy",
"multipagePolicy",
"transparencyPolicy",
"colorPolicy",
"svgPolicy",
"unsupportedPolicy",
"helpUrl"
],
"properties": {
"helpUrl": {
"type": "string"
},
"svgPolicy": {
"type": "string"
},
"colorPolicy": {
"type": "string"
},
"animationPolicy": {
"type": "string"
},
"multipagePolicy": {
"type": "string"
},
"resolutionPolicy": {
"type": "string"
},
"unsupportedPolicy": {
"type": "string"
},
"transparencyPolicy": {
"type": "string"
}
},
"additionalProperties": false
},
"maxInputPixels": {
"type": "integer"
},
"acceptedMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"responseSchemaUrl": {
"type": "string",
"format": "uri"
},
"acceptedExtensions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}create_upload annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}quote_prints — Quote Prints
Open-world
Quote private uploaded photo IDs and a US destination for an optional productId from list_products (defaults to photo-4x6). Items may specify productId to mix products using the same print service; omitted item productId uses the order productId. For a single image use items:[{photoId,productId,quantity}]. For a multi-image design use items:[{photoIds:[frontId,backId,...],quantity}]; array order is print order and quantity counts complete products, not individual images. Follow artwork.minImages/maxImages and labels. For artwork.calendar, upload a cover plus one photo per month and include calendar:{startYear,startMonth} on the item; the server generates and interleaves the date grids. Do not upload date grids. For artwork.composition, upload each source photo at the per-image dimensions; the server assembles the ordered photos into the single print file shown by the layout. Never precompose those photos or send each side as a separate item. Up to 200 uploaded images and 500 product units per order. Shipping follows the product’s configured pricing; flat rates can differ for 1 versus 2+ prints. Use the returned shipping and total; never multiply flat shipping by quantity. Requires consent for PhotoPrintAgent to process these photos and address for printing and delivery. Unique photos, at most 500 total prints. Optional couponCode is validated here; price.total is the discounted buyer amount and price.discount is the savings in USD cents.
quote_prints input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items",
"shipping",
"consent"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"quantity"
],
"properties": {
"photoId": {
"type": "string",
"format": "uuid"
},
"calendar": {
"type": "object",
"required": [
"startYear",
"startMonth"
],
"properties": {
"startYear": {
"type": "integer",
"maximum": 2100,
"minimum": 2000
},
"startMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1
}
},
"additionalProperties": false
},
"photoIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 200,
"minItems": 1
},
"quantity": {
"type": "integer",
"maximum": 99,
"minimum": 1
},
"productId": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
}
},
"additionalProperties": false
},
"maxItems": 50,
"minItems": 1
},
"consent": {
"type": "boolean",
"const": true
},
"shipping": {
"type": "object",
"required": [
"firstName",
"lastName",
"email",
"phone",
"line1",
"city",
"state",
"zip",
"country"
],
"properties": {
"zip": {
"type": "string",
"pattern": "^\\d{5}(-\\d{4})?$"
},
"city": {
"$ref": "#/properties/shipping/properties/firstName"
},
"email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"line1": {
"$ref": "#/properties/shipping/properties/firstName"
},
"line2": {
"type": "string",
"default": "",
"maxLength": 150
},
"phone": {
"type": "string"
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"country": {
"type": "string",
"const": "US"
},
"lastName": {
"$ref": "#/properties/shipping/properties/firstName"
},
"firstName": {
"type": "string",
"maxLength": 150,
"minLength": 1
}
},
"additionalProperties": false
},
"productId": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
},
"campaignId": {
"type": "string",
"pattern": "^[a-f0-9]{16}$"
},
"couponCode": {
"type": "string",
"maxLength": 64
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}quote_prints output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"price",
"validUntil",
"expiresAt",
"lineItems"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"expiresAt": {
"$ref": "#/properties/validUntil"
},
"lineItems": {
"type": "array",
"items": {
"type": "object",
"required": [
"productId",
"quantity"
],
"properties": {
"photoId": {
"type": "string",
"format": "uuid"
},
"calendar": {
"type": "object",
"required": [
"startYear",
"startMonth"
],
"properties": {
"startYear": {
"type": "integer",
"maximum": 2100,
"minimum": 2000
},
"startMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1
}
},
"additionalProperties": false
},
"photoIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"quantity": {
"type": "integer"
},
"productId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"validUntil": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
}
},
"additionalProperties": false
}quote_prints annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}create_print_order — Create Print Order
Open-world
Create one order from the approved quote, which already contains buyer contact and address. Requires termsAccepted:true confirming acceptance of https://photoprintagent.com/terms with the buyer’s authorization, separately from buyerApproved:true. Never infer acceptance from an upload, quote, or previous order. Reuse the same idempotency key for retries. Returns a buyer card checkout URL or x402 payment URL; call pay_print_order for the challenge. A zero-total coupon order is submitted with buyerApproved:true and needs no card or wallet. Optional couponCode must match the approved quote.
create_print_order input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"quoteId",
"idempotencyKey",
"buyerApproved",
"termsAccepted"
],
"properties": {
"method": {
"enum": [
"card",
"x402"
],
"type": "string",
"default": "x402"
},
"quoteId": {
"type": "string",
"format": "uuid"
},
"couponCode": {
"type": "string",
"maxLength": 64
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
},
"buyerApproved": {
"type": "boolean",
"const": true
},
"termsAccepted": {
"type": "boolean",
"const": true,
"description": "Required explicit acceptance of https://photoprintagent.com/terms for this order, with buyer authorization. Missing or false acceptance is rejected."
},
"idempotencyKey": {
"type": "string",
"pattern": "^[-\\w]{16,100}$"
}
},
"additionalProperties": false
}create_print_order output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"order",
"checkoutUrl"
],
"properties": {
"order": {
"type": "object",
"required": [
"id",
"status",
"method",
"price",
"pricingVersion",
"paymentDeadline",
"canEditCoupon",
"quantity",
"createdAt",
"paidAt",
"paymentStatus",
"fulfillmentStatus",
"cryptoPayment",
"transaction",
"network",
"trackingUrls",
"message"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/order/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/order/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"method": {
"enum": [
"card",
"x402"
],
"type": "string"
},
"paidAt": {
"anyOf": [
{
"$ref": "#/properties/order/properties/paymentDeadline"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
},
"status": {
"enum": [
"creating_checkout",
"awaiting_payment",
"verifying_payment",
"settling_payment",
"paid",
"submitting",
"processing",
"needs_review",
"expired"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"network": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"quantity": {
"type": "integer"
},
"createdAt": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"imageCount": {
"type": "integer"
},
"productName": {
"type": "string"
},
"transaction": {
"type": [
"string",
"null"
]
},
"trackingUrls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"canEditCoupon": {
"type": "boolean"
},
"cardProcessor": {
"anyOf": [
{
"enum": [
"square",
"stripe"
],
"type": "string"
},
{
"type": "null"
}
]
},
"cryptoPayment": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"priceAsOf": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"validUntil": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"paymentStatus": {
"enum": [
"unpaid",
"pending",
"paid",
"refunded",
"not_required",
"needs_review",
"expired"
],
"type": "string"
},
"cardPaymentUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"pricingVersion": {
"type": "integer",
"minimum": 0
},
"paymentDeadline": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"canRenewCheckout": {
"type": "boolean"
},
"fulfillmentStatus": {
"enum": [
"not_submitted",
"submitting",
"accepted",
"needs_review"
],
"type": "string"
}
},
"additionalProperties": false
},
"paymentUrl": {
"type": "string"
},
"checkoutUrl": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
}create_print_order annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}list_payment_assets — List Payment Assets
Advertised read-onlyOpen-world
Public: search Base ERC-20 and ready Solana SPL / compatible Token-2022 payment candidates by name, ticker or exact contract/mint. No market-cap limit. Results are paginated; pass nextOffset as offset. Call quote_crypto_payment to verify the token and obtain a fresh price. Solana needs the merchant receiving account initialized.
list_payment_assets input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 20000,
"minimum": 0
},
"search": {
"type": "string",
"default": "",
"maxLength": 100
},
"network": {
"enum": [
"eip155:8453",
"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
],
"type": "string"
}
},
"additionalProperties": false
}list_payment_assets output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"network",
"priceStatus",
"rankingSource",
"assets",
"networks",
"total",
"offset",
"nextOffset",
"solanaPayTo"
],
"properties": {
"total": {
"type": "integer"
},
"assets": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"rankId": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
}
},
"offset": {
"type": "integer"
},
"network": {
"type": "string"
},
"networks": {
"type": "array",
"items": {
"type": "string"
}
},
"nextOffset": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"priceStatus": {
"enum": [
"available",
"unavailable"
],
"type": "string"
},
"solanaPayTo": {
"type": [
"string",
"null"
]
},
"catalogStale": {
"type": "boolean"
},
"catalogSource": {
"enum": [
"bundled",
"refreshed"
],
"type": "string"
},
"rankingSource": {
"type": "string"
},
"catalogUpdatedAt": {
"type": "string"
}
},
"additionalProperties": false
}list_payment_assets annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}quote_crypto_payment — Quote Crypto Payment
Open-world
Lock an unpaid order in a listed token for up to 60 seconds. Obtain approval of this exact amount and include cryptoQuoteId in the payment retry.
quote_crypto_payment input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId",
"tokenId"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"tokenId": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}quote_crypto_payment output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/priceAsOf"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"priceAsOf": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"validUntil": {
"$ref": "#/properties/priceAsOf"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
}quote_crypto_payment annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}pay_print_order — Pay Print Order
Advertised destructiveOpen-world
Request an x402 v2 challenge without a signature, or settle an approved signature and submit the paid print. Uses the same guarded payment flow as REST. An unsigned call returns payment_required in structuredContent (MCP HTTP 200). Never repay an ambiguous order.
pay_print_order input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
},
"cryptoQuoteId": {
"type": "string",
"format": "uuid"
},
"paymentSignature": {
"type": "string",
"maxLength": 64000,
"minLength": 1,
"description": "Base64-encoded x402 v2 payload, same value as PAYMENT-SIGNATURE; never provide both."
}
},
"additionalProperties": false
}pay_print_order output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"status",
"httpStatus"
],
"properties": {
"order": {
"type": "object",
"required": [
"id",
"status",
"method",
"price",
"pricingVersion",
"paymentDeadline",
"canEditCoupon",
"quantity",
"createdAt",
"paidAt",
"paymentStatus",
"fulfillmentStatus",
"cryptoPayment",
"transaction",
"network",
"trackingUrls",
"message"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/order/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/order/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"method": {
"enum": [
"card",
"x402"
],
"type": "string"
},
"paidAt": {
"anyOf": [
{
"$ref": "#/properties/order/properties/paymentDeadline"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
},
"status": {
"enum": [
"creating_checkout",
"awaiting_payment",
"verifying_payment",
"settling_payment",
"paid",
"submitting",
"processing",
"needs_review",
"expired"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"network": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"quantity": {
"type": "integer"
},
"createdAt": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"imageCount": {
"type": "integer"
},
"productName": {
"type": "string"
},
"transaction": {
"type": [
"string",
"null"
]
},
"trackingUrls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"canEditCoupon": {
"type": "boolean"
},
"cardProcessor": {
"anyOf": [
{
"enum": [
"square",
"stripe"
],
"type": "string"
},
{
"type": "null"
}
]
},
"cryptoPayment": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"$ref": "#/properties/order/properties/price/properties/subtotal"
},
"priceAsOf": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"validUntil": {
"$ref": "#/properties/order/properties/paymentDeadline"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"paymentStatus": {
"enum": [
"unpaid",
"pending",
"paid",
"refunded",
"not_required",
"needs_review",
"expired"
],
"type": "string"
},
"cardPaymentUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"pricingVersion": {
"type": "integer",
"minimum": 0
},
"paymentDeadline": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"canRenewCheckout": {
"type": "boolean"
},
"fulfillmentStatus": {
"enum": [
"not_submitted",
"submitting",
"accepted",
"needs_review"
],
"type": "string"
}
},
"additionalProperties": false
},
"status": {
"enum": [
"payment_required",
"order_status"
],
"type": "string"
},
"httpStatus": {
"enum": [
200,
402
],
"type": "number"
},
"paymentResponse": {
"type": "object",
"required": [
"success",
"transaction",
"network"
],
"properties": {
"payer": {
"type": "string"
},
"network": {
"type": "string"
},
"success": {
"type": "boolean"
},
"errorReason": {
"type": "string"
},
"transaction": {
"type": "string"
}
},
"additionalProperties": true
},
"payment_required": {
"type": "object",
"required": [
"x402Version",
"resource",
"accepts"
],
"properties": {
"error": {
"type": "string"
},
"accepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"scheme",
"network",
"asset",
"amount",
"payTo",
"maxTimeoutSeconds"
],
"properties": {
"asset": {
"type": "string"
},
"extra": {
"type": "object",
"additionalProperties": {}
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"scheme": {
"type": "string",
"const": "exact"
},
"network": {
"type": "string"
},
"maxTimeoutSeconds": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"resource": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"mimeType": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
},
"extensions": {
"type": "object",
"additionalProperties": {}
},
"x402Version": {
"type": "number",
"const": 2
}
},
"additionalProperties": false
},
"paymentRequiredHeader": {
"type": "string"
},
"paymentResponseHeader": {
"type": "string"
}
},
"additionalProperties": false
}pay_print_order annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": true
}list_admin_products — List Admin Products
Advertised read-onlyOpen-world
List ready products including Admin Only products. Requires a verified allowlisted admin Firebase session; guest and agent keys cannot access private catalog products.
list_admin_products input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
}list_admin_products output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"products"
],
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"description",
"widthInches",
"heightInches"
],
"properties": {
"id": {
"type": "string"
},
"sku": {
"type": "string"
},
"size": {
"type": "string"
},
"title": {
"type": "string"
},
"finish": {
"type": "string"
},
"artwork": {
"type": "object",
"required": [
"widthPixels",
"heightPixels",
"minImages",
"maxImages",
"minimumDpi",
"allowRotate",
"labels",
"bleed",
"issues"
],
"properties": {
"bleed": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"issues": {
"type": "array",
"items": {
"type": "string"
}
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"calendar": {
"type": "object",
"required": [
"layout",
"months"
],
"properties": {
"layout": {
"type": "string",
"const": "alternating-photo-grid"
},
"months": {
"enum": [
12,
18
],
"type": "number"
}
},
"additionalProperties": false
},
"maxImages": {
"type": "integer"
},
"minImages": {
"type": "integer"
},
"minimumDpi": {
"type": "number"
},
"allowRotate": {
"type": "boolean"
},
"composition": {
"type": "object",
"required": [
"id",
"width",
"height",
"background",
"slots"
],
"properties": {
"id": {
"type": "string"
},
"slots": {
"type": "array",
"items": {
"type": "object",
"required": [
"x",
"y",
"width",
"height"
],
"properties": {
"x": {
"type": "integer"
},
"y": {
"type": "integer"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"background": {
"type": "string"
}
},
"additionalProperties": false
},
"widthPixels": {
"type": "integer"
},
"heightPixels": {
"type": "integer"
},
"qualityGuidance": {
"type": "object",
"required": [
"recommendedDpi",
"minimumDpiIsRejectionThreshold",
"fitModes",
"fitDescription"
],
"properties": {
"fitModes": {
"type": "array",
"items": {
"type": "string"
}
},
"fitDescription": {
"type": "string"
},
"recommendedDpi": {
"type": "number"
},
"minimumDpiIsRejectionThreshold": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"preview": {
"type": "object",
"additionalProperties": {}
},
"category": {
"type": "string"
},
"shipping": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"enum": [
"provider",
"flat",
"per_item"
],
"type": "string"
},
"amountCents": {
"type": "integer",
"default": 0,
"maximum": 100000,
"minimum": 0
},
"multipleItemAmountCents": {
"anyOf": [
{
"$ref": "#/properties/products/items/properties/shipping/properties/amountCents"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
"adminOnly": {
"type": "boolean"
},
"available": {
"type": "boolean"
},
"description": {
"type": "string"
},
"productCode": {
"type": "string",
"pattern": "^PPA[A-F0-9]{12}$"
},
"widthInches": {
"type": "number"
},
"heightInches": {
"type": "number"
},
"unitPriceCents": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
{
"type": "null"
}
],
"description": "Integer USD cents"
},
"unavailableReason": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": false
}list_admin_products annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}list_photos — List Photos
Advertised read-only
List your unexpired, unlocked uploaded photos. Use their IDs in slot order. Photos reserved by an order cannot be deleted.
list_photos input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}list_photos output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"photos"
],
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"productId",
"artworkKey",
"width",
"height",
"quality",
"orientation"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"quality": {
"anyOf": [
{
"enum": [
"high",
"reduced"
],
"type": "string"
},
{
"type": "null"
}
]
},
"productId": {
"type": "string"
},
"artworkKey": {
"type": "string"
},
"orientation": {
"enum": [
"portrait",
"landscape"
],
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}list_photos annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_photo — Get Photo
Advertised read-only
Get the private JPEG download endpoint for your uploaded photo. Send the same Bearer credential; this is not a public image URL.
get_photo input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"photoId"
],
"properties": {
"photoId": {
"type": "string",
"format": "uuid"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}get_photo output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url",
"method",
"mimeType",
"authorization"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"method": {
"type": "string",
"const": "GET"
},
"mimeType": {
"type": "string",
"const": "image/jpeg"
},
"authorization": {
"type": "string"
}
},
"additionalProperties": false
}get_photo annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}delete_photo — Delete Photo
Advertised destructive
Permanently delete one of your uploaded photos. Photos locked or reserved by an order cannot be deleted.
delete_photo input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"photoId"
],
"properties": {
"photoId": {
"type": "string",
"format": "uuid"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}delete_photo output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}delete_photo annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}preview_print_item — Preview Print Item
Advertised read-only
Preview one complete design using owned uploaded photoIds in product slot order. Reviewed compositions (including photobooth strips) render the same assembly used for fulfillment. For artwork.calendar, include calendar:{startYear,startMonth}; previews include the generated date grids in print page order. Other products return ordered flat artwork pages, not a physical mockup. JPEG thumbnails appear as MCP image content after the JSON metadata. Page with offset/limit; no order or external photo link is created.
preview_print_item input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"photoIds"
],
"properties": {
"limit": {
"type": "integer",
"default": 4,
"maximum": 4,
"minimum": 1
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0
},
"calendar": {
"type": "object",
"required": [
"startYear",
"startMonth"
],
"properties": {
"startYear": {
"type": "integer",
"maximum": 2100,
"minimum": 2000
},
"startMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1
}
},
"additionalProperties": false
},
"photoIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 200,
"minItems": 1
},
"productId": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}preview_print_item output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"productId",
"kind",
"layoutId",
"totalPages",
"nextOffset",
"pages"
],
"properties": {
"kind": {
"enum": [
"composition",
"artwork_pages",
"calendar"
],
"type": "string"
},
"pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"label",
"width",
"height"
],
"properties": {
"index": {
"type": "integer"
},
"label": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"layoutId": {
"type": [
"string",
"null"
]
},
"productId": {
"type": "string"
},
"nextOffset": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"totalPages": {
"type": "integer"
}
},
"additionalProperties": false
}preview_print_item annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}preview_print_price — Preview Print Price
Open-world
Estimate product and destination pricing before using the customer’s photos for an order. Uses placeholder artwork and does not create an order or a payable quote. Call quote_prints with buyer consent before checkout.
preview_print_price input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items",
"shipping"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"quantity"
],
"properties": {
"photoId": {
"type": "string",
"format": "uuid"
},
"calendar": {
"type": "object",
"required": [
"startYear",
"startMonth"
],
"properties": {
"startYear": {
"type": "integer",
"maximum": 2100,
"minimum": 2000
},
"startMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1
}
},
"additionalProperties": false
},
"photoIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 200,
"minItems": 1
},
"quantity": {
"type": "integer",
"maximum": 99,
"minimum": 1
},
"productId": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
}
},
"additionalProperties": false
},
"maxItems": 50,
"minItems": 1
},
"shipping": {
"type": "object",
"required": [
"firstName",
"lastName",
"email",
"phone",
"line1",
"city",
"state",
"zip",
"country"
],
"properties": {
"zip": {
"type": "string",
"pattern": "^\\d{5}(-\\d{4})?$"
},
"city": {
"$ref": "#/properties/shipping/properties/firstName"
},
"email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"line1": {
"$ref": "#/properties/shipping/properties/firstName"
},
"line2": {
"type": "string",
"default": "",
"maxLength": 150
},
"phone": {
"type": "string"
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"country": {
"type": "string",
"const": "US"
},
"lastName": {
"$ref": "#/properties/shipping/properties/firstName"
},
"firstName": {
"type": "string",
"maxLength": 150,
"minLength": 1
}
},
"additionalProperties": false
},
"productId": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
},
"campaignId": {
"type": "string",
"pattern": "^[a-f0-9]{16}$"
},
"couponCode": {
"type": "string",
"maxLength": 64
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}preview_print_price output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"preview",
"price",
"validUntil",
"expiresAt",
"lineItems"
],
"properties": {
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"preview": {
"type": "boolean",
"const": true
},
"expiresAt": {
"$ref": "#/properties/validUntil"
},
"lineItems": {
"type": "array",
"items": {
"type": "object",
"required": [
"productId",
"quantity"
],
"properties": {
"photoId": {
"type": "string",
"format": "uuid"
},
"calendar": {
"type": "object",
"required": [
"startYear",
"startMonth"
],
"properties": {
"startYear": {
"type": "integer",
"maximum": 2100,
"minimum": 2000
},
"startMonth": {
"type": "integer",
"maximum": 12,
"minimum": 1
}
},
"additionalProperties": false
},
"photoIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"quantity": {
"type": "integer"
},
"productId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"validUntil": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
}
},
"additionalProperties": false
}preview_print_price annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}list_orders — List Orders
Advertised read-only
List your most recent orders, newest first, up to 50. Does not reconcile payments; use get_order for a specific order. Unpaid Admin Only orders require a verified admin session.
list_orders input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 50,
"minimum": 1
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}list_orders output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orders"
],
"properties": {
"orders": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status",
"method",
"price",
"pricingVersion",
"paymentDeadline",
"canEditCoupon",
"quantity",
"createdAt",
"paidAt",
"paymentStatus",
"fulfillmentStatus",
"cryptoPayment",
"transaction",
"network",
"trackingUrls",
"message"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"method": {
"enum": [
"card",
"x402"
],
"type": "string"
},
"paidAt": {
"anyOf": [
{
"$ref": "#/properties/orders/items/properties/paymentDeadline"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
},
"status": {
"enum": [
"creating_checkout",
"awaiting_payment",
"verifying_payment",
"settling_payment",
"paid",
"submitting",
"processing",
"needs_review",
"expired"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"network": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"quantity": {
"type": "integer"
},
"createdAt": {
"$ref": "#/properties/orders/items/properties/paymentDeadline"
},
"imageCount": {
"type": "integer"
},
"productName": {
"type": "string"
},
"transaction": {
"type": [
"string",
"null"
]
},
"trackingUrls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"canEditCoupon": {
"type": "boolean"
},
"cardProcessor": {
"anyOf": [
{
"enum": [
"square",
"stripe"
],
"type": "string"
},
{
"type": "null"
}
]
},
"cryptoPayment": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/orders/items/properties/paymentDeadline"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"$ref": "#/properties/orders/items/properties/price/properties/subtotal"
},
"priceAsOf": {
"$ref": "#/properties/orders/items/properties/paymentDeadline"
},
"validUntil": {
"$ref": "#/properties/orders/items/properties/paymentDeadline"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"paymentStatus": {
"enum": [
"unpaid",
"pending",
"paid",
"refunded",
"not_required",
"needs_review",
"expired"
],
"type": "string"
},
"cardPaymentUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"pricingVersion": {
"type": "integer",
"minimum": 0
},
"paymentDeadline": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"canRenewCheckout": {
"type": "boolean"
},
"fulfillmentStatus": {
"enum": [
"not_submitted",
"submitting",
"accepted",
"needs_review"
],
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}list_orders annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_checkout_link — Get Checkout Link
Open-world
Mint a private on-site checkout link for your existing order. Preserve its access fragment, share only with the buyer, and never create another order to recover a checkout. Card payment uses the embedded payment modal; MCP never accepts card details.
get_checkout_link input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}get_checkout_link output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"checkoutUrl"
],
"properties": {
"checkoutUrl": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
}get_checkout_link annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}update_order_coupon — Update Order Coupon
Open-world
Apply or remove a coupon on your eligible unpaid x402 order; empty couponCode removes it. Check canEditCoupon first. Returns the revised price and pricingVersion, invalidates old crypto quotes, and never requests payment. Obtain approval of the new total before paying. Card or ambiguous payments cannot be changed.
update_order_coupon input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId",
"couponCode"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"couponCode": {
"type": "string",
"maxLength": 64
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}update_order_coupon output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"status",
"method",
"price",
"pricingVersion",
"paymentDeadline",
"canEditCoupon",
"quantity",
"createdAt",
"paidAt",
"paymentStatus",
"fulfillmentStatus",
"cryptoPayment",
"transaction",
"network",
"trackingUrls",
"message"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"method": {
"enum": [
"card",
"x402"
],
"type": "string"
},
"paidAt": {
"anyOf": [
{
"$ref": "#/properties/paymentDeadline"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
},
"status": {
"enum": [
"creating_checkout",
"awaiting_payment",
"verifying_payment",
"settling_payment",
"paid",
"submitting",
"processing",
"needs_review",
"expired"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"network": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"quantity": {
"type": "integer"
},
"createdAt": {
"$ref": "#/properties/paymentDeadline"
},
"imageCount": {
"type": "integer"
},
"productName": {
"type": "string"
},
"transaction": {
"type": [
"string",
"null"
]
},
"trackingUrls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"canEditCoupon": {
"type": "boolean"
},
"cardProcessor": {
"anyOf": [
{
"enum": [
"square",
"stripe"
],
"type": "string"
},
{
"type": "null"
}
]
},
"cryptoPayment": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/paymentDeadline"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"$ref": "#/properties/price/properties/subtotal"
},
"priceAsOf": {
"$ref": "#/properties/paymentDeadline"
},
"validUntil": {
"$ref": "#/properties/paymentDeadline"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"paymentStatus": {
"enum": [
"unpaid",
"pending",
"paid",
"refunded",
"not_required",
"needs_review",
"expired"
],
"type": "string"
},
"cardPaymentUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"pricingVersion": {
"type": "integer",
"minimum": 0
},
"paymentDeadline": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"canRenewCheckout": {
"type": "boolean"
},
"fulfillmentStatus": {
"enum": [
"not_submitted",
"submitting",
"accepted",
"needs_review"
],
"type": "string"
}
},
"additionalProperties": false
}update_order_coupon annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}confirm_complimentary_order — Confirm Complimentary Order
Advertised destructiveOpen-world
Explicitly approve fulfillment of your existing zero-total order after a coupon change. Requires buyerApproved:true and the current pricingVersion. Original order terms consent remains required. Idempotent for an already confirmed complimentary order; never use this for a positive total.
confirm_complimentary_order input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId",
"buyerApproved",
"pricingVersion"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
},
"buyerApproved": {
"type": "boolean",
"const": true
},
"pricingVersion": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}confirm_complimentary_order output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"status",
"method",
"price",
"pricingVersion",
"paymentDeadline",
"canEditCoupon",
"quantity",
"createdAt",
"paidAt",
"paymentStatus",
"fulfillmentStatus",
"cryptoPayment",
"transaction",
"network",
"trackingUrls",
"message"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"method": {
"enum": [
"card",
"x402"
],
"type": "string"
},
"paidAt": {
"anyOf": [
{
"$ref": "#/properties/paymentDeadline"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
},
"status": {
"enum": [
"creating_checkout",
"awaiting_payment",
"verifying_payment",
"settling_payment",
"paid",
"submitting",
"processing",
"needs_review",
"expired"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"network": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"quantity": {
"type": "integer"
},
"createdAt": {
"$ref": "#/properties/paymentDeadline"
},
"imageCount": {
"type": "integer"
},
"productName": {
"type": "string"
},
"transaction": {
"type": [
"string",
"null"
]
},
"trackingUrls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"canEditCoupon": {
"type": "boolean"
},
"cardProcessor": {
"anyOf": [
{
"enum": [
"square",
"stripe"
],
"type": "string"
},
{
"type": "null"
}
]
},
"cryptoPayment": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/paymentDeadline"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"$ref": "#/properties/price/properties/subtotal"
},
"priceAsOf": {
"$ref": "#/properties/paymentDeadline"
},
"validUntil": {
"$ref": "#/properties/paymentDeadline"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"paymentStatus": {
"enum": [
"unpaid",
"pending",
"paid",
"refunded",
"not_required",
"needs_review",
"expired"
],
"type": "string"
},
"cardPaymentUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"pricingVersion": {
"type": "integer",
"minimum": 0
},
"paymentDeadline": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"canRenewCheckout": {
"type": "boolean"
},
"fulfillmentStatus": {
"enum": [
"not_submitted",
"submitting",
"accepted",
"needs_review"
],
"type": "string"
}
},
"additionalProperties": false
}confirm_complimentary_order annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": true
}list_agent_keys — List Agent Keys
Advertised read-only
List your account key IDs and expiry/revocation status, never their secrets. Requires a verified Firebase account session; guest and agent keys cannot manage keys.
list_agent_keys input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
}list_agent_keys output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"keys"
],
"properties": {
"keys": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"createdAt",
"expiresAt",
"revoked"
],
"properties": {
"id": {
"type": "string"
},
"revoked": {
"type": "boolean"
},
"createdAt": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"expiresAt": {
"$ref": "#/properties/keys/items/properties/createdAt"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}list_agent_keys annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}revoke_agent_key — Revoke Agent Key
Advertised destructive
Revoke one of your account keys by ID. Requires a verified Firebase account session; guest and agent keys cannot manage keys.
revoke_agent_key input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
}
},
"additionalProperties": false
}revoke_agent_key output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}revoke_agent_key annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}get_order — Get Order
Open-world
Read your private order. Payment and fulfillment states are separate; processing means PhotoPrintAgent accepted the order for processing, not shipped. Use only PhotoPrintAgent branding and the returned customer status in updates. Does not initiate charges. Polling verifies a completed card checkout only with payment permission or a full guest/account credential. Read-only OAuth returns saved status without reconciliation.
get_order input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}get_order output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"status",
"method",
"price",
"pricingVersion",
"paymentDeadline",
"canEditCoupon",
"quantity",
"createdAt",
"paidAt",
"paymentStatus",
"fulfillmentStatus",
"cryptoPayment",
"transaction",
"network",
"trackingUrls",
"message"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"price": {
"type": "object",
"required": [
"currency",
"subtotal",
"shipping",
"tax",
"total"
],
"properties": {
"tax": {
"$ref": "#/properties/price/properties/subtotal"
},
"total": {
"$ref": "#/properties/price/properties/subtotal"
},
"coupon": {
"type": "object",
"required": [
"code",
"name",
"printDiscount",
"shippingDiscount",
"taxCredit"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"taxCredit": {
"$ref": "#/properties/price/properties/subtotal"
},
"printDiscount": {
"$ref": "#/properties/price/properties/subtotal"
},
"shippingDiscount": {
"$ref": "#/properties/price/properties/subtotal"
}
},
"additionalProperties": false
},
"currency": {
"type": "string",
"const": "USD"
},
"discount": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
},
"shipping": {
"$ref": "#/properties/price/properties/subtotal"
},
"subtotal": {
"type": "integer",
"minimum": 0,
"description": "Integer USD cents"
},
"originalTotal": {
"$ref": "#/properties/price/properties/subtotal",
"description": "Integer USD cents"
}
},
"additionalProperties": false
},
"method": {
"enum": [
"card",
"x402"
],
"type": "string"
},
"paidAt": {
"anyOf": [
{
"$ref": "#/properties/paymentDeadline"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
},
"status": {
"enum": [
"creating_checkout",
"awaiting_payment",
"verifying_payment",
"settling_payment",
"paid",
"submitting",
"processing",
"needs_review",
"expired"
],
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"network": {
"type": [
"string",
"null"
]
},
"progress": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"quantity": {
"type": "integer"
},
"createdAt": {
"$ref": "#/properties/paymentDeadline"
},
"imageCount": {
"type": "integer"
},
"productName": {
"type": "string"
},
"transaction": {
"type": [
"string",
"null"
]
},
"trackingUrls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"canEditCoupon": {
"type": "boolean"
},
"cardProcessor": {
"anyOf": [
{
"enum": [
"square",
"stripe"
],
"type": "string"
},
{
"type": "null"
}
]
},
"cryptoPayment": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"rankId",
"name",
"symbol",
"asset",
"decimals",
"transferMethod",
"network",
"tokenId",
"amount",
"displayAmount",
"usdTotal",
"usdPrice",
"priceAsOf",
"source",
"payTo",
"quotedAt",
"validUntil"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"rank": {
"type": [
"number",
"null"
]
},
"asset": {
"type": "string"
},
"payTo": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^\\d+$"
},
"rankId": {
"type": "string"
},
"source": {
"type": "string"
},
"stable": {
"type": "boolean"
},
"symbol": {
"type": "string"
},
"network": {
"type": "string"
},
"tokenId": {
"type": "string"
},
"wrapped": {
"type": "boolean"
},
"decimals": {
"type": "integer"
},
"quotedAt": {
"$ref": "#/properties/paymentDeadline"
},
"usdPrice": {
"type": "string"
},
"usdTotal": {
"$ref": "#/properties/price/properties/subtotal"
},
"priceAsOf": {
"$ref": "#/properties/paymentDeadline"
},
"validUntil": {
"$ref": "#/properties/paymentDeadline"
},
"availability": {
"enum": [
"quote_required",
"receiving_ready"
],
"type": "string"
},
"priceChecked": {
"type": "boolean"
},
"tokenProgram": {
"type": "string"
},
"displayAmount": {
"type": "string"
},
"transferMethod": {
"enum": [
"eip3009",
"permit2",
"spl"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"paymentStatus": {
"enum": [
"unpaid",
"pending",
"paid",
"refunded",
"not_required",
"needs_review",
"expired"
],
"type": "string"
},
"cardPaymentUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"pricingVersion": {
"type": "integer",
"minimum": 0
},
"paymentDeadline": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"canRenewCheckout": {
"type": "boolean"
},
"fulfillmentStatus": {
"enum": [
"not_submitted",
"submitting",
"accepted",
"needs_review"
],
"type": "string"
}
},
"additionalProperties": false
}get_order annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}estimate_print_price — Estimate Print Price
Advertised read-onlyOpen-world
Estimate configured product and shipping charges using only product, quantity, ZIP and state. No photos or contact details required. Unknown tax or charges remain null; this is not a payable quote.
estimate_print_price input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"productId",
"quantity",
"zip",
"state"
],
"properties": {
"zip": {
"type": "string",
"pattern": "^\\d{5}$"
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"quantity": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"productId": {
"type": "string",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}estimate_print_price output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"estimate",
"currency",
"productId",
"quantity",
"subtotal",
"shipping",
"tax",
"total",
"knownAmount",
"unknownComponents",
"requiresFinalQuote",
"message"
],
"properties": {
"tax": {
"type": [
"number",
"null"
]
},
"total": {
"type": [
"number",
"null"
]
},
"message": {
"type": "string"
},
"currency": {
"type": "string",
"const": "USD"
},
"estimate": {
"type": "boolean",
"const": true
},
"quantity": {
"type": "number"
},
"shipping": {
"type": [
"number",
"null"
]
},
"subtotal": {
"type": [
"number",
"null"
]
},
"productId": {
"type": "string"
},
"knownAmount": {
"type": "number"
},
"unknownComponents": {
"type": "array",
"items": {
"type": "string"
}
},
"requiresFinalQuote": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}estimate_print_price annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}get_order_events — Get Order Events
Advertised read-onlyOpen-world
Read your customer-safe order events in sequence. Save the last sequence as after for incremental recovery; duplicate events must be deduplicated by orderId and sequence.
get_order_events input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId"
],
"properties": {
"after": {
"type": "integer",
"default": 0,
"minimum": 0
},
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}get_order_events output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"events",
"nextCursor"
],
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"orderId",
"sequence",
"type",
"occurredAt",
"data"
],
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"productionStatus",
"shipmentStatus",
"lastUpdatedAt",
"trackingUrls",
"supportStatus",
"canRequestCancellation",
"canRequestChange",
"canRequestRefund",
"cancellationGuaranteed",
"paymentStatus"
],
"properties": {
"trackingUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"lastUpdatedAt": {
"type": [
"number",
"null"
]
},
"paymentStatus": {
"enum": [
"refunded",
"not_required",
"paid",
"unpaid"
],
"type": "string"
},
"supportStatus": {
"enum": [
"none",
"open",
"waiting_customer",
"under_review",
"resolved"
],
"type": "string"
},
"shipmentStatus": {
"enum": [
"unknown",
"shipped",
"delivered"
],
"type": "string"
},
"canRequestChange": {
"type": "boolean"
},
"canRequestRefund": {
"type": "boolean"
},
"productionStatus": {
"enum": [
"not_submitted",
"queued",
"submitting",
"accepted",
"printing",
"shipped",
"delivered",
"cancelled",
"on_hold",
"needs_review",
"unknown"
],
"type": "string"
},
"canRequestCancellation": {
"type": "boolean"
},
"cancellationGuaranteed": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"type": {
"type": "string",
"const": "order.updated"
},
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"sequence": {
"type": "integer"
},
"occurredAt": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
}
},
"additionalProperties": false
}
},
"nextCursor": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}get_order_events annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}request_order_help — Request Order Help
Open-world
Create an order-bound support, address-change, cancellation or refund REQUEST. Requires buyer authorization. No cancellation, refund or change is executed or guaranteed. Reuse idempotencyKey when retrying the same request; read progress capability flags first.
request_order_help input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId",
"type",
"message",
"idempotencyKey"
],
"properties": {
"type": {
"enum": [
"general",
"address",
"cancellation",
"refund",
"damaged_prints",
"late_delivery"
],
"type": "string"
},
"message": {
"type": "string",
"maxLength": 2000,
"minLength": 10
},
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
},
"idempotencyKey": {
"type": "string",
"pattern": "^[\\w-]{16,100}$"
}
},
"additionalProperties": false
}request_order_help output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reference",
"status",
"type",
"createdAt",
"message"
],
"properties": {
"type": {
"type": "string"
},
"status": {
"type": "string",
"const": "requested"
},
"message": {
"type": "string"
},
"createdAt": {
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
"reference": {
"type": "string"
}
},
"additionalProperties": false
}request_order_help annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}subscribe_order_events — Subscribe Order Events
Open-world
Subscribe an owned order to an HTTPS webhook you control. Requires permission to send this order status to that endpoint. Returns a signing secret once. At-least-once delivery; verify timestamp/signature and deduplicate orderId + sequence. Repeated failures pause delivery; use event history for recovery.
subscribe_order_events input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2000
},
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}subscribe_order_events output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"secret",
"url",
"orderId",
"signature",
"message"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"secret": {
"type": "string"
},
"message": {
"type": "string"
},
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"signature": {
"type": "string"
}
},
"additionalProperties": false
}subscribe_order_events annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}list_order_subscriptions — List Order Subscriptions
Advertised read-onlyOpen-world
List your webhook destinations and delivery status for an owned order. Signing secrets are never returned.
list_order_subscriptions input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"orderId"
],
"properties": {
"orderId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
}
},
"additionalProperties": false
}list_order_subscriptions output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"subscriptions"
],
"properties": {
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"url",
"active",
"cursor",
"deliveryStatus",
"lastDeliveredAt"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"active": {
"type": "boolean"
},
"cursor": {
"type": "number"
},
"deliveryStatus": {
"type": "string"
},
"lastDeliveredAt": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Unix time in milliseconds"
},
{
"type": "null"
}
],
"description": "Unix time in milliseconds"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}list_order_subscriptions annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}replay_order_events — Replay Order Events
Open-world
Resume a failed subscription or replay events after a saved sequence. Requires authorization to resend order status to the registered destination; no payments or orders are repeated.
replay_order_events input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"subscriptionId"
],
"properties": {
"after": {
"type": "integer",
"default": 0,
"minimum": 0
},
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
},
"subscriptionId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
}
},
"additionalProperties": false
}replay_order_events output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}replay_order_events annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}unsubscribe_order_events — Unsubscribe Order Events
Open-world
Disable one of your webhook subscriptions and erase its signing secret.
unsubscribe_order_events input schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"subscriptionId"
],
"properties": {
"guestToken": {
"type": "string",
"pattern": "^ppg_[a-f0-9]{64}$",
"description": "Private guest credential; omit when Authorization Bearer is present."
},
"subscriptionId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
}
},
"additionalProperties": false
}unsubscribe_order_events output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}unsubscribe_order_events annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}Prompts
Not advertised
Resources
Not advertised
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 596 ms
- 95th percentile latency
- 596 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 596 ms · metadata changed · 30 tool(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http photoprintagent-mcp https://photoprintagent.com/mcpCodex
Codex configuration
codex mcp add photoprintagent-mcp --url https://photoprintagent.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"photoprintagent-mcp": {
"url": "https://photoprintagent.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"photoprintagent-mcp": {
"type": "streamableHttp",
"url": "https://photoprintagent.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"photoprintagent-mcp": {
"type": "http",
"url": "https://photoprintagent.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http photoprintagent-mcp https://photoprintagent.com/mcpClaude Desktop
Claude Desktop configuration
{
"mcpServers": {
"photoprintagent-mcp": {
"url": "https://photoprintagent.com/mcp"
}
}
}Windsurf
Windsurf configuration
{
"mcpServers": {
"photoprintagent-mcp": {
"serverUrl": "https://photoprintagent.com/mcp"
}
}
}Let your agent find its tools
Find servers like PhotoPrintAgent MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.
Other commerce servers
Do you run PhotoPrintAgent MCP?
Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.