# REST API reference OpenAPI 3.1.0; API version v1. JSON schema: https://onprint-test.heymadeit.com/api/v1/openapi.json Schemas below describe the current API. Error responses use JSON {"message":"..."}; 422 additionally includes errors as an object mapping field names to arrays of messages. Rate-limited responses may include Retry-After in seconds. Additional model metadata may be returned; tolerate unknown response fields. Examples use fictional identifiers which must be replaced by your own tenant resources. ## GET /api/v1/orders List orders Operation ID: `api_commerce_orders_index` Print orders, verified payment updates and production files. Required scope: `orders:read`. All resources are scoped to this printer hostname. Endpoint throttle: 60 requests per 60 seconds. Respect Retry-After on 429. ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "status": { "type": "string" }, "totalOre": { "type": "integer" } } } } } } } } } } ``` ## POST /api/v1/orders Create orders Operation ID: `merchant-api_post_orders` Print orders, verified payment updates and production files. Required scope: `orders:write`. All resources are scoped to this printer hostname. Idempotency-Key is required (1–120 letters, digits, underscores, dots, colons or hyphens). Reuse it for the same request body on retries; a different body with the same key returns 409. Shipping addresses are required when the shipping method requires one. Payment verification belongs on your server. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]{1,120}$" }, "example": "shop-order-1042" } ] ``` ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "minimum": 1 }, "payment_method": { "enum": [ "manual", "on_account", "external" ] }, "shipping_method_id": { "type": "integer" }, "shipping_address": { "type": "object", "required": [ "name", "line1", "postal_code", "city", "country" ], "properties": { "name": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "product", "design", "quantity" ], "properties": { "product": { "type": "string", "format": "uuid" }, "design": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 } } }, "minItems": 1, "maxItems": 100 } }, "required": [ "customer_id", "payment_method", "shipping_method_id", "lines" ] }, "example": { "customer_id": 123, "payment_method": "external", "shipping_method_id": 1, "lines": [ { "product": "00000000-0000-7000-8000-000000000001", "design": "00000000-0000-7000-8000-000000000001", "quantity": 100 } ] } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "status": { "type": "string" }, "total_ore": { "type": "integer" } } } } } } } } } ``` ## GET /api/v1/orders/{order} Get orders Operation ID: `api_commerce_orders_show` Print orders, verified payment updates and production files. Required scope: `orders:read`. All resources are scoped to this printer hostname. Endpoint throttle: 60 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "status": { "type": "string" }, "total_ore": { "type": "integer" }, "totalOre": { "type": "integer" }, "shipping_address": { "type": [ "object", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "quantity": { "type": "integer" }, "copyId": { "type": "integer" }, "print_files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "url": { "type": [ "string", "null" ] } } } } } } } } } } } } } } } ``` ## PATCH /api/v1/orders/{order} Update orders Operation ID: `merchant-api_orders_update` Print orders, verified payment updates and production files. Required scope: `orders:write`. All resources are scoped to this printer hostname. ### Parameters ```json [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "paid", "cancelled" ] } }, "required": [ "status" ] }, "example": { "status": "paid" } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "status": { "type": "string" } } } } } } } } } ``` ## GET /api/v1/products List products Operation ID: `merchant-api_get_products` Catalogue items and quantity prices. Monetary fields are integer minor currency units. Required scope: `products:read`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "unit": { "type": "string" }, "active": { "type": "boolean" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer" }, "net_ore": { "type": "integer" } } } } } } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] } } } } } } } ``` ## POST /api/v1/products Create products Operation ID: `merchant-api_post_products` Catalogue items and quantity prices. Monetary fields are integer minor currency units. Required scope: `products:write`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 150 }, "width": { "type": "integer", "minimum": 1, "maximum": 10000 }, "height": { "type": "integer", "minimum": 1, "maximum": 10000 }, "unit": { "enum": [ "px", "mm", "cm", "in" ] }, "active": { "type": "boolean" }, "prices": { "type": "array", "items": { "type": "object", "required": [ "quantity", "net_ore" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "net_ore": { "type": "integer", "minimum": 0, "maximum": 100000000 } } }, "minItems": 1, "maxItems": 30 } }, "required": [ "name", "width", "height", "unit", "active", "prices" ] }, "example": { "name": "A5 flyer", "width": 148, "height": 210, "unit": "mm", "active": true, "prices": [ { "quantity": 100, "net_ore": 25000 } ] } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "unit": { "type": "string" }, "active": { "type": "boolean" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer" }, "net_ore": { "type": "integer" } } } } } } } } } } } } ``` ## GET /api/v1/products/{product} Get products Operation ID: `merchant-api_get_products_product` Catalogue items and quantity prices. Monetary fields are integer minor currency units. Required scope: `products:read`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "unit": { "type": "string" }, "active": { "type": "boolean" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer" }, "net_ore": { "type": "integer" } } } } } } } } } } } } ``` ## PUT /api/v1/products/{product} Update products Operation ID: `merchant-api_put_products_product` Catalogue items and quantity prices. Monetary fields are integer minor currency units. Required scope: `products:write`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 150 }, "width": { "type": "integer", "minimum": 1, "maximum": 10000 }, "height": { "type": "integer", "minimum": 1, "maximum": 10000 }, "unit": { "enum": [ "px", "mm", "cm", "in" ] }, "active": { "type": "boolean" }, "prices": { "type": "array", "items": { "type": "object", "required": [ "quantity", "net_ore" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "net_ore": { "type": "integer", "minimum": 0, "maximum": 100000000 } } }, "minItems": 1, "maxItems": 30 } }, "required": [ "name", "width", "height", "unit", "active", "prices" ] }, "example": { "name": "A5 flyer", "width": 148, "height": 210, "unit": "mm", "active": true, "prices": [ { "quantity": 100, "net_ore": 25000 } ] } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "unit": { "type": "string" }, "active": { "type": "boolean" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer" }, "net_ore": { "type": "integer" } } } } } } } } } } } } ``` ## DELETE /api/v1/products/{product} Archive products Operation ID: `merchant-api_delete_products_product` Catalogue items and quantity prices. Monetary fields are integer minor currency units. Required scope: `products:write`. All resources are scoped to this printer hostname. Archives the product by setting active=false; retains existing orders. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "204": { "description": "Completed; no response body" } } ``` ## GET /api/v1/customers List customers Operation ID: `merchant-api_get_customers` Find or create customer accounts on this printer only. Required scope: `customers:read`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "email", "in": "query", "schema": { "type": "string", "format": "email" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] } } } } } } } ``` ## POST /api/v1/customers Create customers Operation ID: `merchant-api_post_customers` Find or create customer accounts on this printer only. Required scope: `customers:write`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "locale": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "email" ] }, "example": { "name": "Alex Example", "email": "alex@example.com", "locale": "en" } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } } } } } ``` ## GET /api/v1/designs List designs Operation ID: `merchant-api_get_designs` Customer-owned editable documents, created blank or copied from a published template. Required scope: `designs:read`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "owner_id": { "type": "integer" }, "title": { "type": "string" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "head_seq": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] } } } } } } } ``` ## POST /api/v1/designs Create designs Operation ID: `merchant-api_post_designs` Customer-owned editable documents, created blank or copied from a published template. Required scope: `designs:write`. All resources are scoped to this printer hostname. Choose either a preset format or width_mm + height_mm. With a template, supply the exact trim size and omit format. Flat designs support 1–8 pages; booklet presets use their own sheet constraints. UUIDs identify designs and templates; customer_id is an integer. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "maxLength": 200 }, "format": { "type": "string", "description": "A preset key; or give width_mm and height_mm." }, "width_mm": { "type": "number", "minimum": 10, "maximum": 5000 }, "height_mm": { "type": "number", "minimum": 10, "maximum": 5000 }, "bleed_mm": { "type": "number", "minimum": 0, "maximum": 50, "default": 3 }, "pages": { "type": "integer", "minimum": 1, "maximum": 8, "default": 1 }, "template": { "type": "string", "format": "uuid", "description": "A published template to clone at width_mm \u00d7 height_mm. Omit it for a blank design." } }, "required": [ "customer_id", "title" ], "oneOf": [ { "required": [ "format" ], "not": { "anyOf": [ { "required": [ "width_mm" ] }, { "required": [ "height_mm" ] }, { "required": [ "bleed_mm" ] }, { "required": [ "template" ] } ] } }, { "required": [ "width_mm", "height_mm" ], "not": { "required": [ "format" ] } } ] }, "example": { "customer_id": 123, "title": "Spring flyer", "width_mm": 148, "height_mm": 210, "pages": 1 } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "owner_id": { "type": "integer" }, "title": { "type": "string" }, "pages": { "type": "integer" } } } } } } } } } ``` ## GET /api/v1/designs/{design} Get designs Operation ID: `merchant-api_get_designs_design` Customer-owned editable documents, created blank or copied from a published template. Required scope: `designs:read`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "design", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "owner_id": { "type": "integer" }, "title": { "type": "string" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "head_seq": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } ``` ## GET /api/v1/templates List templates Operation ID: `merchant-api_get_templates` Published shared templates and this printer’s own templates. Publishing uses MCP, not REST. Required scope: `templates:read`. All resources are scoped to this printer hostname. Contains published HeyMadeIt templates and this printer’s templates, never another printer’s own templates. Both dimensions are required when filtering by size. fields=browse includes description_da and category_name_da. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "width_mm", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "height_mm", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "pages", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "browse" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "object" }, "format_key": { "type": "string" }, "category": { "type": "string" }, "pages": { "type": "integer" }, "width_mm": { "type": "number" }, "height_mm": { "type": "number" }, "thumb": { "type": "string" } } } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] } } } } } } } ``` ## GET /api/v1/templates/{template} Get templates Operation ID: `merchant-api_get_templates_template` Published shared templates and this printer’s own templates. Publishing uses MCP, not REST. Required scope: `templates:read`. All resources are scoped to this printer hostname. Endpoint throttle: 120 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "object" }, "format_key": { "type": "string" }, "category": { "type": "string" }, "pages": { "type": "integer" }, "width_mm": { "type": "number" }, "height_mm": { "type": "number" }, "thumb": { "type": "string" } } } } } } } } } ``` ## POST /api/v1/editor-sessions Create editor sessions Operation ID: `merchant-api_editor-sessions` One-use, five-minute sessions for embedding the editor without exposing a merchant key. Required scope: `editor:write`. All resources are scoped to this printer hostname. The design must belong to customer_id. parent_origin must exactly match an origin allowed on embed_key. Redeem session_token once by POST /embed/session, or pass it as sessionToken to the embed SDK. It expires after 300 seconds. Never put it in a URL or logs. The response uses Cache-Control: no-store. Endpoint throttle: 60 requests per 60 seconds. Respect Retry-After on 429. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "minimum": 1 }, "design": { "type": "string", "format": "uuid" }, "embed_key": { "type": "string" }, "parent_origin": { "type": "string", "format": "uri" }, "finish": { "enum": [ "save", "basket" ], "default": "save", "description": "The finish button: \"Gem og forts\u00e6t\" or \"L\u00e6g i kurv\"." } }, "required": [ "customer_id", "design", "embed_key", "parent_origin" ] }, "example": { "customer_id": 123, "design": "00000000-0000-7000-8000-000000000001", "embed_key": "YOUR_EMBED_KEY", "parent_origin": "https://shop.example.com", "finish": "save" } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_token": { "type": "string", "description": "One-use token, redeemed by POST /embed/session." }, "expires_in": { "type": "integer", "const": 300 }, "redeem_url": { "type": "string", "format": "uri" } } } } } } } ``` ## GET /api/v1/membership-plans List memberships Operation ID: `merchant-api_membership-plans` Printer-owned plans for its customers; separate from HeyMadeIt printer subscriptions. Required scope: `subscriptions:read`. All resources are scoped to this printer hostname. ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "amount_minor": { "type": "integer" }, "currency": { "type": "string" }, "interval": { "type": "string", "enum": [ "month", "year" ] }, "checkout_url": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } } } } } } } } } } ``` ## GET /api/v1/subscriptions List subscriptions Operation ID: `merchant-api_subscriptions_index` Sync your payment provider’s verified membership state from your server. Required scope: `subscriptions:read`. All resources are scoped to this printer hostname. ### Parameters ```json [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "merchant_plan_id": { "type": "integer" }, "external_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "trialing", "past_due", "cancelled" ] }, "current_period_end": { "type": "string", "format": "date-time" } } } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] } } } } } } } } } ``` ## POST /api/v1/subscriptions Create subscriptions Operation ID: `merchant-api_subscriptions_sync` Sync your payment provider’s verified membership state from your server. Required scope: `subscriptions:write`. All resources are scoped to this printer hostname. Only call after verifying your payment provider on your server. current_period_end must be in the future for active or trialing status. Reusing external_id for a different customer returns 409. The printer must enable subscriptions. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "minimum": 1 }, "plan": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "maxLength": 150 }, "status": { "enum": [ "active", "trialing", "past_due", "cancelled" ] }, "current_period_end": { "type": "string", "format": "date-time" } }, "required": [ "customer_id", "plan", "external_id", "status", "current_period_end" ] }, "example": { "customer_id": 123, "plan": "00000000-0000-7000-8000-000000000001", "external_id": "provider-subscription-1042", "status": "active", "current_period_end": "2099-12-31T23:59:59Z" } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "merchant_plan_id": { "type": "integer" }, "external_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "trialing", "past_due", "cancelled" ] }, "current_period_end": { "type": "string", "format": "date-time" } } } } } } } } } ``` ## POST /api/v1/designs/{design}/exports Create exports Operation ID: `merchant-api_exports_store` Asynchronous document rendering and authenticated downloads. Required scope: `exports:write`. All resources are scoped to this printer hostname. POST queues a render (202). Poll GET /exports/{export} until status=done or a terminal failed/canceled state; back off between polls. Download file_url with exports:read; it is null until done. Expired or unavailable files return 404. No webhook delivery is promised. PDF Print supports marks, bleed and bleed_mm. Endpoint throttle: 30 requests per 60 seconds. Respect Retry-After on 429. ### Parameters ```json [ { "name": "design", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "enum": [ "png", "jpg", "pdf_standard", "pdf_print" ] }, "pages": { "type": "array", "items": { "type": "string" }, "maxItems": 200 }, "marks": { "type": "boolean", "description": "Crop marks; also the bleed unless `bleed` is given." }, "bleed": { "type": "boolean", "description": "PDF Print: the document bleed, with or without marks." }, "bleed_mm": { "type": "number", "minimum": 0, "maximum": 50, "description": "PDF Print: the bleed in mm a print shop's data sheet asks for, less or more than the document's own (art on the trim grows into it)." }, "layout": { "enum": [ "pages", "spreads" ], "default": "spreads" }, "scale": { "type": "number", "minimum": 0.5, "maximum": 4 } } }, "example": { "format": "pdf_print", "marks": true, "bleed": true, "bleed_mm": 3, "layout": "pages" } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "202": { "description": "Render queued; poll the export status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "enum": [ "queued", "rendering", "encoding", "done", "failed", "canceled" ] }, "progress": { "type": "integer" }, "format": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "file_url": { "type": [ "string", "null" ], "description": "Relative download URL when done; requires exports:read." } } } } } } } } } ``` ## GET /api/v1/exports/{export} Get exports Operation ID: `merchant-api_exports_show` Asynchronous document rendering and authenticated downloads. Required scope: `exports:read`. All resources are scoped to this printer hostname. POST queues a render (202). Poll GET /exports/{export} until status=done or a terminal failed/canceled state; back off between polls. Download file_url with exports:read; it is null until done. Expired or unavailable files return 404. No webhook delivery is promised. PDF Print supports marks, bleed and bleed_mm. ### Parameters ```json [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "enum": [ "queued", "rendering", "encoding", "done", "failed", "canceled" ] }, "progress": { "type": "integer" }, "format": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "file_url": { "type": [ "string", "null" ], "description": "Relative download URL when done; requires exports:read." } } } } } } } } } ``` ## GET /api/v1/exports/{export}/file Get exports Operation ID: `merchant-api_exports_file` Asynchronous document rendering and authenticated downloads. Required scope: `exports:read`. All resources are scoped to this printer hostname. POST queues a render (202). Poll GET /exports/{export} until status=done or a terminal failed/canceled state; back off between polls. Download file_url with exports:read; it is null until done. Expired or unavailable files return 404. No webhook delivery is promised. PDF Print supports marks, bleed and bleed_mm. ### Parameters ```json [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } ``` ## GET /api/v1/shipping-methods List shipping Operation ID: `merchant-api_shipping_index` Delivery choices and their net prices. Required scope: `products:read`. All resources are scoped to this printer hostname. ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "net_ore": { "type": "integer" }, "active": { "type": "boolean" }, "requires_address": { "type": "boolean" } } } } } } } } } } ``` ## POST /api/v1/shipping-methods Create shipping Operation ID: `merchant-api_shipping_store` Delivery choices and their net prices. Required scope: `products:write`. All resources are scoped to this printer hostname. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "net_ore", "active" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "net_ore": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "active": { "type": "boolean" }, "requires_address": { "type": "boolean" } } }, "example": { "name": "Collection", "net_ore": 0, "active": true, "requires_address": false } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "net_ore": { "type": "integer" }, "active": { "type": "boolean" }, "requires_address": { "type": "boolean" } } } } } } } } } ``` ## GET /api/v1/print-files/{printFile} Get print files Operation ID: `merchant-api_print-file` Authenticated order production PDF downloads. Required scope: `orders:read`. All resources are scoped to this printer hostname. ### Parameters ```json [ { "name": "printFile", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } ``` ## GET /api/v1/client-licences List client licences Operation ID: `merchant-api_client-licences_index` Allocate the printer’s Business employee seat allowance across client company teams. Required scope: `licences:read`. All resources are scoped to this printer hostname. Light / Pro / Plus include 5 / 15 / 50 Business employee seats in total. Team owners and pending invitations consume seats. POST without team creates a team (201); with team resizes it (200). DELETE releases allocation without deleting designs or the team. These are named employee seats, not unlimited company subscriptions. ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowance": { "type": "integer" }, "allocated": { "type": "integer" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_id": { "type": "integer" }, "seats": { "type": "integer" }, "occupied": { "type": "integer" }, "owner": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } } } } } } } } ``` ## POST /api/v1/client-licences Create client licences Operation ID: `merchant-api_client-licences_store` Allocate the printer’s Business employee seat allowance across client company teams. Required scope: `licences:write`. All resources are scoped to this printer hostname. Light / Pro / Plus include 5 / 15 / 50 Business employee seats in total. Team owners and pending invitations consume seats. POST without team creates a team (201); with team resizes it (200). DELETE releases allocation without deleting designs or the team. These are named employee seats, not unlimited company subscriptions. ### JSON request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "name", "seats" ], "properties": { "customer_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 100 }, "seats": { "type": "integer", "minimum": 1, "maximum": 10000 }, "team": { "type": "string", "format": "uuid", "description": "Omit to create a client company team; supply its UUID to resize its allocation." } } }, "example": { "customer_id": 123, "name": "Example Company", "seats": 5 } } } } ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_id": { "type": "integer" }, "printer_licence_seats": { "type": "integer" } } } } } } } }, "200": { "description": "Existing team allocation resized", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_id": { "type": "integer" }, "printer_licence_seats": { "type": "integer" } } } } } } } } } ``` ## DELETE /api/v1/client-licences/{team} Release client licences Operation ID: `merchant-api_client-licences_destroy` Allocate the printer’s Business employee seat allowance across client company teams. Required scope: `licences:write`. All resources are scoped to this printer hostname. Light / Pro / Plus include 5 / 15 / 50 Business employee seats in total. Team owners and pending invitations consume seats. POST without team creates a team (201); with team resizes it (200). DELETE releases allocation without deleting designs or the team. These are named employee seats, not unlimited company subscriptions. ### Parameters ```json [ { "name": "team", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] ``` ### Responses ```json { "401": { "description": "Missing, unknown or revoked API key" }, "403": { "description": "Required scope or tenant capability missing" }, "404": { "description": "Resource does not belong to this tenant" }, "409": { "description": "Order state or idempotency conflict" }, "422": { "description": "Validation failed; errors maps field names to messages" }, "429": { "description": "Rate limit reached; retry with backoff" }, "204": { "description": "Completed; no response body" } } ```