Connect an assistant to PrintGen

Endpoint

Transport

Streamable HTTP

Sign-in

OAuth 2.1 with PKCE. The buyer signs in to PrintGen and chooses what the assistant may do.

Tools

17 tools: 13 read, 4 create something in the buyer’s account.

Ships to

United States only

Input

Written descriptions only. The tools do not take uploaded photos or logos.

Authentication

OAuth 2.1 authorization code with PKCE (S256). Clients discover the authorization server from /.well-known/oauth-protected-resource and may register themselves through dynamic client registration. A call without a valid token is answered with 401 and a WWW-Authenticate header that points at that document.

Access tokens last one hour. Request offline_access for a refresh token; a refresh token lasts 30 days and is replaced on every use.

Permissions

The buyer signs in to PrintGen and chooses which of these the assistant gets. Each is shown to them in the words below. They can disconnect the assistant at any time from their account page.

• catalog:read

  Browse products you can customize

  Needed by shop.list_products, shop.get_product

• design:read

  View the designs you made

  Needed by design.get_generation, design.get, design.list, design.browse

• design:write

  Create and change designs for you

  Needed by design.generate, design.edit

• mockup:read

  View previews of your designs on products

  Needed by design.browse, mockup.get_generation, mockup.get, mockup.show

• mockup:write

  Create previews of your designs on products

  Needed by mockup.generate

• order:read

  View your orders and their delivery status

  Needed by shop.get_checkout, shop.list_orders, shop.get_order

• checkout:write

  Prepare a checkout link for you to pay

  Needed by shop.create_checkout

A typical session

1. 1.shop.list_products Find a product the buyer can customize, with its starting price.
2. 2.shop.get_product Read its colors and sizes. Each size carries the variant_id a checkout needs.
3. 3.design.generate Start a design from the buyer’s description, then poll design.get_generation until it is done.
4. 4.design.get Show the finished design on the product.
5. 5.design.edit Refine it in plain language. Each edit is a new design, polled and shown the same way.
6. 6.shop.create_checkout Quote the order for the chosen sizes and quantities, and get the checkout link.
7. 7.shop.get_checkout After the buyer pays, confirm the order.
8. 8.shop.get_order Later, report production and delivery.

Generation is asynchronous: a generate or edit call returns a handle, and the matching get_generation tool long-polls it for up to 50 seconds per call. A finished design already comes with pictures of it on the product. mockup.generate makes more on request, such as close-ups of the print.

Each buyer has a small allowance of free designs, the same one the website gives them. A delivered design or edit uses one, a failed one uses none, and an order adds more. Previews are free.

Checkout and payment

An assistant prepares the order and the buyer pays for it. No tool takes a payment: shop.create_checkout returns a quote and a link to PrintGen’s checkout page, and an order exists only once the buyer has paid there.

1. Quote the order

Show the buyer the finished design and agree the sizes and quantities first. Then send one item per size. Each variant_id comes from shop.get_product, for the product the design was made on. Order the color the design was made for; to offer another, run design.edit with the new variant_group_uuid first, so the buyer sees the design on that color. A checkout takes up to 20 sizes and up to 50 of each.

{
  "name": "shop.create_checkout",
  "arguments": {
    "design_id": "e4a1c7b2-3f58-4c9d-a6e0-9b2d7f1c5a38",
    "items": [
      {
        "variant_id": "c2e4a6b8-d0f1-4a3c-8e5b-7f9d1b3a5c60",
        "quantity": 2
      },
      {
        "variant_id": "f1b3d5a7-c9e0-4b2d-9a4c-6e8f0a2c4b71",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "first_name": "Sam",
      "last_name": "Rivera",
      "address1": "500 Congress Ave",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    }
  }
}

{
  "checkout_id": "gid://shopify/Cart/hWN5k2PqT8xLm4RvYc7Zb1Qd?key=6b1f0e9d2c7a4b3e8f5a1c2d3e4f5a6b",
  "checkout_url": "https://…/cart/c/hWN5k2PqT8xLm4RvYc7Zb1Qd?key=6b1f0e9d2c7a4b3e8f5a1c2d3e4f5a6b",
  "status": "awaiting_payment",
  "seller": "PrintGen (Algorithmic Labs, LLC)",
  "lines": [
    {
      "variant_id": "c2e4a6b8-d0f1-4a3c-8e5b-7f9d1b3a5c60",
      "size": "M",
      "color": "Black",
      "quantity": 2,
      "unit_price_cents": 4699
    },
    {
      "variant_id": "f1b3d5a7-c9e0-4b2d-9a4c-6e8f0a2c4b71",
      "size": "L",
      "color": "Black",
      "quantity": 1,
      "unit_price_cents": 4699
    }
  ],
  "subtotal_cents": 14097,
  "shipping_cents": 0,
  "tax": "added on the checkout page, from the shipping address",
  "currency": "USD",
  "ships_to": "United States only",
  "address_prefilled": true,
  "policies_url": "https://printgen.ai/shipping-and-returns"
}

• unit_price_cents is what the buyer pays for one, design included. It can be higher than the price_cents in shop.get_product, which is the price before the design.
• shipping_cents is a number when shipping is already known, 0 when it is free, and null when the checkout page works it out. Tell the buyer a null is worked out at checkout; do not show it as free.
• Tax is never in the quote. The checkout page adds it from the shipping address.
• shipping_address is optional and must be a US address. With it, the checkout opens prefilled and all that is left for the buyer is to choose a payment method and confirm. Without it, they enter it on the checkout page.

2. Hand over the link

Give the buyer checkout_url exactly as it was returned. They pay on PrintGen’s checkout page; never ask for card details in the conversation. Keep checkout_id. Every call to shop.create_checkout makes a new checkout, so reuse the link you have instead of making another. An unpaid checkout costs nothing and expires on its own.

3. Confirm the payment

shop.get_checkout reads one of three states. Tell the buyer they have an order only after paid.

{
  "status": "awaiting_payment",
  "checkout_url": "https://…/cart/c/hWN5k2PqT8xLm4RvYc7Zb1Qd?key=6b1f0e9d2c7a4b3e8f5a1c2d3e4f5a6b"
}

{
  "status": "paid",
  "order": {
    "order_id": "7d1a3c5e-9b2f-4d6a-8c0e-2f4b6d8a0c13",
    "status": "paid",
    "stage": "paid",
    "total": "152.60",
    "currency": "USD",
    "created_at": "2026-10-09T15:04:12.381204+00:00",
    "items": [
      {
        "design_id": "e4a1c7b2-3f58-4c9d-a6e0-9b2d7f1c5a38",
        "title": "Milo's 7th Birthday",
        "quantity": 2,
        "unit_price": "46.99",
        "estimated_ship_at": "2026-10-14T00:00:00+00:00",
        "estimated_delivery_at": "2026-10-19T00:00:00+00:00"
      },
      {
        "design_id": "e4a1c7b2-3f58-4c9d-a6e0-9b2d7f1c5a38",
        "title": "Milo's 7th Birthday",
        "quantity": 1,
        "unit_price": "46.99",
        "estimated_ship_at": "2026-10-14T00:00:00+00:00",
        "estimated_delivery_at": "2026-10-19T00:00:00+00:00"
      }
    ],
    "tracking_url": null,
    "carrier": null,
    "ship_to": "Austin, TX"
  }
}

{
  "status": "not_found"
}

For about a minute after the buyer pays, a checkout can read not_found before it reads paid. Check again before saying anything went wrong or creating another checkout.

4. Follow the order

shop.get_order and shop.list_orders report where a paid order is. stage is the state to tell the buyer, such as in_production, shipped or delivered. tracking_url and carrier are filled once it ships, and ship_to holds the city and state only. The shop.get_order entry below has an order that has shipped.

Changes, cancellations and refunds are handled by PrintGen support at contact@printgen.ai.

When a checkout cannot be made

• A variant_id is not a size of the design’s product: invalid_argument. Use the ids shop.get_product returns for that product.
• A size cannot be produced right now: an error with no code that names the sizes. Offer another size or color.
• The design is still being prepared for checkout: an error with no code that says how many seconds to wait. Call again after that.
• The address is not a US address, or the checkout does not accept it: invalid_argument. Fix it, or leave it out and let the buyer enter it at checkout.

Tools

The server has 17 tools. A Read tool changes nothing. A Write tool creates something in the buyer’s own PrintGen account. No tool is a sensitive write: none charges the buyer, places an order, sends a message or deletes anything. Everything below is generated from the server’s own tool definitions.

ProductsDesignsPreviewsCheckout and ordersConnection

Errors

A failed call returns an error whose message starts with a stable code, then a colon and a sentence the assistant can show the buyer. A failure with no code says in its message what happened; most are temporary, so wait and try again.

• invalid_argument
  An input failed validation. The message names the field. Fix it and call again.
• not_found
  The design, product, preview or order does not exist or is not this buyer’s.
• missing_scope
  The buyer did not grant the permission this tool needs.
• rate_limited
  Too many calls to this tool. The message says how long to wait.
• insufficient_credits
  The buyer has used their free designs. An order adds more. Nothing was made.

Support

Questions about connecting an assistant: contact@printgen.ai.