AgentMade Print on Demand

Use this when the user wants their own picture, words or logo printed on a T-shirt, hoodie, sweatshirt or tote bag and delivered, as a gift or for themselves. Finds products by free text, category, colour and size. Returns product_id, image_url (a product photo, or null), colours, sizes and print placements. No account needed. Not for mugs, posters, caps, stickers or embroidery.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text description, e.g. \"heavyweight black t-shirt\" or \"hoodie\".",
      "type": "string",
      "maxLength": 200
    },
    "category": {
      "type": "string",
      "enum": [
        "t-shirt",
        "long-sleeve",
        "sweatshirt",
        "hoodie",
        "tote-bag"
      ]
    },
    "color": {
      "description": "Only products available in this colour, e.g. \"black\".",
      "type": "string"
    },
    "size": {
      "description": "Only products available in this size, e.g. \"XL\".",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "description": "Use in get_product, validate_artwork and quote."
          },
          "title": {
            "type": "string"
          },
          "image_url": {
            "description": "A product photo, or null when none is approved yet.",
            "type": [
              "string",
              "null"
            ]
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "model": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "decoration_method": {
            "type": "string"
          },
          "colors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Colour ids to pass as color."
          },
          "sizes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Size values to pass as size."
          },
          "placements": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Placement ids to pass as placement."
          },
          "printed_in_regions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Regions where this product is printed, e.g. [\"EU\", \"US\"]."
          },
          "production_business_days": {
            "type": "object",
            "properties": {
              "min": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "max": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "min",
              "max"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "product_id",
          "title",
          "image_url",
          "brand",
          "model",
          "category",
          "description",
          "decoration_method",
          "colors",
          "sizes",
          "placements",
          "printed_in_regions",
          "production_business_days"
        ],
        "additionalProperties": {}
      }
    },
    "count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "products",
    "count",
    "note"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Full details for one product: colours with hex codes and product photos (images: url, view, style, alt; empty when none yet; ai_generated marks AI photos), sizes, variant ids, print placements with the print area in mm, placement presets (for example center_chest, left_chest, full_front, full_back), materials and artwork guidance.

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product id from search_products, e.g. \"tee-heavyweight\"."
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Use in get_product, validate_artwork and quote."
    },
    "title": {
      "type": "string"
    },
    "image_url": {
      "description": "A product photo, or null when none is approved yet.",
      "type": [
        "string",
        "null"
      ]
    },
    "brand": {
      "type": [
        "string",
        "null"
      ]
    },
    "model": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "decoration_method": {
      "type": "string"
    },
    "colors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "hex": {
            "type": "string"
          },
          "printed_in_regions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Regions where this product is printed, e.g. [\"EU\", \"US\"]."
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "view": {
                  "type": "string"
                },
                "style": {
                  "type": "string"
                },
                "alt": {
                  "type": "string"
                },
                "ai_generated": {
                  "type": "boolean",
                  "description": "True for an AI-made photo. Say so when you show it."
                }
              },
              "required": [
                "url",
                "view",
                "style",
                "alt",
                "ai_generated"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "id",
          "name",
          "hex",
          "printed_in_regions",
          "images"
        ],
        "additionalProperties": {}
      }
    },
    "sizes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Size values to pass as size."
    },
    "placements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "print_area_mm": {
            "type": "object",
            "properties": {
              "width": {
                "type": "number"
              },
              "height": {
                "type": "number"
              }
            },
            "required": [
              "width",
              "height"
            ],
            "additionalProperties": {}
          },
          "safe_margin_mm": {
            "type": "number"
          },
          "default_preset": {
            "type": "string"
          },
          "presets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "max_width_mm": {
                  "type": "number"
                },
                "max_height_mm": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "top_mm": {
                  "type": "number"
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "max_width_mm",
                "top_mm"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "id",
          "name",
          "print_area_mm",
          "safe_margin_mm",
          "default_preset",
          "presets"
        ],
        "additionalProperties": {}
      }
    },
    "printed_in_regions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Regions where this product is printed, e.g. [\"EU\", \"US\"]."
    },
    "production_business_days": {
      "type": "object",
      "properties": {
        "min": {
          "type": [
            "number",
            "null"
          ]
        },
        "max": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": {}
    },
    "size_chart_cm": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "additionalProperties": {}
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "size": {
            "type": "string"
          }
        },
        "required": [
          "variant_id",
          "color",
          "size"
        ],
        "additionalProperties": {}
      }
    },
    "artwork_guidance": {
      "type": "string"
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    }
  },
  "required": [
    "product_id",
    "title",
    "image_url",
    "brand",
    "model",
    "category",
    "description",
    "decoration_method",
    "colors",
    "sizes",
    "placements",
    "printed_in_regions",
    "production_business_days",
    "size_chart_cm",
    "variants",
    "artwork_guidance",
    "next_step"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Upload artwork and check that it prints well on one product placement. Send exactly one of: artwork with svg (markup, best for text and logos), base64 (a PNG, JPEG or SVG file up to about 2 MB, no data: prefix) or url (a public HTTPS link to the file); file (a file object from your client); or upload_link:true when you cannot send the file in this call. Returns artwork_id and PASS/WARN/FAIL checks: print size in mm, resolution (DPI), print and safe area, transparent background, contrast with the product colour. For photos and AI images use preset center_chest. Use the artwork_id in quote.

{
  "type": "object",
  "properties": {
    "artwork": {
      "description": "New artwork to upload: exactly one of svg, base64 or url.",
      "type": "object",
      "properties": {
        "svg": {
          "description": "Inline SVG markup. Best for logos and text.",
          "type": "string",
          "minLength": 1
        },
        "base64": {
          "description": "Base64-encoded PNG, JPEG or SVG file contents, no data: prefix. Only for files up to about 2 MB; for larger files use url, file or upload_link.",
          "type": "string",
          "minLength": 1
        },
        "url": {
          "description": "Public HTTPS URL of a PNG, JPEG or SVG file.",
          "type": "string",
          "format": "uri"
        },
        "filename": {
          "type": "string",
          "maxLength": 200
        }
      }
    },
    "artwork_id": {
      "description": "Re-validate artwork uploaded earlier, or validate the file of an upload link.",
      "type": "string"
    },
    "file": {
      "description": "A file that your client gives you as a file object (for example in ChatGPT).",
      "type": "object",
      "properties": {
        "download_url": {
          "type": "string",
          "format": "uri",
          "description": "Temporary HTTPS link to the file."
        },
        "file_id": {
          "type": "string",
          "description": "Client file id."
        },
        "mime_type": {
          "type": "string"
        },
        "file_name": {
          "type": "string"
        }
      },
      "required": [
        "download_url",
        "file_id"
      ]
    },
    "upload_link": {
      "description": "Set true when you cannot send the file in this call. The answer gives an artwork_id and a one-time upload_url: upload with curl, or give the link to the person. Then call validate_artwork with the artwork_id.",
      "type": "boolean",
      "const": true
    },
    "product_id": {
      "type": "string",
      "description": "Product to print on."
    },
    "color": {
      "description": "Product colour, for the contrast check.",
      "type": "string"
    },
    "size": {
      "description": "Garment size, e.g. \"XL\". Print areas can differ by size; without it the smallest size is checked.",
      "type": "string"
    },
    "placement": {
      "default": "front",
      "description": "Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.",
      "type": "string"
    },
    "preset": {
      "description": "Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.",
      "type": "string"
    },
    "width_mm": {
      "description": "Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "height_mm": {
      "description": "Maximum printed height in millimetres.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "top_mm": {
      "description": "Distance from the top of the print area to the top of the artwork.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    },
    "left_mm": {
      "description": "Distance from the left edge of the print area. Default: horizontally centred.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "artwork_id": {
      "description": "Only in the upload_link answer: the reserved id for the file.",
      "type": "string"
    },
    "upload_url": {
      "description": "Only in the upload_link answer: the one-time upload link.",
      "type": "string"
    },
    "expires_at": {
      "type": "string"
    },
    "artwork": {
      "type": "object",
      "properties": {
        "artwork_id": {
          "type": "string",
          "description": "Use in quote and create_mockup."
        },
        "format": {
          "type": "string"
        },
        "width_px": {
          "type": "number"
        },
        "height_px": {
          "type": "number"
        },
        "transparent_background": {
          "type": "boolean"
        }
      },
      "required": [
        "artwork_id",
        "format",
        "width_px",
        "height_px",
        "transparent_background"
      ],
      "additionalProperties": {}
    },
    "validation": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "PASS",
            "WARN",
            "FAIL"
          ],
          "description": "PASS: prints well. WARN: tell the user, then continue if they agree. FAIL: fix the artwork, then validate again."
        },
        "placement": {
          "type": "string"
        },
        "preset": {
          "type": [
            "string",
            "null"
          ]
        },
        "print_box": {
          "type": "object",
          "properties": {
            "left_mm": {
              "type": "number"
            },
            "top_mm": {
              "type": "number"
            },
            "width_mm": {
              "type": "number"
            },
            "height_mm": {
              "type": "number"
            }
          },
          "required": [
            "left_mm",
            "top_mm",
            "width_mm",
            "height_mm"
          ],
          "additionalProperties": {},
          "description": "Position and size of the printed artwork inside the print area, in mm."
        },
        "print_area_mm": {
          "type": "object",
          "properties": {
            "width": {
              "type": "number"
            },
            "height": {
              "type": "number"
            }
          },
          "required": [
            "width",
            "height"
          ],
          "additionalProperties": {}
        },
        "effective_dpi": {
          "description": "Resolution at the printed size. Null for vector artwork.",
          "type": [
            "number",
            "null"
          ]
        },
        "checks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "PASS",
                  "WARN",
                  "FAIL"
                ]
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "status",
              "message"
            ],
            "additionalProperties": {}
          }
        },
        "summary": {
          "type": "string",
          "description": "Status and the checks in short lines; relay the gist to the user."
        }
      },
      "required": [
        "status",
        "placement",
        "preset",
        "print_box",
        "print_area_mm",
        "effective_dpi",
        "checks",
        "summary"
      ],
      "additionalProperties": {}
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    }
  },
  "required": [
    "next_step"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Render a preview PNG of the artwork on the product in the chosen colour and placement. style flat draws the placement; style packshot uses a product photo with the exact print at real size, or gives the flat preview with a note when no photo exists. Returns mockup_url, blank_image_url and image_prompt (an optional text prompt for an illustration of a person who wears the product; such an image is an illustration, not the exact print). Optional.

{
  "type": "object",
  "properties": {
    "artwork_id": {
      "type": "string"
    },
    "product_id": {
      "type": "string"
    },
    "color": {
      "type": "string",
      "description": "Product colour, e.g. \"black\"."
    },
    "size": {
      "type": "string"
    },
    "style": {
      "default": "flat",
      "description": "flat: quick placement drawing. packshot: product photo with the exact print at real size (where a product photo exists).",
      "type": "string",
      "enum": [
        "flat",
        "packshot"
      ]
    },
    "placement": {
      "default": "front",
      "description": "Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.",
      "type": "string"
    },
    "preset": {
      "description": "Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.",
      "type": "string"
    },
    "width_mm": {
      "description": "Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "height_mm": {
      "description": "Maximum printed height in millimetres.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "top_mm": {
      "description": "Distance from the top of the print area to the top of the artwork.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    },
    "left_mm": {
      "description": "Distance from the left edge of the print area. Default: horizontally centred.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    }
  },
  "required": [
    "artwork_id",
    "product_id",
    "color"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "mockup_url": {
      "type": "string",
      "description": "PNG preview of the exact print on the product."
    },
    "style": {
      "type": "string",
      "enum": [
        "flat",
        "packshot"
      ]
    },
    "blank_image_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "PASS",
        "WARN",
        "FAIL"
      ]
    },
    "summary": {
      "type": "string"
    },
    "image_prompt": {
      "type": "string",
      "description": "A prompt for your own image model, to make an illustration from mockup_url."
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "mockup_url",
    "style",
    "blank_image_url",
    "validation_status",
    "summary",
    "image_prompt",
    "note"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Price printed items delivered to one destination. Returns quote_id, the total that the payer pays (products, shipping and VAT where AgentMade collects it), what is not included, the delivery estimate and the expiry. Needs artwork_id values from validate_artwork. Charges nothing. For a destination where orders are not open, the quote is for information only.

{
  "type": "object",
  "properties": {
    "items": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "description": "Product id from search_products, e.g. \"tee-heavyweight\"."
          },
          "color": {
            "type": "string",
            "description": "Colour id or name, e.g. \"black\"."
          },
          "size": {
            "type": "string",
            "description": "Size, e.g. \"XL\". For one-size products use \"ONE SIZE\" (\"ONE\" also works)."
          },
          "quantity": {
            "default": 1,
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "artwork": {
            "minItems": 1,
            "maxItems": 4,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "placement": {
                  "default": "front",
                  "description": "Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.",
                  "type": "string"
                },
                "preset": {
                  "description": "Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.",
                  "type": "string"
                },
                "width_mm": {
                  "description": "Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 1000
                },
                "height_mm": {
                  "description": "Maximum printed height in millimetres.",
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "maximum": 1000
                },
                "top_mm": {
                  "description": "Distance from the top of the print area to the top of the artwork.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1000
                },
                "left_mm": {
                  "description": "Distance from the left edge of the print area. Default: horizontally centred.",
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1000
                },
                "artwork_id": {
                  "type": "string",
                  "description": "artwork_id returned by validate_artwork."
                }
              },
              "required": [
                "artwork_id"
              ]
            },
            "description": "One entry per print placement. Each placement may appear once per item."
          }
        },
        "required": [
          "product_id",
          "color",
          "size",
          "artwork"
        ]
      }
    },
    "ship_to": {
      "description": "Destination. country_code is required; postal_code and state_code improve shipping accuracy.",
      "type": "object",
      "properties": {
        "country_code": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "state_code": {
          "type": "string",
          "maxLength": 10
        },
        "postal_code": {
          "type": "string",
          "maxLength": 20
        },
        "city": {
          "type": "string",
          "maxLength": 60
        }
      },
      "required": [
        "country_code"
      ]
    },
    "preference": {
      "default": "fewest_packages",
      "description": "How AgentMade picks the manufacturing route: fewest_packages (default: fewest parcels, then best price among the fastest routes), cheapest, or fastest.",
      "type": "string",
      "enum": [
        "fewest_packages",
        "cheapest",
        "fastest"
      ]
    },
    "purpose": {
      "description": "What the order is for. Set it only if the user already said it. Do not ask for it.",
      "type": "string",
      "enum": [
        "gift",
        "personal",
        "group",
        "work",
        "event",
        "sample"
      ]
    },
    "deliver_by": {
      "description": "Date by which the parcel should arrive, e.g. \"2026-12-20\". The quote is never refused because of it: if the estimate is later, the quote says so.",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "speed": {
      "default": "standard",
      "description": "Shipping speed. Only standard is offered now; express returns a note and a standard quote.",
      "type": "string",
      "enum": [
        "standard",
        "express"
      ]
    },
    "currency": {
      "description": "ISO 4217 currency of the payer, e.g. \"USD\". Optional. The quote states the currency that it uses.",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "buyer": {
      "description": "Only for a company purchase with an invoice. Business checkout is not open yet: the quote charges destination VAT.",
      "type": "object",
      "properties": {
        "company_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Registered company name for the invoice."
        },
        "vat_id": {
          "description": "EU or UK VAT number with the country prefix, e.g. \"DE123456789\".",
          "type": "string",
          "maxLength": 20
        }
      },
      "required": [
        "company_name"
      ]
    }
  },
  "required": [
    "items",
    "ship_to"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string",
      "description": "Use in purchase before expires_at."
    },
    "status": {
      "type": "string",
      "enum": [
        "valid",
        "expired"
      ]
    },
    "expires_at": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_id": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          },
          "variant_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "size": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "line_total_minor": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Integer minor units (cents) of `currency`."
          },
          "placements": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "artwork_id": {
                  "type": "string"
                },
                "placement": {
                  "type": "string"
                },
                "validation": {
                  "type": "string",
                  "enum": [
                    "PASS",
                    "WARN",
                    "FAIL"
                  ]
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "artwork_id",
                "placement",
                "validation",
                "warnings"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "line_id",
          "product_id",
          "variant_id",
          "title",
          "color",
          "size",
          "quantity",
          "line_total_minor",
          "placements"
        ],
        "additionalProperties": {}
      }
    },
    "ship_to": {
      "type": "object",
      "properties": {
        "country_code": {
          "type": "string"
        }
      },
      "required": [
        "country_code"
      ],
      "additionalProperties": {}
    },
    "shipping": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "price_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "transit_business_days": {
          "type": "object",
          "properties": {
            "min": {
              "type": [
                "number",
                "null"
              ]
            },
            "max": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": {}
        }
      },
      "required": [
        "name",
        "price_minor",
        "transit_business_days"
      ],
      "additionalProperties": {}
    },
    "packages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "package": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "line_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ships_from": {
            "description": "Country code where the package is printed.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "package",
          "line_ids",
          "ships_from"
        ],
        "additionalProperties": {}
      }
    },
    "package_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "tax": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string"
        },
        "rate_percent": {
          "type": "number"
        },
        "amount_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "included_in_total": {
          "type": "boolean"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "label",
        "rate_percent",
        "amount_minor",
        "included_in_total",
        "note"
      ],
      "additionalProperties": {}
    },
    "totals": {
      "type": "object",
      "properties": {
        "products_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "shipping_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "tax_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "total_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "total_formatted": {
          "type": "string"
        }
      },
      "required": [
        "products_minor",
        "shipping_minor",
        "tax_minor",
        "total_minor",
        "total_formatted"
      ],
      "additionalProperties": {},
      "description": "total_minor is the full amount that the payer pays. Show total_formatted to the user. products_minor and shipping_minor are before VAT; tax_minor is the VAT included in the total, or 0 when tax is not collected."
    },
    "delivery_estimate_business_days": {
      "type": "object",
      "properties": {
        "min": {
          "type": [
            "number",
            "null"
          ]
        },
        "max": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": {}
    },
    "delivery_estimate_dates": {
      "type": "object",
      "properties": {
        "earliest": {
          "type": "string"
        },
        "latest": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "earliest",
        "latest",
        "note"
      ],
      "additionalProperties": {},
      "description": "Calendar dates (YYYY-MM-DD) for the delivery estimate. Tell the user these dates."
    },
    "purchase_open": {
      "type": "boolean",
      "description": "False when this destination does not take orders yet or the quote expired. Then do not call purchase."
    },
    "assumptions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Things to tell the user before purchase."
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    }
  },
  "required": [
    "quote_id",
    "status",
    "expires_at",
    "currency",
    "items",
    "ship_to",
    "shipping",
    "packages",
    "package_count",
    "tax",
    "totals",
    "delivery_estimate_business_days",
    "delivery_estimate_dates",
    "purchase_open",
    "assumptions",
    "notes",
    "next_step"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Turn a quote into an order. Needs quote_id, the full recipient address (it must match the quoted destination) and rights_attestation=true. contact_email is the payer's own email, never the gift recipient's. Returns order_id and payment.url: the order page where the person pays by card, Apple Pay or Google Pay. Nothing is printed until the payment is confirmed. Idempotent per quote_id.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "description": "quote_id returned by quote, for one parcel. Set quote_id or orders, not both.",
      "type": "string"
    },
    "recipient": {
      "description": "Shipping address. Country, state and postal code must match the quote destination. Send the full address when you have it. If you cannot collect the street address, send only country_code, postal_code (and state_code for US, CA and AU): the person then enters the address on the order page before paying. Required with quote_id.",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Full name of the recipient."
        },
        "company": {
          "type": "string",
          "maxLength": 100
        },
        "address1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Street and house number."
        },
        "address2": {
          "description": "Apartment, floor, etc.",
          "type": "string",
          "maxLength": 100
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "state_code": {
          "description": "State or province code. Required for US, CA and AU.",
          "type": "string",
          "maxLength": 10
        },
        "postal_code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20
        },
        "country_code": {
          "description": "ISO 3166-1 alpha-2 country code, e.g. CZ, DE, US.",
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "email": {
          "description": "Recipient email, for carrier delivery notices only. Never used for receipts. For a gift, leave it empty unless the recipient agrees.",
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "phone": {
          "type": "string",
          "maxLength": 30
        }
      },
      "required": [
        "postal_code",
        "country_code"
      ]
    },
    "orders": {
      "description": "Many parcels with one payment: one quote_id and one recipient per parcel. Not live yet: call purchase once per quote_id for now.",
      "minItems": 2,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "quote_id": {
            "type": "string",
            "description": "quote_id returned by quote."
          },
          "recipient": {
            "description": "Shipping address. Country, state and postal code must match the quote destination. Send the full address when you have it. If you cannot collect the street address, send only country_code, postal_code (and state_code for US, CA and AU): the person then enters the address on the order page before paying.",
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "description": "Full name of the recipient."
              },
              "company": {
                "type": "string",
                "maxLength": 100
              },
              "address1": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "description": "Street and house number."
              },
              "address2": {
                "description": "Apartment, floor, etc.",
                "type": "string",
                "maxLength": 100
              },
              "city": {
                "type": "string",
                "minLength": 1,
                "maxLength": 60
              },
              "state_code": {
                "description": "State or province code. Required for US, CA and AU.",
                "type": "string",
                "maxLength": 10
              },
              "postal_code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "country_code": {
                "description": "ISO 3166-1 alpha-2 country code, e.g. CZ, DE, US.",
                "type": "string",
                "minLength": 2,
                "maxLength": 2
              },
              "email": {
                "description": "Recipient email, for carrier delivery notices only. Never used for receipts. For a gift, leave it empty unless the recipient agrees.",
                "type": "string",
                "format": "email",
                "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              },
              "phone": {
                "type": "string",
                "maxLength": 30
              }
            },
            "required": [
              "name",
              "address1",
              "city",
              "postal_code",
              "country_code"
            ]
          }
        },
        "required": [
          "quote_id",
          "recipient"
        ]
      }
    },
    "contact_email": {
      "description": "Email of the payer, for the order confirmation and the payment receipt. Not the recipient's email: for a gift, the recipient must not see the price. Optional.",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "payment_capabilities": {
      "default": [
        "hosted_checkout"
      ],
      "description": "Payment methods the calling agent can use. \"hosted_checkout\" = a link that the person opens to pay by card, Apple Pay or Google Pay. Always supported.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "hosted_checkout",
          "x402",
          "mpp"
        ]
      }
    },
    "gift_message": {
      "description": "Short message for the packing slip of a gift. Not printed yet: the answer says so.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "rights_attestation": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms the customer owns or is licensed to print all submitted artwork, and that it is not prohibited content."
    }
  },
  "required": [
    "rights_attestation"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "A bearer key: whoever has it can read and cancel the order. Do not share it publicly."
    },
    "status": {
      "type": "string",
      "enum": [
        "AWAITING_PAYMENT",
        "PAID",
        "VALIDATING",
        "SUBMITTING",
        "SUBMITTED",
        "IN_PRODUCTION",
        "SHIPPED",
        "DELIVERED",
        "QUOTE_EXPIRED",
        "PAYMENT_FAILED",
        "REJECTED",
        "SUBMISSION_FAILED",
        "CANCELLED",
        "REFUND_PENDING",
        "REFUNDED",
        "DISPUTED"
      ]
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    },
    "address_needed": {
      "type": "boolean",
      "description": "True when purchase had no street address: the person enters it on the order page before paying."
    },
    "destination": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country_code": {
              "type": "string"
            }
          },
          "required": [
            "country_code"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "While address_needed: the quoted destination."
    },
    "status_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "quote_id": {
      "type": "string"
    },
    "total": {
      "type": "object",
      "properties": {
        "amount_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "currency": {
          "type": "string"
        },
        "formatted": {
          "type": "string"
        }
      },
      "required": [
        "amount_minor",
        "currency",
        "formatted"
      ],
      "additionalProperties": {}
    },
    "order_url": {
      "type": "string",
      "description": "The order page. The person sees the status there."
    },
    "payment": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string"
        },
        "paid": {
          "type": "boolean",
          "description": "True only after a verified payment."
        },
        "url": {
          "description": "While unpaid: the link to give the person who pays.",
          "type": [
            "string",
            "null"
          ]
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "instructions": {
          "type": [
            "string",
            "null"
          ]
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "method",
        "paid",
        "url",
        "expires_at",
        "instructions",
        "note"
      ],
      "additionalProperties": {}
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "size": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "mockups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "placement": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "placement",
                "url"
              ],
              "additionalProperties": {}
            },
            "description": "One preview per print side of the ordered design on the product. Show them to the person as the exact print."
          }
        },
        "required": [
          "product_id",
          "title",
          "color",
          "size",
          "quantity",
          "image_url",
          "mockups"
        ],
        "additionalProperties": {}
      }
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "carrier": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "carrier",
          "tracking_number",
          "tracking_url"
        ],
        "additionalProperties": {}
      }
    },
    "delivery_estimate_business_days": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "min": {
              "type": [
                "number",
                "null"
              ]
            },
            "max": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Null when the order ended (cancelled, refunded, rejected, expired or delivered)."
    },
    "timeline": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "at",
          "status",
          "note"
        ],
        "additionalProperties": {}
      }
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "order_id",
    "status",
    "next_step",
    "address_needed",
    "destination",
    "status_reason",
    "quote_id",
    "total",
    "order_url",
    "payment",
    "items",
    "shipments",
    "delivery_estimate_business_days",
    "timeline",
    "notes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Current order status (AWAITING_PAYMENT, PAID, SUBMITTED, IN_PRODUCTION, SHIPPED, DELIVERED or an exception state), next_step in plain language, the payment link while unpaid, shipments and a timeline.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "order_id returned by purchase."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "A bearer key: whoever has it can read and cancel the order. Do not share it publicly."
    },
    "status": {
      "type": "string",
      "enum": [
        "AWAITING_PAYMENT",
        "PAID",
        "VALIDATING",
        "SUBMITTING",
        "SUBMITTED",
        "IN_PRODUCTION",
        "SHIPPED",
        "DELIVERED",
        "QUOTE_EXPIRED",
        "PAYMENT_FAILED",
        "REJECTED",
        "SUBMISSION_FAILED",
        "CANCELLED",
        "REFUND_PENDING",
        "REFUNDED",
        "DISPUTED"
      ]
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    },
    "address_needed": {
      "type": "boolean",
      "description": "True when purchase had no street address: the person enters it on the order page before paying."
    },
    "destination": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country_code": {
              "type": "string"
            }
          },
          "required": [
            "country_code"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "While address_needed: the quoted destination."
    },
    "status_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "quote_id": {
      "type": "string"
    },
    "total": {
      "type": "object",
      "properties": {
        "amount_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "currency": {
          "type": "string"
        },
        "formatted": {
          "type": "string"
        }
      },
      "required": [
        "amount_minor",
        "currency",
        "formatted"
      ],
      "additionalProperties": {}
    },
    "order_url": {
      "type": "string",
      "description": "The order page. The person sees the status there."
    },
    "payment": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string"
        },
        "paid": {
          "type": "boolean",
          "description": "True only after a verified payment."
        },
        "url": {
          "description": "While unpaid: the link to give the person who pays.",
          "type": [
            "string",
            "null"
          ]
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "instructions": {
          "type": [
            "string",
            "null"
          ]
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "method",
        "paid",
        "url",
        "expires_at",
        "instructions",
        "note"
      ],
      "additionalProperties": {}
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "size": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "mockups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "placement": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "placement",
                "url"
              ],
              "additionalProperties": {}
            },
            "description": "One preview per print side of the ordered design on the product. Show them to the person as the exact print."
          }
        },
        "required": [
          "product_id",
          "title",
          "color",
          "size",
          "quantity",
          "image_url",
          "mockups"
        ],
        "additionalProperties": {}
      }
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "carrier": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "carrier",
          "tracking_number",
          "tracking_url"
        ],
        "additionalProperties": {}
      }
    },
    "delivery_estimate_business_days": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "min": {
              "type": [
                "number",
                "null"
              ]
            },
            "max": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Null when the order ended (cancelled, refunded, rejected, expired or delivered)."
    },
    "timeline": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "at",
          "status",
          "note"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "order_id",
    "status",
    "next_step",
    "address_needed",
    "destination",
    "status_reason",
    "quote_id",
    "total",
    "order_url",
    "payment",
    "items",
    "shipments",
    "delivery_estimate_business_days",
    "timeline"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Carrier, tracking number and tracking link for each shipment of an order, and the delivery estimate.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "order_id returned by purchase."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "AWAITING_PAYMENT",
        "PAID",
        "VALIDATING",
        "SUBMITTING",
        "SUBMITTED",
        "IN_PRODUCTION",
        "SHIPPED",
        "DELIVERED",
        "QUOTE_EXPIRED",
        "PAYMENT_FAILED",
        "REJECTED",
        "SUBMISSION_FAILED",
        "CANCELLED",
        "REFUND_PENDING",
        "REFUNDED",
        "DISPUTED"
      ]
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    },
    "order_url": {
      "type": "string"
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "carrier": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "carrier",
          "tracking_number",
          "tracking_url"
        ],
        "additionalProperties": {}
      }
    },
    "delivery_estimate_business_days": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "min": {
              "type": [
                "number",
                "null"
              ]
            },
            "max": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Null when the order ended (cancelled, refunded, rejected, expired or delivered)."
    },
    "tracking_available": {
      "type": "boolean"
    }
  },
  "required": [
    "order_id",
    "status",
    "next_step",
    "order_url",
    "shipments",
    "delivery_estimate_business_days",
    "tracking_available"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Cancel an order. Unpaid: closes the payment link; nothing is charged. Paid and not yet in production: cancels and refunds in full. In production or shipped: cannot be cancelled; the error gives the reason. A second call on a cancelled order is safe.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "order_id returned by purchase."
    },
    "reason": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "A bearer key: whoever has it can read and cancel the order. Do not share it publicly."
    },
    "status": {
      "type": "string",
      "enum": [
        "AWAITING_PAYMENT",
        "PAID",
        "VALIDATING",
        "SUBMITTING",
        "SUBMITTED",
        "IN_PRODUCTION",
        "SHIPPED",
        "DELIVERED",
        "QUOTE_EXPIRED",
        "PAYMENT_FAILED",
        "REJECTED",
        "SUBMISSION_FAILED",
        "CANCELLED",
        "REFUND_PENDING",
        "REFUNDED",
        "DISPUTED"
      ]
    },
    "next_step": {
      "type": "string",
      "description": "What the agent should do next, in plain language."
    },
    "address_needed": {
      "type": "boolean",
      "description": "True when purchase had no street address: the person enters it on the order page before paying."
    },
    "destination": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country_code": {
              "type": "string"
            }
          },
          "required": [
            "country_code"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "While address_needed: the quoted destination."
    },
    "status_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "quote_id": {
      "type": "string"
    },
    "total": {
      "type": "object",
      "properties": {
        "amount_minor": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Integer minor units (cents) of `currency`."
        },
        "currency": {
          "type": "string"
        },
        "formatted": {
          "type": "string"
        }
      },
      "required": [
        "amount_minor",
        "currency",
        "formatted"
      ],
      "additionalProperties": {}
    },
    "order_url": {
      "type": "string",
      "description": "The order page. The person sees the status there."
    },
    "payment": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string"
        },
        "paid": {
          "type": "boolean",
          "description": "True only after a verified payment."
        },
        "url": {
          "description": "While unpaid: the link to give the person who pays.",
          "type": [
            "string",
            "null"
          ]
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "instructions": {
          "type": [
            "string",
            "null"
          ]
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "method",
        "paid",
        "url",
        "expires_at",
        "instructions",
        "note"
      ],
      "additionalProperties": {}
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "size": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "mockups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "placement": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "placement",
                "url"
              ],
              "additionalProperties": {}
            },
            "description": "One preview per print side of the ordered design on the product. Show them to the person as the exact print."
          }
        },
        "required": [
          "product_id",
          "title",
          "color",
          "size",
          "quantity",
          "image_url",
          "mockups"
        ],
        "additionalProperties": {}
      }
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "carrier": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "carrier",
          "tracking_number",
          "tracking_url"
        ],
        "additionalProperties": {}
      }
    },
    "delivery_estimate_business_days": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "min": {
              "type": [
                "number",
                "null"
              ]
            },
            "max": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Null when the order ended (cancelled, refunded, rejected, expired or delivered)."
    },
    "timeline": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "at",
          "status",
          "note"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "order_id",
    "status",
    "next_step",
    "address_needed",
    "destination",
    "status_reason",
    "quote_id",
    "total",
    "order_url",
    "payment",
    "items",
    "shipments",
    "delivery_estimate_business_days",
    "timeline"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}