{ "openapi": "3.1.0", "info": { "title": "Printcart REST API", "description": "The Printcart REST API powers the whole headless web-to-print build path:\ncreate a store, add products, define print sides with bleed and safe zones,\nupload fonts and artwork, save designs from the customizer, turn designs into\nprojects (orders), and generate print-ready PDFs.\n\n## Plans and API access\n\nThis reference is public, and the credentials every Printcart plugin already\nuses — `storeBasic` and `unauthToken` — keep working on every plan.\n\n**Creating developer API keys (`sk_…` / `pk_…`) requires the Advanced plan.**\nBelow Advanced, `POST /stores/{store}/api-keys` and `POST /account/api-keys`\nanswer `402` with `error.code` `capability_not_available` and an upgrade link in\n`error.details.cta.url`. Keys that already exist keep working and can still be\nrotated or revoked.\n\nBuilding your own integration on the API — including customising a Premium\nstore — is supported on **Advanced** and **Enterprise**, which include the\ntechnical support that kind of work needs.\n\n- [Compare plans and upgrade](https://www.printcart.com/en/payment/plans)\n- Enterprise — dedicated support and custom limits: support@printcart.com\n\n## Base URL\n\n`https://api.printcart.com/v1`\n\nRoutes are registered without an `/api` prefix. A few API Resources still test\nfor an `api/v1/...` path when deciding which optional fields to include; those\nbranches are unreachable in the current deployment and can be ignored.\n\n## Versioning\n\n`v1` is the only version in service. There is **no** `Accept-Version` header\nsupport in the API today — sending one has no effect. Treat additive response\nfields as expected: clients must tolerate unknown fields.\n\nThe API is under active development. Changes inside `v1` are additive; this\nreference is regenerated from the code on every release, so it always\ndescribes what is deployed.\n\n## Authentication\n\nThree credential types coexist. Which one an endpoint accepts is documented per\noperation via its `security` block:\n\n| Scheme | Header | Principal resolved | Typical caller |\n|---|---|---|---|\n| `storeBasic` | `Authorization: Basic base64(sid:secret)` | Store | server-side merchant integration |\n| `unauthToken` | `X-PrintCart-Unauth-Token: ` | Store | browser / embedded customizer (public key) |\n| `accountJwt` + `storeSid` | `Authorization: Bearer ` **and** `X-PrintCart-Store-Sid: ` | Store | dashboard acting on one store |\n| `accountJwt` | `Authorization: Bearer ` | User (account) | dashboard acting on the account |\n\n`storeBasic` and `unauthToken` are interchangeable on any operation whose\n`security` lists both: the `unauth.token` middleware accepts Basic credentials\nas well. The reverse is **not** true — an endpoint that only lists `storeBasic`\nrejects the unauth token.\n\n**The secret must never reach a browser.** `sid:secret` is a server-side\ncredential. The unauth token is the only credential intended for public\nclients.\n\n## Errors\n\nSee the `Error` schema and the error-code catalogue in that schema's\ndescription. Be aware that the live API emits **more than one error envelope**;\neach operation's error responses document the shape that endpoint actually\nreturns. The two shapes in circulation are `{\"error\":{\"message\":…}}` and\n`{\"message\":…}`.\n\n## Validation\n\nFailed validation returns **HTTP 400** (not 422) with\n`{\"error\":{\"\":[\"message\"]},\"message\":\"Invalid input\"}`.\n\n## Pagination\n\nList endpoints use **cursor** pagination, not page-number pagination. See the\n`CursorPaginationLinks` and `CursorPaginationMeta` schemas.\n\n## Rate limits\n\nA single global limiter applies: 1000 requests per minute, keyed by the\nauthenticated principal id, falling back to the client IP for unauthenticated\nroutes. Two narrower limiters exist for specific operations and are documented\non those operations.\n\n**Planned: limits by plan on specific endpoint classes.** Order creation,\npricing and Studio operations will get per-plan limits; read endpoints stay\ngenerous on every plan. New limits are announced here before they take\neffect, and a limited call answers `429` with a `Retry-After` header.", "contact": { "name": "Printcart Support", "url": "https://printcart.com", "email": "support@printcart.com" }, "license": { "name": "Proprietary", "url": "https://printcart.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.printcart.com/v1", "description": "Production" } ], "paths": { "/account/capabilities": { "get": { "tags": [ "Stores" ], "summary": "The store's resolved entitlement, plus the full tier matrix", "description": "What this store may do right now, and what every other tier would give it.\n\n`entitlement` is the resolved answer the capability middleware itself gates\non — tier, capability map and quotas — so a client never has to infer\naccess from a plan name. `matrix` is the same config for every tier, which\nis what lets a dashboard show a locked feature with its tier badge instead\nof hiding it; a hidden feature never sells an upgrade. `cta` carries the\nupgrade copy.\n\nReading this endpoint does not change anything and is not itself gated.", "operationId": "showAccountCapabilities", "responses": { "200": { "description": "Resolved entitlement and tier matrix.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "entitlement": { "description": "Tier, capability map and quotas as resolved for this store.", "type": "object" }, "matrix": { "description": "Capability map for every tier, keyed by tier.", "type": "object" }, "cta": { "description": "Upgrade call-to-action copy, keyed by tier.", "type": "object" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Authenticated as a user rather than a store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/account/api-keys": { "get": { "tags": [ "Authentication" ], "summary": "List the account's API keys", "description": "Every key on the account, across all its stores. Metadata only — a key's\nsecret value is shown once, at creation, and is not retrievable afterwards.", "operationId": "listAccountApiKeys", "responses": { "200": { "description": "Keys.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "apiKey": [] }, { "accountJwt": [] } ] }, "post": { "tags": [ "Authentication" ], "summary": "Create an account-scoped API key", "description": "Mints an `sk_acc_live_…` key that reaches **every store on the account**. Use a\nstore-scoped key instead unless the caller genuinely needs that reach.\n\nThe response carries a `key` field beside the key object. That is the only\ntime the secret is ever transmitted — store it before you close the response.", "operationId": "createAccountApiKey", "requestBody": { "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Label for the audit trail, e.g. \"CI deploy\".", "type": "string" }, "scopes": { "description": "Optional. Omit to receive the default scope set for this kind.", "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "allowed_ips": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Created. `key` appears here and nowhere else.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "key": { "description": "The plaintext secret. Shown once.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Invalid input — an unknown scope, or a malformed expiry." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "No store on the account is on the Advanced plan. `error.code` is `capability_not_available`; `error.details.cta.url` is the upgrade page." } }, "security": [ { "apiKey": [] }, { "accountJwt": [] } ] } }, "/account/api-keys/{key}/rotate": { "post": { "tags": [ "Authentication" ], "summary": "Rotate an account API key", "description": "Issues the replacement immediately and leaves the old key valid until\n`grace_until`, so a running deploy cannot be cut off mid-flight. Roll the new\nvalue out during the grace window, then let the old one lapse — or revoke it\nearly with `DELETE` if it leaked.", "operationId": "rotateAccountApiKey", "parameters": [ { "name": "key", "in": "path", "description": "The key `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotated. `key` is the new secret, shown once.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "key": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such key on this account." } }, "security": [ { "apiKey": [] }, { "accountJwt": [] } ] } }, "/account/api-keys/{key}": { "delete": { "tags": [ "Authentication" ], "summary": "Revoke an account API key", "description": "Takes effect immediately — there is no grace period here, which is the point:\nthis is the endpoint for a leaked key. The record is kept, with `revoked_at`\nset, so the audit trail survives the revocation.", "operationId": "revokeAccountApiKey", "parameters": [ { "name": "key", "in": "path", "description": "The key `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such key on this account." } }, "security": [ { "apiKey": [] }, { "accountJwt": [] } ] } }, "/account/api-keys/{key}/events": { "get": { "tags": [ "Authentication" ], "summary": "Audit trail for one account key", "description": "Every recorded use of the key, newest first: creation, rotation, revocation,\nand authentication attempts with the IP and route. This is where you look\nafter a suspected leak, and how you prove a key is genuinely unused before\nretiring it.", "operationId": "listAccountApiKeyEvents", "parameters": [ { "name": "key", "in": "path", "description": "The key `uuid`.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "Events, newest first." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such key on this account." } }, "security": [ { "apiKey": [] }, { "accountJwt": [] } ] } }, "/stores/{store}/api-keys": { "get": { "tags": [ "Authentication" ], "summary": "List one store's API keys", "operationId": "listStoreApiKeys", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keys.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Store not visible to this credential." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Authentication" ], "summary": "Create a store-scoped API key", "description": "`kind` decides where the key may live:\n\n- `store_secret` → `sk_live_…`, server only.\n- `store_publishable` → `pk_live_…`, safe in a browser bundle.\n\nA publishable key's default scopes are deliberately narrower than the legacy\nunauth token's, so it is not a drop-in replacement — read `scopes` on the\nresponse before swapping one for the other.\n\nThe `key` field beside the object is the only transmission of the secret.", "operationId": "createStoreApiKey", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "store_secret", "store_publishable" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "allowed_origins": { "description": "Recommended for publishable keys.", "type": "array", "items": { "type": "string" } }, "allowed_ips": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Created. `key` shown once.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "key": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Invalid input." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The store is not on the Advanced plan. `error.code` is `capability_not_available`; `error.details.current_tier` and `error.details.cta.url` say what it has and where to upgrade." }, "404": { "description": "Store not visible to this credential." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/api-keys/{key}/rotate": { "post": { "tags": [ "Authentication" ], "summary": "Rotate a store API key", "description": "Same grace-period contract as the account rotation: the old key keeps working until `grace_until`.", "operationId": "rotateStoreApiKey", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The key `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotated. `key` is the new secret, shown once.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "key": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such key on this store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/api-keys/{key}": { "delete": { "tags": [ "Authentication" ], "summary": "Revoke a store API key", "description": "Immediate, no grace period. The record is kept with `revoked_at` set so the audit trail survives.", "operationId": "revokeStoreApiKey", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The key `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such key on this store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/api-keys/{key}/events": { "get": { "tags": [ "Authentication" ], "summary": "Audit trail for one store key", "description": "Creation, rotation, revocation and authentication attempts with IP and route, newest first.", "operationId": "listStoreApiKeyEvents", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The key `uuid`.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "Events, newest first." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such key on this store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/storages": { "get": { "tags": [ "Templates" ], "summary": "List the store's categories", "description": "\"Storage\" is the API's word for a category node. The same `categories` table\nbacks product categories, clipart categories and template categories; the\n`type` column separates them.", "operationId": "listStorages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Create a category", "description": "Store a newly created resource in storage.", "operationId": "createStorage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" } } } }, "responses": { "201": { "description": "Category created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Storage" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/storages/default": { "get": { "tags": [ "Templates" ], "summary": "List the Printcart-curated categories", "description": "Display a listing of the resource.", "operationId": "listDefaultStorages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Curated categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/storages/{storage}": { "get": { "tags": [ "Templates" ], "summary": "Read a category", "description": "Display the specified resource.", "operationId": "getStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The category.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Storage" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a category", "description": "Update the specified resource in storage.", "operationId": "updateStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryUpdate" } } } }, "responses": { "200": { "description": "Updated category.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Storage" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/storages/count": { "get": { "tags": [ "Templates" ], "summary": "Count categories", "description": "Display count of the resource.", "operationId": "countStorages", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the cliparts available to this store", "description": "The `/cliparts` family stores cliparts as `Image` rows with `type=cliparts`,\nso the response is an `Image`, not a `Clipart`. The newer `/cliparts/mine`\nand `/cliparts/global` endpoints use a different table and return the\n`Clipart` shape instead — including a **numeric** id.", "operationId": "listCliparts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Cliparts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Fonts & assets" ], "summary": "Upload a clipart", "operationId": "uploadClipart", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ClipartUpload" } } } }, "responses": { "201": { "description": "Clipart stored.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Image" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/default": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the Printcart-curated cliparts", "description": "Get list cliparts default", "operationId": "listDefaultCliparts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Curated cliparts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/{clipart}": { "get": { "tags": [ "Fonts & assets" ], "summary": "Read a clipart", "description": "Display the specified resource.", "operationId": "getClipart", "parameters": [ { "name": "clipart", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The clipart.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Image" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Fonts & assets" ], "summary": "Update a clipart", "description": "Validated inline, so failures use Laravel's default **422** envelope.", "operationId": "updateClipart", "parameters": [ { "name": "clipart", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated clipart.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Image" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failed (Laravel default envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Fonts & assets" ], "summary": "Delete a clipart", "description": "Remove the specified resource from storage.", "operationId": "deleteClipart", "parameters": [ { "name": "clipart", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count cliparts", "description": "Display count of the resource.", "operationId": "countCliparts", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/default/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count the curated cliparts", "description": "Display count of the resource.", "operationId": "countDefaultCliparts", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/batch": { "post": { "tags": [ "Fonts & assets" ], "summary": "Upload several cliparts", "description": "Narrower than the single upload: only `svg` and `png` are accepted here,\nwhereas `POST /cliparts` also takes `jpg`, `jpeg` and `webp`.", "operationId": "uploadCliparts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ClipartBatchUpload" } } } }, "responses": { "201": { "description": "Cliparts stored.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages": { "get": { "tags": [ "Fonts & assets" ], "summary": "List clipart categories", "description": "Also served, identically, at `GET /clipart-categories`.", "operationId": "listClipartStorages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Fonts & assets" ], "summary": "Create a clipart category", "description": "Create Clipart Category", "operationId": "createClipartStorage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" } } } }, "responses": { "201": { "description": "Category created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Storage" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/default": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the curated clipart categories", "description": "Carries **no authentication middleware at all** — it is reachable without any\ncredential. That is deliberate (the curated library is public SEO surface),\nbut it means no entitlement badge fields are attached.", "operationId": "listDefaultClipartStorages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Curated categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [] } }, "/clipart-storages/{storage}": { "delete": { "tags": [ "Fonts & assets" ], "summary": "Delete a clipart category", "description": "Remove the specified resource from project folder.", "operationId": "deleteClipartStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/{storage}/cliparts": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the cliparts filed under a category", "description": "Display clipart of the resource.", "operationId": "listClipartsInStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Cliparts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/{storage}/cliparts-default": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the curated cliparts filed under a category", "description": "Display clipart of the resource.", "operationId": "listDefaultClipartsInStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Cliparts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/{clipart}/storages": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the categories a clipart is filed under", "description": "Display clipart of the resource.", "operationId": "listStoragesForClipart", "parameters": [ { "name": "clipart", "in": "path", "description": "Clipart UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/{clipart}/storages-default": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the curated categories a clipart is filed under", "description": "Display clipart of the resource.", "operationId": "listDefaultStoragesForClipart", "parameters": [ { "name": "clipart", "in": "path", "description": "Clipart UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/{storage}/cliparts/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count the cliparts in a category", "description": "Count Cliparts by Storage", "operationId": "countClipartsInStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/clipart-storages/{storage}/cliparts-default/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count the curated cliparts in a category", "description": "Count Cliparts by Storage Default", "operationId": "countDefaultClipartsInStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs": { "get": { "tags": [ "Designs" ], "summary": "List saved designs", "description": "Buyer-saved customizer documents.\n\nWhen the owning account is on the `free` tier every `designer` field except\n`name` comes back masked with `*`; `designer.is_pro` tells you which branch was\ntaken.", "operationId": "listDesigns", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Designs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Designs" ], "summary": "Save a design", "description": "The hinge of the whole flow: this is what the customizer calls when a buyer\nfinishes a design.\n\nAccepts either `multipart/form-data` with a `design_file`, or JSON referencing\na `design_image_id` uploaded earlier through `POST /images`. Exactly one of\n`side_id` / `product_id` is required, and exactly one of the two file inputs.\n\nIf no `project_id` is given a project is created implicitly, so a design always\nbelongs to something you can later turn into an order.\n\nA design file larger than the account plan allows is rejected with **400**\n(`Please upgrade your account.`), not 402.", "operationId": "createDesign", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DesignCreate" } } } }, "responses": { "201": { "description": "Design saved.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Design" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Validation failed, the file type is not allowed, or the file exceeds the plan limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List template designs", "description": "`/templates` is the same controller as `/designs`, filtered to rows flagged\n`is_template`. Request and response shapes are identical — including the field\nnames, which are `design_file` / `design_image_id` and **not** the\n`template_file` / `template_image_id` that `app/Http/Requests/Template/`\nsuggests (those rule classes are dead code and are never loaded).", "operationId": "listTemplateDesigns", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Template designs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Save a template design", "description": "`/templates` is the same controller as `/designs`, filtered to rows flagged\n`is_template`. Request and response shapes are identical — including the field\nnames, which are `design_file` / `design_image_id` and **not** the\n`template_file` / `template_image_id` that `app/Http/Requests/Template/`\nsuggests (those rule classes are dead code and are never loaded).", "operationId": "createTemplateDesign", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DesignCreate" } } } }, "responses": { "201": { "description": "Template design saved.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Design" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}": { "get": { "tags": [ "Designs" ], "summary": "Read a design", "description": "Display the specified resource.", "operationId": "getDesign", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The design.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Design" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Designs" ], "summary": "Update a design", "description": "Update the specified resource in storage.", "operationId": "updateDesign", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignUpdate" } } } }, "responses": { "200": { "description": "Updated design.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Design" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Designs" ], "summary": "Delete a design", "description": "Remove the specified resource from storage.", "operationId": "deleteDesign", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/templates/{design}": { "get": { "tags": [ "Templates" ], "summary": "Read a template design", "description": "`/templates` is the same controller as `/designs`, filtered to rows flagged\n`is_template`. Request and response shapes are identical — including the field\nnames, which are `design_file` / `design_image_id` and **not** the\n`template_file` / `template_image_id` that `app/Http/Requests/Template/`\nsuggests (those rule classes are dead code and are never loaded).", "operationId": "getTemplateDesign", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The template design.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Design" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a template design", "description": "`/templates` is the same controller as `/designs`, filtered to rows flagged\n`is_template`. Request and response shapes are identical — including the field\nnames, which are `design_file` / `design_image_id` and **not** the\n`template_file` / `template_image_id` that `app/Http/Requests/Template/`\nsuggests (those rule classes are dead code and are never loaded).", "operationId": "updateTemplateDesign", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignUpdate" } } } }, "responses": { "200": { "description": "Updated template design.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Design" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template design", "operationId": "deleteTemplateDesign", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/batch": { "put": { "tags": [ "Designs" ], "summary": "Update designs in bulk", "description": "Batch updated resource in storage.", "operationId": "updateDesigns", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignBatchUpdate" } } } }, "responses": { "200": { "description": "Designs updated.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Designs" ], "summary": "Save designs in bulk", "description": "Batch items also accept the photobook page fields (`book_id`, `side_role`,\n`sequence`, `spread_index`, `left_page_no`, `right_page_no`, `layout`), which\nare written onto the project item rather than the design.", "operationId": "createDesigns", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DesignBatchCreate" } } } }, "responses": { "201": { "description": "Designs saved.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Designs" ], "summary": "Delete designs in bulk", "description": "Batch delete resource in storage.", "operationId": "deleteDesigns", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteByIds" } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/templates/batch": { "put": { "tags": [ "Templates" ], "summary": "Update template designs in bulk", "operationId": "updateTemplateDesigns", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignBatchUpdate" } } } }, "responses": { "200": { "description": "Template designs updated.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Save template designs in bulk", "description": "`/templates` is the same controller as `/designs`, filtered to rows flagged\n`is_template`. Request and response shapes are identical — including the field\nnames, which are `design_file` / `design_image_id` and **not** the\n`template_file` / `template_image_id` that `app/Http/Requests/Template/`\nsuggests (those rule classes are dead code and are never loaded).", "operationId": "createTemplateDesigns", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DesignBatchCreate" } } } }, "responses": { "201": { "description": "Template designs saved.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete template designs in bulk", "operationId": "deleteTemplateDesigns", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteByIds" } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/count": { "get": { "tags": [ "Designs" ], "summary": "Count designs", "description": "Display count of the resource.", "operationId": "countDesigns", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/templates/count": { "get": { "tags": [ "Templates" ], "summary": "Count template designs", "operationId": "countTemplateDesigns", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}/generate/png": { "post": { "tags": [ "Designs" ], "summary": "Generate a PNG of the design", "description": "Rasterises the design, by way of the PDF renderer. Useful for thumbnails and\norder-confirmation emails.\n\nTakes no body — unlike the two PDF endpoints, there is no `reset` option.", "operationId": "generateDesignPng", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The rendered PNG reference.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "The design could not be rendered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "The renderer failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}/generate/pdf": { "post": { "tags": [ "Designs" ], "summary": "Generate the print-ready PDF", "description": "Renders the design at its stored geometry, including bleed and marks, and\nreturns a URL to the artefact.\n\nThe result is cached: repeat calls return the same file until you pass\n`{\"reset\": true}`, which forces a re-render. Rendering is synchronous and can\ntake several seconds on a complex design.", "operationId": "generateDesignPdf", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignGenerate" } } } }, "responses": { "200": { "description": "The rendered PDF reference.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "The design could not be rendered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "The renderer failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}/generate/preview-pdf": { "post": { "tags": [ "Designs" ], "summary": "Generate a low-resolution preview PDF", "description": "Same renderer as the print PDF but intended for on-screen proofing. Do not\nsend this file to a press.", "operationId": "generateDesignPreviewPdf", "parameters": [ { "name": "design", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignGenerate" } } } }, "responses": { "200": { "description": "The rendered preview reference.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "The design could not be rendered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "The renderer failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-groups": { "get": { "tags": [ "Templates" ], "summary": "List design groups", "description": "A design group bundles template designs so a storefront can offer them as a\nset. Also reachable at `/template-groups` (same controller, undocumented\nalias).", "operationId": "listDesignGroups", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Design groups.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DesignGroup" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Create a design group", "operationId": "createDesignGroup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignGroupCreate" } } } }, "responses": { "200": { "description": "Design group created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignGroup" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-groups/{designGroup}": { "get": { "tags": [ "Templates" ], "summary": "Read a design group", "description": "The single-group GET is the only response that includes `template_items`.", "operationId": "getDesignGroup", "parameters": [ { "name": "designGroup", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The design group.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignGroup" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a design group", "operationId": "updateDesignGroup", "parameters": [ { "name": "designGroup", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignGroupUpdate" } } } }, "responses": { "200": { "description": "Updated design group.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignGroup" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a design group", "operationId": "deleteDesignGroup", "parameters": [ { "name": "designGroup", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-groups/count": { "get": { "tags": [ "Templates" ], "summary": "Count design groups", "operationId": "countDesignGroups", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-template-categories": { "get": { "tags": [ "Templates" ], "summary": "List the design-template categories", "operationId": "listDesignTemplateCategories", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-template-categories/{storage}/design-templates": { "get": { "tags": [ "Templates" ], "summary": "List the design templates filed under a category", "operationId": "listDesignTemplatesInCategory", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Design templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DesignTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-template-categories/{storage}/design-templates/count": { "get": { "tags": [ "Templates" ], "summary": "Count the design templates in a category", "operationId": "countDesignTemplatesInCategory", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-template-categories/{storage}/categories": { "get": { "tags": [ "Templates" ], "summary": "List the categories a design template is filed under", "description": "As with the side-template equivalent, `{storage}` is really a design-template\nid.", "operationId": "listCategoriesForDesignTemplate", "parameters": [ { "name": "storage", "in": "path", "description": "Design template UUID, despite the parameter name.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates": { "get": { "tags": [ "Templates" ], "summary": "List this store's design templates", "description": "Design templates and side templates are the **same database table**\n(`side_templates`) presented under two names. A row created through\n`/side-templates` is visible here and vice versa.", "operationId": "listDesignTemplates", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Design templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DesignTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Create a design template", "operationId": "createDesignTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateContainerCreate" } } } }, "responses": { "201": { "description": "Design template created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates/global": { "get": { "tags": [ "Templates" ], "summary": "List the Printcart-curated design templates", "operationId": "listGlobalDesignTemplates", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Global design templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DesignTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates/{designTemplate}": { "get": { "tags": [ "Templates" ], "summary": "Read a design template", "operationId": "getDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The design template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a design template", "operationId": "updateDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateContainerUpdate" } } } }, "responses": { "200": { "description": "Updated design template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a design template", "operationId": "deleteDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates/global/{designTemplate}": { "get": { "tags": [ "Templates" ], "summary": "Read a global design template", "operationId": "getGlobalDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The design template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a global design template", "description": "Unlike the side-template equivalent, this route is **not** behind the `admin`\nmiddleware — any authenticated store may write to a curated design template.", "operationId": "updateGlobalDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateContainerUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a global design template", "description": "Also **not** behind the `admin` middleware, unlike its side-template twin.", "operationId": "deleteGlobalDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates/{designTemplate}/products": { "put": { "tags": [ "Templates" ], "summary": "Apply a design template to products", "operationId": "applyDesignTemplateToProducts", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateApplyToProducts" } } } }, "responses": { "200": { "description": "Applied.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates/global/{designTemplate}/products": { "put": { "tags": [ "Templates" ], "summary": "Apply a global design template to products", "operationId": "applyGlobalDesignTemplateToProducts", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateApplyToProducts" } } } }, "responses": { "200": { "description": "Applied.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/design-templates/{designTemplate}/publish": { "put": { "tags": [ "Templates" ], "summary": "Publish a design template", "operationId": "publishDesignTemplate", "parameters": [ { "name": "designTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateApplyToProducts" } } } }, "responses": { "200": { "description": "Published.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DesignTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/fonts": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the fonts available to this store", "description": "Display a listing of the resource.", "operationId": "listFonts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Fonts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Font" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Fonts & assets" ], "summary": "Add a font", "description": "Two shapes are accepted and the controller picks by whether a `file` part is\npresent:\n\n- `application/json` with `name` + `url` registers an externally hosted font.\n- `multipart/form-data` with `file` + `name` uploads a `ttf`/`otf`/`woff`/`woff2`\n and stores it on the CDN.\n\nUploads run through the media-quota guard, so they can return **402** when the\nstore is over its storage cap and the gate is in `hard` mode.", "operationId": "createFont", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FontCreate" } } } }, "responses": { "200": { "description": "Font registered.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Font" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/fonts/default": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the Printcart-curated fonts", "description": "List fonts default", "operationId": "listDefaultFonts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Curated fonts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Font" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/fonts/{font}": { "get": { "tags": [ "Fonts & assets" ], "summary": "Read a font", "description": "Display the specified resource.", "operationId": "getFont", "parameters": [ { "name": "font", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The font.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Font" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Fonts & assets" ], "summary": "Update a font", "description": "`url` cannot be changed. Delete and re-create to repoint a font.", "operationId": "updateFont", "parameters": [ { "name": "font", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FontUpdate" } } } }, "responses": { "200": { "description": "Updated font.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Font" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Fonts & assets" ], "summary": "Delete a font", "description": "Remove the specified resource from storage.", "operationId": "deleteFont", "parameters": [ { "name": "font", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/fonts/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count the fonts available to this store", "description": "Display count of the resource.", "operationId": "countFonts", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/fonts/default/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count the curated fonts", "description": "Display count of the resource.", "operationId": "countDefaultFonts", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/images": { "get": { "tags": [ "Fonts & assets" ], "summary": "List images", "description": "Display a listing of the resource.", "operationId": "listImages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Images.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Fonts & assets" ], "summary": "Upload an image", "description": "The buyer-facing upload path: accepts the public unauth token so a storefront\ncan upload artwork directly.\n\nA file larger than the account plan allows is rejected with **400**\n(`Please upgrade your account.`), not 402 — the plan check here predates the\nquota middleware and uses a different envelope.", "operationId": "uploadImage", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageUpload" } } } }, "responses": { "201": { "description": "Image stored.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Image" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Validation failed, or the file exceeds the plan limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/images/{image}": { "get": { "tags": [ "Fonts & assets" ], "summary": "Read an image", "description": "Note this single-image read requires store credentials even though the list\nendpoint accepts the public unauth token.", "operationId": "getImage", "parameters": [ { "name": "image", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The image.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Image" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Fonts & assets" ], "summary": "Delete an image", "description": "Remove the specified resource from storage.", "operationId": "deleteImage", "parameters": [ { "name": "image", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/images/batch": { "post": { "tags": [ "Fonts & assets" ], "summary": "Upload several images", "description": "Batch created resource in storage.", "operationId": "uploadImages", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageBatchUpload" } } } }, "responses": { "201": { "description": "Images stored.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Fonts & assets" ], "summary": "Delete several images", "description": "The body key is `images`; each element is `{ \"id\": \"\" }`.", "operationId": "deleteImages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteByIds" } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/images/count": { "get": { "tags": [ "Fonts & assets" ], "summary": "Count images", "description": "Display count of the resource.", "operationId": "countImages", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/images": { "get": { "tags": [ "Designs" ], "summary": "List images uploaded through the customizer", "description": "Buyer uploads, as opposed to merchant assets. Served by `ImageController`\ndespite sitting under `/designs`.", "operationId": "listDesignImages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Images.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/mine": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the cliparts this store uploaded", "description": "Backed by the `media_cliparts` table, not `images` — the `id` is numeric.", "operationId": "listStoreCliparts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Store cliparts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Clipart" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Fonts & assets" ], "summary": "Upload a clipart to the store library", "description": "Validated inline in the controller. Note that\n`app/Http/Requests/StoreMediaClipartRequest.php` describes a stricter\ncontract (2 MB, `category_id`, `tags[]`) but no route loads it — the rules\nactually in force are the ones documented on `StoreClipartUpload`.", "operationId": "uploadStoreClipart", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreClipartUpload" } } } }, "responses": { "201": { "description": "Clipart stored.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Clipart" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "The file could not be written to storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" }, "422": { "description": "Validation failed (Laravel default envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/mine/{clipart}": { "delete": { "tags": [ "Fonts & assets" ], "summary": "Delete a clipart from the store library", "description": "Remove a clipart only if it belongs to the authenticated store.", "operationId": "deleteStoreClipart", "parameters": [ { "name": "clipart", "in": "path", "description": "Numeric clipart id, not a UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted. Returns an empty body — unlike every other delete in the API, which returns 200 with a message." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/cliparts/global": { "get": { "tags": [ "Fonts & assets" ], "summary": "List the Printcart-curated clipart library", "description": "List Printcart-curated cliparts.", "operationId": "listGlobalCliparts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Global cliparts.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Clipart" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart/create": { "post": { "tags": [ "Fonts & assets" ], "summary": "Begin a multipart upload", "description": "For artwork too large to POST in one request. Three steps: `create`, then one\n`upload` call per part, then `complete`.\n\nEach part's bytes travel through this API on their way to S3, and there is\n**no abort endpoint** — an abandoned upload is left for S3 lifecycle rules to\nclean up.\n\nFor large files prefer `/multipart-uploads-v2/*`, which hands the client a\npresigned PUT URL per part (bytes go straight to S3, never through a PHP\nworker) and does have an abort endpoint. Note the different shape: V2 carries\nthe upload id in the **path**, this family takes it in the **body**.", "operationId": "startMultipartUpload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipartCreate" } } } }, "responses": { "201": { "description": "Upload started.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "upload_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" }, "415": { "description": "The `Content-Type` header was not accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart/upload": { "post": { "tags": [ "Fonts & assets" ], "summary": "Upload one part", "description": "Upload Parts", "operationId": "uploadMultipartPart", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MultipartPart" } } } }, "responses": { "200": { "description": "Part accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart/complete": { "post": { "tags": [ "Fonts & assets" ], "summary": "Finish a multipart upload", "description": "Assembles the parts and creates the `Image` record. The response carries the\nimage you can then reference as `design_image_id`.", "operationId": "completeMultipartUpload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipartComplete" } } } }, "responses": { "200": { "description": "Upload assembled.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Image" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart-uploads-v2/start": { "post": { "tags": [ "Fonts & assets" ], "summary": "Begin a presigned multipart upload", "description": "Opens an S3 multipart upload and returns one **presigned PUT URL per part**.\nUpload each part straight to its URL — the bytes never pass through this API\n— keep the `ETag` response header of each PUT, then post them all to\n`/multipart-uploads-v2/{uploadId}/complete`.\n\nPart sizes are S3's rules, not ours: every part except the last must be at\nleast 5 MB, and there can be at most 10000 of them.\n\nOnly `target_type: media_asset` is accepted today; completing the upload\ncreates a Media Asset V2 record. Fonts use `POST /fonts`.\n\nThe older `/multipart/*` family does the same job by proxying each part's\nbytes through this API, and takes the upload id in the body rather than the\npath. Prefer this one for large files.", "operationId": "startMultipartUploadV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "file_name", "file_size", "part_count" ], "properties": { "file_name": { "type": "string", "maxLength": 255, "example": "poster-artwork.pdf" }, "file_size": { "description": "Total size of the finished file in bytes.", "type": "integer", "minimum": 1, "example": 157286400 }, "part_count": { "description": "How many parts you intend to upload. One presigned URL is returned per part.", "type": "integer", "maximum": 10000, "minimum": 1, "example": 30 }, "mime_type": { "type": "string", "maxLength": 100, "example": "application/pdf" }, "target_type": { "type": "string", "enum": [ "media_asset" ], "example": "media_asset" }, "name": { "description": "Display name for the resulting asset. Defaults to file_name.", "type": "string", "maxLength": 255 }, "group_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Upload started; presigned part URLs returned.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "upload_id": { "description": "Pass this in the path of the part, complete and abort calls.", "type": "string", "format": "uuid" }, "parts": { "type": "array", "items": { "properties": { "part_number": { "type": "integer", "example": 1 }, "presigned_url": { "type": "string", "format": "uri" } }, "type": "object" } }, "expires_at": { "type": "string", "format": "date-time" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "target_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "part_count": { "type": "integer" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/StorageQuota" }, "422": { "$ref": "#/components/responses/MultipartV2Invalid" }, "502": { "$ref": "#/components/responses/MultipartV2StorageUnavailable" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart-uploads-v2/{uploadId}/parts": { "put": { "tags": [ "Fonts & assets" ], "summary": "Upload one part through the API", "description": "An **optional fallback** for clients that cannot PUT cross-origin to S3. The\npart's bytes travel through this API, so it carries the same cost the\npresigned flow exists to avoid — prefer the `presigned_url` returned by\n`start`.\n\nParts uploaded here are remembered server-side, so `complete` may be called\nwith an empty body.", "operationId": "uploadMultipartPartV2", "parameters": [ { "name": "uploadId", "in": "path", "description": "The `upload_id` returned by `start`.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "part_number", "file" ], "properties": { "part_number": { "type": "integer", "maximum": 10000, "minimum": 1 }, "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Part accepted and its ETag recorded.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "upload_id": { "type": "string", "format": "uuid" }, "part": { "properties": { "part_number": { "type": "integer" }, "etag": { "type": "string" }, "size_bytes": { "type": "integer" } }, "type": "object" }, "uploaded_parts": { "type": "integer" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/MultipartV2Invalid" }, "502": { "$ref": "#/components/responses/MultipartV2StorageUnavailable" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart-uploads-v2/{uploadId}/complete": { "post": { "tags": [ "Fonts & assets" ], "summary": "Finish a multipart upload", "description": "Assembles the parts into one object and creates the Media Asset.\n\nSend the `ETag` you got back from each presigned PUT, in `parts`. S3's own\ncasing (`PartNumber` / `ETag`) and snake case (`part_number` / `etag`) are\nboth accepted, and order does not matter. Keep the ETag exactly as the\nheader gave it, quotes included.\n\nIf every part was uploaded through `PUT {uploadId}/parts` instead, `parts`\nmay be omitted and the recorded ETags are used.\n\nCompleting an upload is final: a second call returns 404, as does a call\nagainst an aborted upload.", "operationId": "completeMultipartUploadV2", "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "parts": { "type": "array", "items": { "properties": { "PartNumber": { "type": "integer", "example": 1 }, "ETag": { "type": "string", "example": "\"9a0364b9e99bb480dd25e1f0284c8555\"" } }, "type": "object" } }, "name": { "description": "Overrides the display name given at start.", "type": "string" }, "group_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Object assembled and the media asset created.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "file_name": { "type": "string" }, "file_url": { "type": "string", "format": "uri" }, "preview_url": { "type": [ "string", "null" ], "format": "uri" }, "mime_type": { "type": "string" }, "file_size": { "type": "integer" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "group_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/MultipartV2Invalid" }, "502": { "$ref": "#/components/responses/MultipartV2StorageUnavailable" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/multipart-uploads-v2/{uploadId}": { "delete": { "tags": [ "Fonts & assets" ], "summary": "Abort a multipart upload", "description": "Discards the uploaded parts at S3 and marks the upload `aborted`. Call this\nwhen the user cancels — S3 charges for parts of an upload that is never\ncompleted or aborted.\n\nNo media asset is created and the upload can no longer be completed.", "operationId": "abortMultipartUploadV2", "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upload aborted.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "upload_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "aborted" ] } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/MultipartV2StorageUnavailable" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{productId}/prepress/apply-preset": { "post": { "tags": [ "Products" ], "summary": "Apply a size preset to a product", "description": "Writes a named industry size preset (US, EU, ISO, JP, square, slim, folded)\nonto the product as a prepress override, so a merchant picks \"US business\ncard\" instead of typing 88.9 x 50.8 by hand.\n\nList the available presets with `GET /prepress/presets`. Applying a preset\nreplaces the size keys only; bleed, marks and the rest of the product's\noverrides are left as they are.", "operationId": "applyPrepressPreset", "parameters": [ { "name": "productId", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "preset" ], "properties": { "preset": { "description": "Preset id, e.g. `us_3.5x2`.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Applied. Returns the product resolved config." }, "400": { "description": "Unknown preset id." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such product on this store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}/print-file": { "get": { "tags": [ "Designs" ], "summary": "Get the print PDF status for a design", "description": "Status of the design's print PDF and, when one is ready, a fresh signed download link. Never starts a render and never charges; use `POST /designs/{design}/print-file` for that. `status` is `stale` when the design changed after the file was rendered.", "operationId": "getDesignPrintFile", "parameters": [ { "name": "design", "in": "path", "description": "Design `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current state.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "render_id": { "description": "Render uuid. Null when the design has never been rendered.", "type": [ "string", "null" ], "format": "uuid" }, "design_id": { "type": "string", "format": "uuid" }, "status": { "description": "One of `rendering`, `ready`, `stale`, `failed`, or a \"no render yet\" state. `stale` means the file exists but the design changed after it was rendered.", "type": "string" }, "reused": { "description": "True when an existing render was returned instead of starting a new one.", "type": "boolean" }, "input_hash": { "type": [ "string", "null" ] }, "charged_tokens": { "description": "Tokens charged by this call. 0 on a reuse or a read.", "type": "integer" }, "rendered_at": { "type": [ "string", "null" ], "format": "date-time" }, "file": { "description": "Present once the render is ready.", "properties": { "filename": { "type": "string" }, "mime": { "type": "string", "example": "application/pdf" }, "bytes": { "type": [ "integer", "null" ] }, "pages": { "type": [ "integer", "null" ] }, "color_space": { "type": [ "string", "null" ] }, "icc": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "geometry": { "description": "Page geometry used for the render. Present once ready.", "type": [ "object", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "download_url": { "description": "Signed, short-lived link; fetching it answers 302 to a temporary storage URL. Null until the render is ready.", "type": [ "string", "null" ], "format": "uri" }, "download_url_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "order": { "description": "The order reference the render was bound to, if any.", "type": [ "object", "null" ] }, "stale": { "description": "Only present, and true, when `status` is `stale`.", "type": "boolean" }, "error_code": { "description": "Only present when `status` is `failed`.", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Design or print file not found on this store. Body: `{ success: false, message, code, data: null }`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Designs" ], "summary": "Ensure a print PDF exists for a design", "description": "Idempotent. Returns the render for the design's current input and starts one\nonly when none exists, so calling it twice never charges twice. Optionally\nbinds the render to an order line so the file stays reachable, and never turns\nstale, when the design is edited later.\n\n- **200**: the render is already `ready` (`reused` says whether it was found).\n- **202**: a render is in progress (`status: rendering`); poll\n `GET /designs/{design}/print-file` and honour `Retry-After`.\n- **402**: the wallet cannot cover the render (top-level `code: insufficient_tokens`).\n\nError bodies on this endpoint use `{ success, message, code, data }` with a\ntop-level `code`.", "operationId": "ensureDesignPrintFile", "parameters": [ { "name": "design", "in": "path", "description": "Design `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "order": { "description": "Binds the render to an order line.", "required": [ "platform", "order_id" ], "properties": { "platform": { "type": "string", "enum": [ "woocommerce", "shopify", "wix", "other" ] }, "order_id": { "type": "string", "maxLength": 64 }, "line_item_id": { "type": [ "string", "null" ], "maxLength": 64 } }, "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Render is ready.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "render_id": { "description": "Render uuid. Null when the design has never been rendered.", "type": [ "string", "null" ], "format": "uuid" }, "design_id": { "type": "string", "format": "uuid" }, "status": { "description": "One of `rendering`, `ready`, `stale`, `failed`, or a \"no render yet\" state. `stale` means the file exists but the design changed after it was rendered.", "type": "string" }, "reused": { "description": "True when an existing render was returned instead of starting a new one.", "type": "boolean" }, "input_hash": { "type": [ "string", "null" ] }, "charged_tokens": { "description": "Tokens charged by this call. 0 on a reuse or a read.", "type": "integer" }, "rendered_at": { "type": [ "string", "null" ], "format": "date-time" }, "file": { "description": "Present once the render is ready.", "properties": { "filename": { "type": "string" }, "mime": { "type": "string", "example": "application/pdf" }, "bytes": { "type": [ "integer", "null" ] }, "pages": { "type": [ "integer", "null" ] }, "color_space": { "type": [ "string", "null" ] }, "icc": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "geometry": { "description": "Page geometry used for the render. Present once ready.", "type": [ "object", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "download_url": { "description": "Signed, short-lived link; fetching it answers 302 to a temporary storage URL. Null until the render is ready.", "type": [ "string", "null" ], "format": "uri" }, "download_url_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "order": { "description": "The order reference the render was bound to, if any.", "type": [ "object", "null" ] }, "stale": { "description": "Only present, and true, when `status` is `stale`.", "type": "boolean" }, "error_code": { "description": "Only present when `status` is `failed`.", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" } } } }, "202": { "description": "Render in progress. `Retry-After: 5`.", "headers": { "Retry-After": { "schema": { "type": "string", "example": "5" } } }, "content": { "application/json": { "schema": { "properties": { "data": { "description": "Same shape as the 200 response, with `status: rendering`.", "type": "object" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Insufficient tokens. Top-level `code: insufficient_tokens`." }, "404": { "description": "Design or print file not found on this store. Body: `{ success: false, message, code, data: null }`." }, "422": { "description": "Invalid `order` block, or the design cannot be rendered (`code` says why)." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}/print-file/{render}": { "get": { "tags": [ "Designs" ], "summary": "Get one print PDF render", "description": "Status of one specific render and, when ready, a fresh signed link to that exact file. An order line keeps the render it was bound to, so its file does not turn stale when the design is edited afterwards. `data.current` says whether the design would still render to the same input today (informational).", "operationId": "getDesignPrintFileRender", "parameters": [ { "name": "design", "in": "path", "description": "Design `uuid`.", "required": true, "schema": { "type": "string" } }, { "name": "render", "in": "path", "description": "Render `uuid` (`data.render_id`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The render.", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Same shape as `GET /designs/{design}/print-file`, plus `current` (boolean).", "type": "object" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Design or print file not found on this store. Body: `{ success: false, message, code, data: null }`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/print-output": { "get": { "tags": [ "Products" ], "summary": "Get the store print-output settings", "description": "The store-level print-output defaults (bleed, colour space, marks) used by every product that has no override of its own.", "operationId": "getStorePrintOutput", "responses": { "200": { "description": "Current settings.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "print_output": { "description": "The settings stored at this level. Null when none are set here.", "type": [ "object", "null" ] }, "resolved_print_output": { "description": "The settings that actually apply after product, store, then default resolution.", "type": [ "object", "null" ] }, "source": { "description": "Where `resolved_print_output` came from.", "type": "string", "enum": [ "product", "store", "default", "side" ] }, "updated_at": { "description": "Revision token; send it back as `base_updated_at`.", "type": [ "string", "null" ] }, "capabilities": { "description": "Same document as `GET /print-output/capabilities`.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Set the store print-output settings", "description": "Replaces the store-level print-output settings. The whole `print_output` object is required; there is no partial update. Send `base_updated_at` to avoid overwriting a concurrent change.", "operationId": "updateStorePrintOutput", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "print_output" ], "properties": { "print_output": { "description": "Complete print-output settings. Every key is required and unknown keys are rejected. `GET /print-output/capabilities` lists the presets and values currently available.", "required": [ "version", "preset", "pdf_standard", "color_space", "icc_profile_id", "rendering_intent", "black_point_compensation", "bleed", "emit_trim_box", "emit_bleed_box", "cut_line_enabled" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "preset": { "type": "string", "enum": [ "cmyk_pdf", "rgb_pdf" ] }, "pdf_standard": { "type": "string", "enum": [ "none" ] }, "color_space": { "description": "Must match the preset.", "type": "string", "enum": [ "cmyk", "rgb" ] }, "icc_profile_id": { "description": "`fogra39` for CMYK, null for RGB.", "type": [ "string", "null" ], "example": "fogra39" }, "rendering_intent": { "type": [ "string", "null" ], "enum": [ "perceptual", "relative_colorimetric", "saturation", "absolute_colorimetric" ] }, "black_point_compensation": { "type": [ "boolean", "null" ] }, "bleed": { "description": "Each edge is at most 20 mm.", "required": [ "top", "right", "bottom", "left", "unit" ], "properties": { "top": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "bottom": { "type": "number", "minimum": 0 }, "left": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "enum": [ "mm", "in", "pt" ] } }, "type": "object" }, "emit_trim_box": { "type": "boolean" }, "emit_bleed_box": { "type": "boolean" }, "cut_line_enabled": { "type": "boolean" } }, "type": "object" }, "base_updated_at": { "description": "Optimistic concurrency. Send the `data.updated_at` you last read (null if none was set); a mismatch answers 409.", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Current settings.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "print_output": { "description": "The settings stored at this level. Null when none are set here.", "type": [ "object", "null" ] }, "resolved_print_output": { "description": "The settings that actually apply after product, store, then default resolution.", "type": [ "object", "null" ] }, "source": { "description": "Where `resolved_print_output` came from.", "type": "string", "enum": [ "product", "store", "default", "side" ] }, "updated_at": { "description": "Revision token; send it back as `base_updated_at`.", "type": [ "string", "null" ] }, "capabilities": { "description": "Same document as `GET /print-output/capabilities`.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "`base_updated_at` did not match. Body: `{ error: { code: \"PRINT_OUTPUT_CONFLICT\", reason: \"stale_base_updated_at\", server_updated_at } }`." }, "422": { "description": "Unknown field, missing key, or a value the renderer cannot honour. `errors` maps `print_output.` to a reason code: `required`, `unknown_field`, `invalid_type`, `invalid_enum`, `out_of_range`, `preset_conflict` or `unsupported_capability`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/print-output": { "get": { "tags": [ "Products" ], "summary": "Get a product print-output override", "description": "The product-level print-output override and the settings that resolve for it (product, else store, else default).", "operationId": "getProductPrintOutput", "parameters": [ { "name": "product", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current settings.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "print_output": { "description": "The settings stored at this level. Null when none are set here.", "type": [ "object", "null" ] }, "resolved_print_output": { "description": "The settings that actually apply after product, store, then default resolution.", "type": [ "object", "null" ] }, "source": { "description": "Where `resolved_print_output` came from.", "type": "string", "enum": [ "product", "store", "default", "side" ] }, "updated_at": { "description": "Revision token; send it back as `base_updated_at`.", "type": [ "string", "null" ] }, "capabilities": { "description": "Same document as `GET /print-output/capabilities`.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Set a product print-output override", "description": "Replaces the print-output override on one product. The whole `print_output` object is required. Send `base_updated_at` to avoid overwriting a concurrent change.", "operationId": "updateProductPrintOutput", "parameters": [ { "name": "product", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "print_output" ], "properties": { "print_output": { "description": "Complete print-output settings. Every key is required and unknown keys are rejected. `GET /print-output/capabilities` lists the presets and values currently available.", "required": [ "version", "preset", "pdf_standard", "color_space", "icc_profile_id", "rendering_intent", "black_point_compensation", "bleed", "emit_trim_box", "emit_bleed_box", "cut_line_enabled" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "preset": { "type": "string", "enum": [ "cmyk_pdf", "rgb_pdf" ] }, "pdf_standard": { "type": "string", "enum": [ "none" ] }, "color_space": { "description": "Must match the preset.", "type": "string", "enum": [ "cmyk", "rgb" ] }, "icc_profile_id": { "description": "`fogra39` for CMYK, null for RGB.", "type": [ "string", "null" ], "example": "fogra39" }, "rendering_intent": { "type": [ "string", "null" ], "enum": [ "perceptual", "relative_colorimetric", "saturation", "absolute_colorimetric" ] }, "black_point_compensation": { "type": [ "boolean", "null" ] }, "bleed": { "description": "Each edge is at most 20 mm.", "required": [ "top", "right", "bottom", "left", "unit" ], "properties": { "top": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "bottom": { "type": "number", "minimum": 0 }, "left": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "enum": [ "mm", "in", "pt" ] } }, "type": "object" }, "emit_trim_box": { "type": "boolean" }, "emit_bleed_box": { "type": "boolean" }, "cut_line_enabled": { "type": "boolean" } }, "type": "object" }, "base_updated_at": { "description": "Optimistic concurrency. Send the `data.updated_at` you last read (null if none was set); a mismatch answers 409.", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Current settings.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "print_output": { "description": "The settings stored at this level. Null when none are set here.", "type": [ "object", "null" ] }, "resolved_print_output": { "description": "The settings that actually apply after product, store, then default resolution.", "type": [ "object", "null" ] }, "source": { "description": "Where `resolved_print_output` came from.", "type": "string", "enum": [ "product", "store", "default", "side" ] }, "updated_at": { "description": "Revision token; send it back as `base_updated_at`.", "type": [ "string", "null" ] }, "capabilities": { "description": "Same document as `GET /print-output/capabilities`.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`base_updated_at` did not match. Body: `{ error: { code: \"PRINT_OUTPUT_CONFLICT\", reason: \"stale_base_updated_at\", server_updated_at } }`." }, "422": { "description": "Unknown field, missing key, or a value the renderer cannot honour. `errors` maps `print_output.` to a reason code: `required`, `unknown_field`, `invalid_type`, `invalid_enum`, `out_of_range`, `preset_conflict` or `unsupported_capability`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Remove a product print-output override", "description": "Removes the product override so the product falls back to the store settings. Responds 200 with the now-resolved settings (`print_output` is null). The only accepted body field is `base_updated_at`.", "operationId": "deleteProductPrintOutput", "parameters": [ { "name": "product", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "base_updated_at": { "description": "Optimistic concurrency token; a mismatch answers 409.", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Current settings.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "print_output": { "description": "The settings stored at this level. Null when none are set here.", "type": [ "object", "null" ] }, "resolved_print_output": { "description": "The settings that actually apply after product, store, then default resolution.", "type": [ "object", "null" ] }, "source": { "description": "Where `resolved_print_output` came from.", "type": "string", "enum": [ "product", "store", "default", "side" ] }, "updated_at": { "description": "Revision token; send it back as `base_updated_at`.", "type": [ "string", "null" ] }, "capabilities": { "description": "Same document as `GET /print-output/capabilities`.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`base_updated_at` did not match. Body: `{ error: { code: \"PRINT_OUTPUT_CONFLICT\", reason: \"stale_base_updated_at\", server_updated_at } }`." }, "422": { "description": "Unknown field, missing key, or a value the renderer cannot honour. `errors` maps `print_output.` to a reason code: `required`, `unknown_field`, `invalid_type`, `invalid_enum`, `out_of_range`, `preset_conflict` or `unsupported_capability`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/designs/{design}/generate/print-pdf": { "post": { "tags": [ "Designs" ], "summary": "Render a print-ready CMYK PDF for a design", "description": "The endpoint to send a printer. It renders the saved design through the CMYK\npipeline, producing a PDF with real `/TrimBox` and `/BleedBox`, and crop marks,\nregistration marks and a colour bar as configured.\n\n**This is not `POST /designs/{design}/generate/pdf`.** That one emits a\nplain page with no prepress geometry and is fine for a proof or a preview;\nit is not a press-ready file.\n\n**Geometry.** For a fixed-size product the page comes from the store or\nproduct prepress settings. For a canvas (the `canvas` prepress profile, or\n`geometry: \"side\"` in the body) the TrimBox is the print sheet the design's\nown side describes (`side_image_size`, with the face at `design_area`), the\ndesign is placed on the face, and a cut line is drawn as a vector path.\n`data.geometry` reports what was used.\n\n**Colour.** The renderer emits `ICCBased` CMYK with Coated FOGRA39 embedded,\nand nothing else. The store's `color_space` / `icc_profile` settings are\nforwarded; when they ask for something else the file is still CMYK FOGRA39\nand `warnings[]` says so. `data.requested_color_space` echoes the setting.\n\n**Cut line.** Process magenta (`#ff00ff`) through the CMYK transform, not a\nnamed `CutContour` spot colour: `data.geometry.cut_line.spot_color` is\n`false`. A RIP that keys on a named separation will not pick it up.\n\nSynchronous: a single-page design returns in seconds. `data.url` is a public,\npermanent CDN URL of the PDF, safe to store on an order; `?v=` changes on\nevery render.\n\n`warnings[]` is present when something was not honoured verbatim — a\ncrop-mark offset smaller than the bleed, a colour space the renderer cannot\nemit, a design whose shape matches neither face nor sheet, or the wrap band\ncarrying no artwork.", "operationId": "generatePrintReadyPdf", "parameters": [ { "name": "design", "in": "path", "description": "Design `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "geometry": { "description": "`side` sizes the page from the design side (canvas). Absent: `side` for the `canvas` profile, `prepress` otherwise.", "type": [ "string", "null" ], "enum": [ "side", "prepress" ] }, "cut_line": { "description": "Overrides the prepress cut-line settings for this render. Used only with side geometry.", "properties": { "enabled": { "type": "boolean" }, "position": { "description": "`sheet_edge` (default) is the outer edge of the staple margin; `staple_boundary` is where the back wrap meets the staple margin.", "type": "string", "enum": [ "sheet_edge", "staple_boundary" ] }, "staple_margin_in": { "description": "Inches. Read only for `staple_boundary`.", "type": "number", "format": "float", "maximum": 6, "minimum": 0 }, "weight_pt": { "description": "Stroke weight in points.", "type": "number", "format": "float", "maximum": 1, "minimum": 0.1 } }, "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Rendered.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "design_id": { "type": "string", "format": "uuid" }, "output_key": { "description": "Object key of the PDF. Stable per design — re-rendering overwrites in place.", "type": "string" }, "url": { "description": "Public CDN URL of the PDF. Does not expire.", "type": "string", "format": "uri" }, "url_expires_at": { "description": "Always null: the URL is public.", "type": [ "string", "null" ] }, "bytes": { "type": [ "integer", "null" ] }, "pages": { "type": "integer" }, "color_space": { "type": "string", "example": "ICCBased-CMYK (no_device_cs)" }, "icc": { "type": "string", "example": "Coated FOGRA39" }, "requested_color_space": { "description": "What the prepress settings asked for. The file is CMYK whatever this says.", "type": "string", "example": "rgb" }, "geometry": { "description": "`source` (`side` | `prepress`), `unit`, `trim`, `bleed`, and for a sheet `face`, `placement` and `cut_line` (`position`, `offset`, `weight_pt`, `color`, `spot_color`).", "type": "object" }, "warnings": { "description": "Values the renderer or the sheet composer clamped, ignored or could not provide. Empty when everything was honoured verbatim.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such design on this store." }, "422": { "description": "The design has no materialised print file yet, or its side cannot be turned into a print sheet (no physical unit, face outside the sheet, cut line inside the face)." }, "502": { "description": "The renderer failed. Safe to retry; the output key is stable." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/product-categories": { "get": { "tags": [ "Products" ], "summary": "List product categories", "description": "Returns the nested-set tree; `childs` is recursive and is `null` on leaves.", "operationId": "listProductCategories", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Products" ], "summary": "Create a product category", "description": "Create Product Category", "operationId": "createProductCategory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" } } } }, "responses": { "201": { "description": "Category created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Category" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/product-categories/default": { "get": { "tags": [ "Products" ], "summary": "List the Printcart-curated product categories", "description": "Display a listing of the resource.", "operationId": "listDefaultProductCategories", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Curated categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/product-categories/{storage}": { "delete": { "tags": [ "Products" ], "summary": "Delete a product category", "description": "Remove the specified resource from project folder.", "operationId": "deleteProductCategory", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "description": "Returns only top-level products: variant options are excluded, and rows whose\nstatus is `trashed` or `deleted` are hidden unless you ask for them by name via\n`?status=trashed`.\n\nResults are cached in Redis per store and per query-string, so a product\nchanged by another process can be up to one cache-flush stale.", "operationId": "listProducts", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" }, { "name": "status", "in": "query", "description": "Filter by status. Passing `trashed` or `deleted` switches the query to show only trashed rows.", "required": false, "schema": { "type": "string", "enum": [ "publish", "draft", "trashed", "deleted" ] } }, { "name": "is_parent", "in": "query", "description": "Restrict to products whose `parent_id` equals this value. Omit for top-level products.", "required": false, "schema": { "type": "string" } }, { "name": "has_side", "in": "query", "description": "Set to 1 to return only products that already have at least one side.", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "Products.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Products" ], "summary": "Create a product", "description": "The first step of the headless build path. A product on its own is not\nprintable — add at least one side before saving designs against it.\n\nSupplying an `integration_product_id` that already exists on this store returns\n**400 `Duplicate Product`** rather than 409.", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" } } } }, "responses": { "201": { "description": "Product created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Validation failed, or a product with this `integration_product_id` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "A referenced `product_image_id`, `category_ids` or `parent_id` does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}": { "get": { "tags": [ "Products" ], "summary": "Read a product", "description": "Single-product reads additionally include `image_galleries`, which the\ncollection omits.", "operationId": "getProduct", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Replace a product", "description": "`category_ids` and `image_gallery_ids` are **replace-all**: sending them wipes\nthe existing links first. Omit them to leave the links untouched.", "operationId": "updateProduct", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" } } } }, "responses": { "200": { "description": "Updated product.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "description": "Remove the specified resource from storage.", "operationId": "deleteProduct", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "patch": { "tags": [ "Products" ], "summary": "Partially update a product", "description": "Validated inline rather than by a Form Request, so a failure here returns\nLaravel's default **422**, unlike the 400 that `PUT /products/{product}`\nreturns for the same bad field.", "operationId": "patchProduct", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" } } } }, "responses": { "200": { "description": "Updated product.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failed (Laravel default envelope, not the API 400 envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/batch": { "put": { "tags": [ "Products" ], "summary": "Update products in bulk", "description": "If any id in the batch does not belong to this store the whole call fails with\n**404** naming the offending uuid; nothing is written.", "operationId": "updateProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBatchUpdate" } } } }, "responses": { "200": { "description": "Products updated.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "One of the supplied ids does not exist on this store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Products" ], "summary": "Create products in bulk", "description": "Inserts straight to the database rather than through the model, so model\nevents do not fire and defaults are filled in by the controller\n(`dimension_unit` defaults to `cm`, `status` to `publish`).\n\nBatch items take `metadata` and `request_quote_options` as **JSON-encoded\nstrings**, unlike the single-create endpoint which takes objects.", "operationId": "createProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBatchCreate" } } } }, "responses": { "201": { "description": "Products created.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete products in bulk", "description": "Batch delete resource in storage.", "operationId": "deleteProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteByIds" } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "One of the supplied ids does not exist on this store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/count": { "get": { "tags": [ "Products" ], "summary": "Count products", "description": "Display count of the resource.", "operationId": "countProducts", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/restores": { "get": { "tags": [ "Products" ], "summary": "Restore a trashed product", "description": "**This is a write behind a GET.** It un-deletes the product and sets its status\nback to `publish`. It is not safe to retry blindly from a crawler or a\nprefetching client.", "operationId": "restoreProduct", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Restored product.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/variants": { "get": { "tags": [ "Products" ], "summary": "List a product's variants", "description": "Get list products by integration product id", "operationId": "listProductVariants", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Variants.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/images": { "post": { "tags": [ "Products" ], "summary": "Attach an existing image to the product gallery", "description": "Takes an image **id**, not a file — upload through `POST /images` first.\nReturns 200 with the refreshed product, not 201.", "operationId": "attachProductImage", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductImageAttach" } } } }, "responses": { "200": { "description": "The product with its refreshed gallery.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`image_id` missing (inline validation, Laravel default envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/images/{image}": { "delete": { "tags": [ "Products" ], "summary": "Remove an image from the product gallery", "description": "Unlinks the image from the product. The image itself is not deleted.", "operationId": "detachProductImage", "parameters": [ { "name": "product", "in": "path", "description": "Product UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "image", "in": "path", "description": "Image UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/designs": { "get": { "tags": [ "Designs" ], "summary": "List the designs saved against a product", "description": "Get list designs by product", "operationId": "listProductDesigns", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Designs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/designs/count": { "get": { "tags": [ "Designs" ], "summary": "Count the designs saved against a product", "description": "Display count of the resource.", "operationId": "countProductDesigns", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/production-readiness": { "get": { "tags": [ "Products" ], "summary": "Check whether a product is ready to print", "description": "Reports what still has to be configured before the product can produce\nprint-ready output — missing sides, missing geometry, missing artwork. Useful\nas a pre-flight check in an onboarding wizard.\n\nThe payload is produced by `ProductReadinessService` and gains fields as new\nchecks are added; treat unknown keys as informational.", "operationId": "getProductReadiness", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Readiness report.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/sides": { "get": { "tags": [ "Sides" ], "summary": "List the sides of a product", "description": "Get list sides by product", "operationId": "listProductSides", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Sides.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{product}/sides/count": { "get": { "tags": [ "Sides" ], "summary": "Count the sides of a product", "description": "Display count of the resource.", "operationId": "countProductSides", "parameters": [ { "name": "product", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects (orders)", "description": "A project is Printcart's order object. When a store is connected to a\ncommerce platform, one platform order becomes one project.\n\nCommercial fields (`customer_email`, `total_price`, `currency`, …) are derived\nat read time from the free-form `order_detail` blob the integration wrote.\nProjects created directly through this API have no `order_detail` and will\nreport `null` for all of them.", "operationId": "listProjects", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Projects.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "Create a project", "description": "Pass `design_ids` to move existing designs into the new project in one call.\n\nThere is no way to set `order_detail`, a buyer, or any price through this\nendpoint — those are written only by the platform integrations.", "operationId": "createProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } } }, "responses": { "201": { "description": "Project created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Project" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "One of the supplied `design_ids` does not exist on this store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "503": { "description": "The order-notification email could not be queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}": { "get": { "tags": [ "Projects" ], "summary": "Read a project", "description": "The single-project read is the only response that embeds `project_items`, and\nthose items in turn embed their `designs`. This is the call to make when you\nwant everything needed to produce an order.", "operationId": "getProject", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Project" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Projects" ], "summary": "Update a project", "description": "Changing `status` can dispatch a buyer-facing status email, so do not use this\nendpoint to reconcile state in a loop.", "operationId": "updateProject", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdate" } } } }, "responses": { "200": { "description": "Updated project.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Project" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Projects" ], "summary": "Delete a project", "description": "Remove the specified resource from storage.", "operationId": "deleteProject", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/archive": { "put": { "tags": [ "Projects" ], "summary": "Archive a project", "description": "Archive the specified project.", "operationId": "archiveProject", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Archived project.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Project" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/batch": { "put": { "tags": [ "Projects" ], "summary": "Update projects in bulk", "description": "Batch updated resource in storage.", "operationId": "updateProjects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBatchUpdate" } } } }, "responses": { "200": { "description": "Projects updated.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "Create projects in bulk", "description": "Batch created resource in storage.", "operationId": "createProjects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBatchCreate" } } } }, "responses": { "201": { "description": "Projects created.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Projects" ], "summary": "Delete projects in bulk", "description": "Batch delete resource in storage.", "operationId": "deleteProjects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteByIds" } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/count": { "get": { "tags": [ "Projects" ], "summary": "Count projects", "description": "Display count of the resource.", "operationId": "countProjects", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/project-items": { "get": { "tags": [ "Projects" ], "summary": "List a project's line items", "description": "Because this path does not match `/projects/*` in the resource's own test,\nitems returned here carry `project`, `side` and `product` rather than\n`quantity` and `designs`. The same resource returns a different shape when it\nis embedded in `GET /projects/{project}`.", "operationId": "listProjectItems", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Project items.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectItem" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/designs": { "get": { "tags": [ "Projects" ], "summary": "List the designs in a project", "description": "Get list designs by project", "operationId": "listProjectDesigns", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Designs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/designs/count": { "get": { "tags": [ "Projects" ], "summary": "Count the designs in a project", "description": "Display count of the resource.", "operationId": "countProjectDesigns", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/events": { "get": { "tags": [ "Projects" ], "summary": "List a project's audit trail", "description": "**This endpoint paginates differently from every other list in the API.** It\nuses page-number pagination with a fixed page size of 20 and a `meta` block\ncarrying `total` / `current_page` / `last_page`. There is no `links` block and\nno `cursor` parameter.", "operationId": "listProjectEvents", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Events, newest page first.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEvent" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "Add a note to a project", "description": "The only event type you can create is a note: `event_type` is hard-coded to\n`note_added` and `actor_type` to `merchant`.\n\nValidated inline, so a missing `note` returns Laravel's default **422**, not\nthe API's usual 400.", "operationId": "createProjectEvent", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEventCreate" } } } }, "responses": { "201": { "description": "Note recorded. Note the response omits `metadata`, `actor_name`, `from_status` and `to_status` that the list endpoint returns.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProjectEvent" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`note` missing or longer than 1000 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-folder": { "get": { "tags": [ "Projects" ], "summary": "List project folders", "description": "Display a listing of the resource.", "operationId": "listProjectFolders", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Folders.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "File a project into a folder", "description": "Creates the link between a project and a category. Omitting `project_id`\ncreates an empty folder link rather than failing.", "operationId": "createProjectFolder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFolderCreate" } } } }, "responses": { "201": { "description": "Filed.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Storage" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-folder/{category}": { "delete": { "tags": [ "Projects" ], "summary": "Delete a project folder", "description": "Remove the specified resource from project folder.", "operationId": "deleteProjectFolder", "parameters": [ { "name": "category", "in": "path", "description": "Category UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-folder/{category}/projects": { "get": { "tags": [ "Projects" ], "summary": "List the projects in a folder", "description": "Get Projects By Folder", "operationId": "listProjectsInFolder", "parameters": [ { "name": "category", "in": "path", "description": "Category UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Projects.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-folder/{project}/folders": { "get": { "tags": [ "Projects" ], "summary": "List the folders a project is filed in", "description": "Get Folders By Project", "operationId": "listFoldersForProject", "parameters": [ { "name": "project", "in": "path", "description": "Project UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Folders.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-items/{project_item}": { "get": { "tags": [ "Projects" ], "summary": "Read a project item", "description": "Display the specified resource.", "operationId": "getProjectItem", "parameters": [ { "name": "project_item", "in": "path", "description": "Project item UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The project item.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProjectItem" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-items/{project_item}/products": { "get": { "tags": [ "Projects" ], "summary": "List the products behind a project item", "description": "Get Products By Project Items", "operationId": "listProjectItemProducts", "parameters": [ { "name": "project_item", "in": "path", "description": "Project item UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Products.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-items/{project_item}/sides": { "get": { "tags": [ "Projects" ], "summary": "List the sides behind a project item", "description": "Takes no pagination parameters — the full set is always returned.", "operationId": "listProjectItemSides", "parameters": [ { "name": "project_item", "in": "path", "description": "Project item UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sides.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/project-items/{project_item}/designs": { "get": { "tags": [ "Projects" ], "summary": "List the designs on a project item", "description": "Get Designs By Project Item", "operationId": "listProjectItemDesigns", "parameters": [ { "name": "project_item", "in": "path", "description": "Project item UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Designs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/products": { "get": { "tags": [ "Projects" ], "summary": "List the products in a project", "description": "Display a listing of the resource.", "operationId": "listProjectProducts", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Products.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/products/count": { "get": { "tags": [ "Projects" ], "summary": "Count the products in a project", "description": "Display count of the resource.", "operationId": "countProjectProducts", "parameters": [ { "name": "project", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/upload-summary": { "get": { "tags": [ "Projects" ], "summary": "Storefront upload intake counters", "description": "Counters for the store's storefront-upload intakes: how many wait on checkout, how many were received and converted in the last 7 days, and the month's usage against the plan limits. A `*_limit` of null means unlimited.", "operationId": "getUploadIntakeSummary", "responses": { "200": { "description": "Counters.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "awaiting": { "description": "Intakes awaiting checkout.", "type": "integer" }, "abandoned_7d": { "type": "integer" }, "received_7d": { "type": "integer" }, "converted_7d": { "type": "integer" }, "contacts_used_this_month": { "type": "integer" }, "contacts_limit": { "type": [ "integer", "null" ] }, "downloads_used_this_month": { "type": "integer" }, "downloads_limit": { "type": [ "integer", "null" ] } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/files": { "get": { "tags": [ "Projects" ], "summary": "List the buyer files of an upload intake", "description": "The files a buyer uploaded, each with a signed, short-lived download link. `download_url` is null and `download_locked` is true when the plan's monthly download quota is spent; `plan_gate` then names the limit.", "operationId": "listProjectUploadFiles", "parameters": [ { "name": "project", "in": "path", "description": "Project `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Files.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "description": "File key.", "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "preview_url": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ] }, "download_locked": { "type": "boolean" }, "plan_gate": { "type": [ "object", "null" ] } }, "type": "object" } }, "meta": { "properties": { "downloads_used_this_month": { "type": "integer" }, "downloads_limit": { "type": [ "integer", "null" ] } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/projects/{project}/upload-review": { "post": { "tags": [ "Projects" ], "summary": "Accept or decline a buyer upload", "description": "Records the merchant's decision on a storefront upload intake and updates the linked designs. On paid stores the buyer is also emailed (`email_sent`); on Free the decision is recorded and `plan_gate` names the upgrade needed for the email. Only projects created by an upload intake qualify.", "operationId": "reviewProjectUpload", "parameters": [ { "name": "project", "in": "path", "description": "Project `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accept", "decline" ] }, "reason": { "description": "Shown to the buyer on decline.", "type": [ "string", "null" ], "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Decision recorded.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Project" }, "plan_gate": { "description": "`{ feature: \"upload_review_emails\", required_plan: \"premium\" }` when the buyer email was skipped because of the plan.", "type": [ "object", "null" ] }, "email_sent": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Invalid `decision` or `reason`. Body: `{ error: { field: [messages] }, message: \"Invalid input\" }`. **HTTP 422 here, not 400.**" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/upload-settings": { "get": { "tags": [ "Stores" ], "summary": "Get the storefront upload form and notification settings", "description": "Settings for the storefront upload form (phone, note and consent fields) and for the merchant notifications an upload triggers. Unset keys return their defaults.", "operationId": "getStoreUploadSettings", "responses": { "200": { "description": "Settings.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "form": { "properties": { "phone": { "type": "string", "enum": [ "hidden", "optional", "required" ] }, "note": { "description": "Show the free-text note field.", "type": "boolean" }, "require_consent": { "type": "boolean" }, "consent_text": { "type": [ "string", "null" ] } }, "type": "object" }, "notify": { "properties": { "mode": { "type": "string", "enum": [ "immediate", "hourly", "daily" ] }, "extra_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "buyer_reminder": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Stores" ], "summary": "Update the storefront upload form and notification settings", "description": "Partial update: send only the keys to change; anything omitted keeps its current value. `notify.extra_recipients` is a list and is replaced as a whole, never merged.", "operationId": "updateStoreUploadSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "form": { "properties": { "phone": { "type": "string", "enum": [ "hidden", "optional", "required" ] }, "note": { "type": "boolean" }, "require_consent": { "type": "boolean" }, "consent_text": { "type": [ "string", "null" ], "maxLength": 500 } }, "type": "object" }, "notify": { "properties": { "mode": { "type": "string", "enum": [ "immediate", "hourly", "daily" ] }, "extra_recipients": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 190 }, "maxItems": 5 }, "buyer_reminder": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "The settings after the update.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "form": { "properties": { "phone": { "type": "string", "enum": [ "hidden", "optional", "required" ] }, "note": { "description": "Show the free-text note field.", "type": "boolean" }, "require_consent": { "type": "boolean" }, "consent_text": { "type": [ "string", "null" ] } }, "type": "object" }, "notify": { "properties": { "mode": { "type": "string", "enum": [ "immediate", "hourly", "daily" ] }, "extra_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "buyer_reminder": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Invalid value. Body: `{ error: { field: [messages] }, message: \"Invalid input\" }`. **HTTP 422 here, not 400.**" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/sides": { "get": { "tags": [ "Sides" ], "summary": "List sides", "description": "Display a listing of the resource.", "operationId": "listSides", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Sides.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Sides" ], "summary": "Create a print side", "description": "A side is the printable surface — front, back, inner page. It carries the\ngeometry that makes output print-ready: the design area, the bleed\n(`cut_line_margin`) and the safe zone (`safe_zone_margin`).\n\nGeometry is expressed in the owning product's `dimension_unit`. `scale` is\npixels per unit and is what the customizer uses to map canvas coordinates onto\nphysical size — get it wrong and the PDF comes out the wrong size.", "operationId": "createSide", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideCreate" } } } }, "responses": { "201": { "description": "Side created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Side" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The referenced `product_id` or image does not exist on this store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/sides/{side}": { "get": { "tags": [ "Sides" ], "summary": "Read a side", "description": "Display the specified resource.", "operationId": "getSide", "parameters": [ { "name": "side", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The side.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Side" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Sides" ], "summary": "Update a side", "description": "Changing geometry does **not** re-render designs already saved against this\nside: each design keeps a snapshot in `original_side`, so existing artwork\nstays reproducible at its original dimensions.", "operationId": "updateSide", "parameters": [ { "name": "side", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideUpdate" } } } }, "responses": { "200": { "description": "Updated side.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Side" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Sides" ], "summary": "Delete a side", "description": "Remove the specified resource from storage.", "operationId": "deleteSide", "parameters": [ { "name": "side", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/sides/batch": { "put": { "tags": [ "Sides" ], "summary": "Update sides in bulk", "description": "Batch updated resource in storage.", "operationId": "updateSides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideBatchUpdate" } } } }, "responses": { "200": { "description": "Sides updated.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Sides" ], "summary": "Create sides in bulk", "description": "Batch created resource in storage.", "operationId": "createSides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideBatchCreate" } } } }, "responses": { "201": { "description": "Sides created.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Sides" ], "summary": "Delete sides in bulk", "description": "Batch delete resource in storage.", "operationId": "deleteSides", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteByIds" } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/sides/count": { "get": { "tags": [ "Sides" ], "summary": "Count sides", "description": "Display count of the resource.", "operationId": "countSides", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/sides/apply-sides-products": { "post": { "tags": [ "Sides" ], "summary": "Copy a set of sides onto other products", "description": "Used when a variant family should share one side layout. Copies the named\nsides from `product_parent_id` onto every product in `product_ids`.", "operationId": "applySidesToProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideApplyToProducts" } } } }, "responses": { "201": { "description": "Sides copied.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/sides/{side}/children-sides": { "put": { "tags": [ "Sides" ], "summary": "Push a side's geometry down to child products", "description": "`product_ids` is validated as a **string** here, not an array — send a\ncomma-separated list. That is inconsistent with every other endpoint that\ntakes product ids.", "operationId": "propagateSideToChildren", "parameters": [ { "name": "side", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideApplyToChildren" } } } }, "responses": { "200": { "description": "Updated sides.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{productId}/sides/import-from-template": { "post": { "tags": [ "Sides" ], "summary": "Create a side on a product from a side template", "description": "The fastest way to get a printable product: pick a curated side template and\nstamp it onto your product, geometry and all.\n\nReturns **409** when the product already has a side imported from this same\ntemplate.", "operationId": "importSideFromTemplate", "parameters": [ { "name": "productId", "in": "path", "description": "Product UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideImportFromTemplate" } } } }, "responses": { "201": { "description": "Side created from the template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Side" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "This template has already been imported onto this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The import failed part-way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates": { "get": { "tags": [ "Templates" ], "summary": "List this store's side templates", "description": "Display a listing of the resource.", "operationId": "listSideTemplates", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Side templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SideTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Create a side template", "description": "Store a newly created resource in storage.", "operationId": "createSideTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateContainerCreate" } } } }, "responses": { "201": { "description": "Side template created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/global": { "get": { "tags": [ "Templates" ], "summary": "List the Printcart-curated side templates", "description": "The curated library a merchant imports from. Items carry the entitlement badge\nfields (`tier_required`, `store_qualified`, `badge`) so a UI can mark premium\ncontent — but nothing is hidden and every item returns a usable preview.", "operationId": "listGlobalSideTemplates", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Global side templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SideTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/global/recommended": { "get": { "tags": [ "Templates" ], "summary": "List recommended global side templates", "description": "Filtered by the `wix_recommended` flag; the naming is a leftover from the Wix\nintegration but the endpoint is platform-neutral.", "operationId": "listRecommendedSideTemplates", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Recommended templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SideTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/{sideTemplate}": { "get": { "tags": [ "Templates" ], "summary": "Read a side template", "description": "Single reads include the nested `sides`; the collection does not.", "operationId": "getSideTemplate", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The side template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Templates" ], "summary": "Update a side template", "description": "Update the specified resource in storage.", "operationId": "updateSideTemplate", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateContainerUpdate" } } } }, "responses": { "200": { "description": "Updated side template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a side template", "description": "Remove the specified resource from storage.", "operationId": "deleteSideTemplate", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "patch": { "tags": [ "Templates" ], "summary": "Update a side template (PATCH alias)", "description": "Routed to the same controller method as `PUT`, with the same Form Request and\nthe same semantics. There is no partial-update behaviour distinct from `PUT`\nhere.", "operationId": "patchSideTemplate", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateContainerUpdate" } } } }, "responses": { "200": { "description": "Updated side template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/global/{sideTemplate}": { "get": { "tags": [ "Templates" ], "summary": "Read a global side template", "description": "Display the specified resource.", "operationId": "getGlobalSideTemplate", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The side template.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/{sideTemplate}/products": { "put": { "tags": [ "Templates" ], "summary": "Apply a side template to products", "description": "Also the asset-contribution endpoint: the optional `license`, `source_url`,\n`copyright_holder`, `contribution_note` and `idempotency_key` fields record\nprovenance when a merchant offers a template back to the curated library.\n\nThis is the **only** Wave-1 endpoint that honours an idempotency key, and it\nreads it from the JSON body rather than a header. It can answer **202** when\nthe contribution is queued for review rather than applied immediately.", "operationId": "applySideTemplateToProducts", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideTemplateContribute" } } } }, "responses": { "200": { "description": "Applied.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "202": { "description": "Contribution accepted for review.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/global/{sideTemplate}/products": { "put": { "tags": [ "Templates" ], "summary": "Apply a global side template to products", "description": "Apply a global side template to multiple products.\nReturns per-product batch result (HTTP 207 when any product fails).\nSupports idempotency: products that already have sides cloned from this\ntemplate are counted as applied without duplicating them.", "operationId": "applyGlobalSideTemplateToProducts", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateApplyToProducts" } } } }, "responses": { "200": { "description": "Applied.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/global/{sideTemplate}/collections": { "post": { "tags": [ "Templates" ], "summary": "Apply a global side template to a product collection", "description": "Apply a global side template to all products in a Wix collection.\nSynchronous for <= 200 products; returns 202 + job_id for larger sets.\n\nPOST /v1/side-templates/global/{id}/collections", "operationId": "applyGlobalSideTemplateToCollection", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Applied.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/{sideTemplate}/publish": { "put": { "tags": [ "Templates" ], "summary": "Publish a side template", "description": "Update product side", "operationId": "publishSideTemplate", "parameters": [ { "name": "sideTemplate", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SideTemplateContribute" } } } }, "responses": { "200": { "description": "Published.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SideTemplate" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-templates/global/{template_id}/products/{product_id}": { "delete": { "tags": [ "Templates" ], "summary": "Unlink a global side template from a product", "description": "Detach global template source metadata from a product side WITHOUT deleting the clone.\n\nDELETE /v1/side-templates/global/{template_id}/products/{product_id}", "operationId": "unlinkSideTemplateFromProduct", "parameters": [ { "name": "template_id", "in": "path", "description": "Side template UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "product_id", "in": "path", "description": "Product UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Unlinked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-template-storages": { "get": { "tags": [ "Templates" ], "summary": "List the side-template categories", "operationId": "listSideTemplateStorages", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-template-storages/{storage}/side-templates": { "get": { "tags": [ "Templates" ], "summary": "List the side templates filed under a category", "description": "Get Side Templates by Storage", "operationId": "listSideTemplatesInStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Side templates.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SideTemplate" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-template-storages/{storage}/side-templates/count": { "get": { "tags": [ "Templates" ], "summary": "Count the side templates in a category", "description": "Count Side Templates by Storage", "operationId": "countSideTemplatesInStorage", "parameters": [ { "name": "storage", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/side-template-storages/{storage}/storages": { "get": { "tags": [ "Templates" ], "summary": "List the categories a side template is filed under", "description": "The `{storage}` path segment is really a **side-template** id here, not a\ncategory id — the route parameter name is wrong.", "operationId": "listStoragesForSideTemplate", "parameters": [ { "name": "storage", "in": "path", "description": "Side template UUID, despite the parameter name.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "Categories.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/publish/channels": { "get": { "tags": [ "Stores" ], "summary": "List publish channels", "description": "The channels a product listing can be exported for, and the fields each format cannot carry. Publishing is export-only today: Printcart produces an import file and the merchant uploads it to the channel; nothing calls Shopify, Wix or WooCommerce from here (`meta.transport: \"export\"`).", "operationId": "listPublishChannels", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`. Must be the authenticated store.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channels.", "content": { "application/json": { "schema": { "properties": { "data": { "description": "One entry per exporter, including its format and unsupported fields.", "type": "array", "items": { "type": "object" } }, "meta": { "properties": { "transport": { "type": "string", "example": "export" }, "note": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The `{store}` path segment is not the authenticated store. Body: `{ error: { message } }`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/publish/preview": { "post": { "tags": [ "Stores" ], "summary": "Preview the publish payload for products", "description": "Builds the channel-neutral listing payload for each product without exporting anything, with a `readiness` block saying whether the product is ready to publish.", "operationId": "previewPublish", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`. Must be the authenticated store.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "product_ids": { "description": "Product `uuid`s (parent products only; at most 100 are used). Omitted or empty: the store's POD-linked products.", "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Payloads.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "description": "A listing payload; `readiness.ready` says whether it can be exported.", "type": "object" } }, "meta": { "properties": { "count": { "type": "integer" }, "ready": { "description": "How many payloads are ready.", "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The `{store}` path segment is not the authenticated store. Body: `{ error: { message } }`." }, "404": { "description": "No matching product for this store." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/publish/export": { "post": { "tags": [ "Stores" ], "summary": "Export products as a channel import file", "description": "Produces the import file for one channel and returns it inline as a string in `data.content`, together with the products that were skipped and why, so the merchant sees what did NOT make it into the file before uploading it. Each call is recorded as a publish run (`GET /stores/{store}/publish/runs`).", "operationId": "exportPublish", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`. Must be the authenticated store.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channel" ], "properties": { "channel": { "description": "A key from `GET /stores/{store}/publish/channels` (`shopify`, `woocommerce`, `wix`, `generic`).", "type": "string" }, "product_ids": { "description": "Product `uuid`s (parent products only; at most 100 are used). Omitted or empty: the store's POD-linked products.", "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "The export.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "channel": { "type": "string" }, "format": { "type": "string" }, "filename": { "type": "string" }, "content": { "description": "The file body.", "type": "string" }, "checksum": { "description": "SHA-256 of `content`.", "type": "string" }, "exported_product_ids": { "type": "array", "items": { "type": "string" } }, "skipped": { "description": "Products left out of the file, with the reason.", "type": "array", "items": { "type": "object" } }, "unsupported_fields": { "description": "Fields this format cannot carry.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "meta": { "properties": { "exported_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "transport": { "type": "string", "example": "export" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The `{store}` path segment is not the authenticated store. Body: `{ error: { message } }`." }, "404": { "description": "No matching product for this store." }, "422": { "description": "Unknown `channel` (the message lists the available ones), or the exporter rejected the products." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/publish/mappings": { "get": { "tags": [ "Stores" ], "summary": "List published product mappings", "description": "What this store believes is listed where, newest first: one row per product and channel with the channel's own product id and the price it was published at. Page-number pagination, not cursor.", "operationId": "listPublishMappings", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`. Must be the authenticated store.", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "maximum": 100 } }, { "name": "channel", "in": "query", "description": "Filter by channel key.", "required": false, "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "description": "Filter by product `uuid`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mappings.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "channel": { "type": "string" }, "publish_status": { "type": "string" }, "product": { "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "channel_product_id": { "type": [ "string", "null" ] }, "published_price": { "type": [ "string", "null" ] }, "currency_code": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The `{store}` path segment is not the authenticated store. Body: `{ error: { message } }`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/publish/runs": { "get": { "tags": [ "Stores" ], "summary": "List publish runs", "description": "Every export attempt for the store, newest first. The audit trail behind `POST /stores/{store}/publish/export`. Page-number pagination, not cursor.", "operationId": "listPublishRuns", "parameters": [ { "name": "store", "in": "path", "description": "Store `uuid`. Must be the authenticated store.", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "maximum": 100 } }, { "name": "channel", "in": "query", "description": "Filter by channel key.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Runs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "channel": { "type": "string" }, "status": { "type": "string" }, "transport": { "type": "string" }, "format": { "type": [ "string", "null" ] }, "row_count": { "type": [ "integer", "null" ] }, "byte_size": { "type": [ "integer", "null" ] }, "checksum": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "product": { "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The `{store}` path segment is not the authenticated store. Body: `{ error: { message } }`." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores": { "get": { "tags": [ "Stores" ], "summary": "List the stores on this account", "description": "JWT only — store credentials cannot list stores, because a store credential\nis scoped to exactly one store.\n\nAdd `?include=credentials` to have each store's `sid` and `secret` returned;\nthat is how a provisioning script bootstraps a new store's keys.", "operationId": "listStores", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Stores owned by the account.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "accountJwt": [] } ] }, "put": { "tags": [ "Stores" ], "summary": "Update the current store", "description": "Update the specified resource in storage.", "operationId": "updateStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUpdate" } } } }, "responses": { "200": { "description": "Updated store.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Store" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Stores" ], "summary": "Create a store", "description": "Generates the store's `sid`, `secret` and `unauth_access_token`. **The\nresponse is the only time the secret is returned without an explicit\n`include=credentials` opt-in — capture it here.**\n\nRequires a JWT. A server-side integration that only holds an existing store's\n`sid:secret` can mint the JWT it needs via `GET /account/render-jwt`.", "operationId": "createStore", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCreate" } } } }, "responses": { "201": { "description": "Store created, with credentials.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Store" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "accountJwt": [] } ] }, "delete": { "tags": [ "Stores" ], "summary": "Soft-delete the current store", "description": "Deletes the store the credential belongs to. There is no confirmation step and\nno store id in the path — the credential itself selects the target.", "operationId": "deleteStore", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/store-details": { "get": { "tags": [ "Stores" ], "summary": "Read the current store", "description": "Resolves the store from whichever credential was supplied — there is no store\nid in the path.\n\nWhen called with Basic `sid:secret` this endpoint returns the full credential\nset **without** needing `?include=credentials`; that legacy exception exists\nonly here. An `X-PrintCart-Unauth-Token` caller gets the public fields only.", "operationId": "getStore", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated. `credentials` (or `api_credentials`) adds the store keys. Ignored for unauth-token callers.", "required": false, "schema": { "type": "string", "example": "credentials" } } ], "responses": { "200": { "description": "The store.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Store" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "unauthToken": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/profile": { "put": { "tags": [ "Stores" ], "summary": "Update the public brand profile", "description": "`shop_url` is required on every call even when you are only changing, say,\nthe tagline. Send the current value back if you are not changing it.\n\n`locations` and `category_ids` replace the whole set rather than merging.", "operationId": "updateStoreProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProfileUpdate" } } } }, "responses": { "200": { "description": "Updated store profile.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Store" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "The chosen `slug` is already taken by another store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/{store}/profile": { "put": { "tags": [ "Stores" ], "summary": "Update the public brand profile of a named store", "description": "Identical to `PUT /stores/profile` — the same controller method, and the\n`{store}` segment is **not** used to select the store. The store is still\nresolved from the credential. Prefer the credential-scoped path.", "operationId": "updateStoreProfileById", "parameters": [ { "name": "store", "in": "path", "description": "Store UUID. Accepted but ignored; the credential decides which store is written.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProfileUpdate" } } } }, "responses": { "200": { "description": "Updated store profile.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Store" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/token-revoke": { "put": { "tags": [ "Stores" ], "summary": "Rotate the store credentials", "description": "Issues a new `sid`, `secret` and `unauth_access_token` for the current store.\n\n**This is immediate and total.** The previous credentials stop working the\ninstant this returns, including the unauth token embedded in any storefront\nbundle. There is no overlap window and no way to revoke just one of the three.\nPlan a deploy of the new public token at the same time.", "operationId": "rotateStoreCredentials", "responses": { "200": { "description": "New credentials.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Store" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/prepress-workflow": { "get": { "tags": [ "Stores" ], "summary": "Read the store prepress defaults", "description": "The store-level prepress config: trim size, bleed, safe zone, and which\nprinter's marks to emit. Always returns a complete, valid, schema-stamped\nobject even when nothing has ever been saved — the defaults are filled in\nserver-side so the customizer never has to guess.", "operationId": "showStorePrepressWorkflow", "responses": { "200": { "description": "Resolved config plus its provenance." }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Stores" ], "summary": "Update the store prepress defaults", "description": "Sparse update — send only the keys you are changing. Unknown keys are\nrejected rather than ignored, so a typo fails loudly instead of silently\ndoing nothing.\n\nPass `base_updated_at` from the last read to get optimistic locking: if\nsomeone else saved in the meantime the call returns **409** with the current\nserver config, rather than overwriting their change.", "operationId": "updateStorePrepressWorkflow", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Saved. Returns the newly resolved config." }, "400": { "description": "Invalid input — unknown key, or a value outside its allowed range." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Someone else saved first. The current server config is in the body." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/products/{productId}/prepress-workflow": { "get": { "tags": [ "Products" ], "summary": "Read the resolved prepress config for one product", "description": "The store defaults with this product's overrides merged on top, key by key.\nThis is the endpoint the customizer reads: the geometry block it returns\n(trim, bleed, safe area, media size, marks gutter) is computed server-side on\npurpose, so the canvas and the renderer cannot drift apart.", "operationId": "showProductPrepressWorkflow", "parameters": [ { "name": "productId", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved config, geometry and provenance." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such product on this store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Override prepress settings for one product", "description": "Only product-scoped keys are accepted here. Store-scoped keys are dropped\nwith a note in `warnings[]` rather than failing the request — the same\ncontract the photobook workflow uses.\n\nSupports `base_updated_at` optimistic locking, as the store endpoint does.", "operationId": "updateProductPrepressWorkflow", "parameters": [ { "name": "productId", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Saved. Returns the resolved config and any warnings." }, "400": { "description": "Invalid input." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such product on this store." }, "409": { "description": "Someone else saved first." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Clear a product prepress override", "description": "Removes the product-level layer so the product falls back to the store defaults. The store config is untouched.", "operationId": "clearProductPrepressWorkflow", "parameters": [ { "name": "productId", "in": "path", "description": "Product `uuid`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cleared. Returns the config the product now resolves to." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such product on this store." } }, "security": [ { "apiKey": [] }, { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/stores/subscription": { "get": { "tags": [ "Stores" ], "summary": "The acting store's app subscription and payment history", "description": "Subscription state and payment history for the store the credentials belong\nto, whichever platform billed it — Wix, Shopify, WooCommerce or PayPal.\n\nRead `is_entitled` to decide whether to unlock paid behaviour. Do not infer\nit from `status`: a subscription whose auto-renewal was cancelled still\ncarries entitlement until `billing_on`, and treating `cancelled` as \"no\nlonger paying\" locks out a merchant who has paid through the end of the\nperiod.\n\nThe route takes no store identifier. The subject is always the\nauthenticated store, so there is no parameter that could reach another\nmerchant's billing.\n\n`payments` is newest-first and capped by `limit` (default 50, max 100). A\nstore that has never paid gets an empty list, not an error.", "operationId": "showStoreSubscription", "parameters": [ { "name": "limit", "in": "query", "description": "How many payment records to return. 1–100, default 50.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Subscription state and payment history.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "store": { "description": "Store name and the platform it is installed on.", "type": "object" }, "subscription": { "description": "status, is_entitled, tier, source, plan, activated_on, billing_on, renews_on, expires_on, auto_renew.", "type": "object" }, "payments": { "description": "Payment history, newest first.", "type": "array", "items": { "type": "object" } }, "payments_count": { "description": "How many records were returned.", "type": "integer" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Invalid `limit`." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Authenticated as a user rather than a store." } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/account": { "get": { "tags": [ "Authentication" ], "summary": "Read the authenticated account", "description": "Accepts either a bare JWT or store Basic credentials; with Basic credentials\nit resolves the account that owns the store.\n\nThis is the one path where the `basic` middleware treats a bare `Bearer` token\nwithout `X-PrintCart-Store-Sid` as valid — and only for `GET`.", "operationId": "getAccount", "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Account" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Authentication" ], "summary": "Update the authenticated account", "description": "Only `name`, `email` and `metadata` are applied; anything else in the body is\nignored silently.", "operationId": "updateAccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdate" } } } }, "responses": { "200": { "description": "Updated account.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Account" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "accountJwt": [] } ] }, "post": { "tags": [ "Authentication" ], "summary": "Create an account", "description": "Creates a Printcart account and immediately returns a JWT. This is the\nonly Wave-1 endpoint that needs no credential at all.\n\nAn account owns stores; it is not itself a store. Call `POST /stores` next to\nget the `sid`/`secret` pair that the rest of the API uses.\n\nThe account starts on the `free` tier. Email verification is **not** required\nto sign in.", "operationId": "createAccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreate" } } } }, "responses": { "201": { "description": "Account created; the JWT is live immediately.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AuthSession" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } }, "security": [] } }, "/account/signIn": { "post": { "tags": [ "Authentication" ], "summary": "Sign in and obtain a JWT", "description": "Note the camelCase path segment — it is `signIn`, not `sign-in`.\n\nBad credentials return **401** with `{\"error\":{\"message\":\"Unauthorized\"}}`\n(no trailing full stop, unlike the middleware's `\"Unauthorized.\"`).", "operationId": "signIn", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInRequest" } } } }, "responses": { "200": { "description": "Signed in.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AuthSession" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "400": { "$ref": "#/components/responses/ValidationFailed" } }, "security": [] } }, "/account/render-jwt": { "get": { "tags": [ "Authentication" ], "summary": "Exchange store credentials for an account JWT", "description": "Lets a server-side integration holding only `sid:secret` obtain a JWT for the\nowning account, without the human's password. This is the intended way to\nautomate anything that needs `auth.jwt` — including `POST /stores`.", "operationId": "renderJwt", "responses": { "200": { "description": "A fresh JWT for the store owner.", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "token_type": { "type": "string", "example": "bearer" }, "access_token": { "type": "string" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/account/signOut": { "post": { "tags": [ "Authentication" ], "summary": "Invalidate the current JWT", "description": "Sign out", "operationId": "signOut", "responses": { "200": { "description": "Logged out.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Successfully logged out" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "accountJwt": [] } ] } }, "/account/password-update": { "put": { "tags": [ "Authentication" ], "summary": "Change the account password", "description": "A wrong current password returns **400**, not 401 or 422.", "operationId": "updatePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordUpdate" } } } }, "responses": { "200": { "description": "Password changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "400": { "description": "Current password did not match, or the new password failed the strength rules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "accountJwt": [] } ] } }, "/password-reset": { "post": { "tags": [ "Authentication" ], "summary": "Send a password-reset link", "description": "Unknown addresses return **404**, so this endpoint discloses whether an email\nis registered. Do not proxy it to an untrusted caller.", "operationId": "requestPasswordReset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordRequest" } } } }, "responses": { "200": { "description": "Reset link queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "400": { "description": "Could not queue the reset link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/password-reset/{token}": { "put": { "tags": [ "Authentication" ], "summary": "Complete a password reset", "description": "Password Reset", "operationId": "completePasswordReset", "parameters": [ { "name": "token", "in": "path", "description": "The encrypted reset token taken from the emailed link.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetRequest" } } } }, "responses": { "200": { "description": "Password changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook subscriptions", "description": "Display a listing of the resource.", "operationId": "listWebhooks", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/sortBy" } ], "responses": { "200": { "description": "Subscriptions for this store.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "links": { "$ref": "#/components/schemas/CursorPaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorPaginationMeta" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/LimitTooLarge" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Subscribe to a topic", "description": "One subscription covers one (`topic`, `event`) pair. To hear about both\ncreates and updates of products, create two subscriptions.\n\nDeliveries carry a `Signature` header — see the `WebhookDelivery` schema for\nthe payload envelope and the HMAC recipe. **Nothing is delivered unless the\nbackend is running with `APP_ENV=production`.**\n\nReturns **200**, not 201.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "200": { "description": "Subscription created.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/webhooks/{webhook}": { "get": { "tags": [ "Webhooks" ], "summary": "Read a webhook subscription", "description": "Display the specified resource.", "operationId": "getWebhook", "parameters": [ { "name": "webhook", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The subscription.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook subscription", "description": "Unlike `show` and `destroy`, this method does **not** check that the\nsubscription belongs to the calling store before writing. Treat the id as\nsensitive.", "operationId": "updateWebhook", "parameters": [ { "name": "webhook", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "Updated subscription.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook subscription", "description": "Remove the specified resource from storage.", "operationId": "deleteWebhook", "parameters": [ { "name": "webhook", "in": "path", "description": "UUID of the resource.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } }, "/webhooks/count": { "get": { "tags": [ "Webhooks" ], "summary": "Count webhook subscriptions", "description": "Display count of the resource.", "operationId": "countWebhooks", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "storeBasic": [] }, { "accountJwt": [], "storeSid": [] } ] } } }, "components": { "schemas": { "Error": { "title": "Error (nested envelope)", "description": "The envelope produced by `BaseController::error()` and by the `basic` /\n`admin` auth middleware.\n\n```json\n{ \"error\": { \"message\": \"Unauthorized.\" } }\n```\n\n### Error catalogue\n\nThere is **no machine-readable `code` field on most errors today.** The stable\ncontract is the HTTP status plus the endpoint. Only three responses currently\ncarry a code, and they do not agree on where it sits:\n\n| HTTP | Where a code appears | Value | Meaning |\n|---|---|---|---|\n| 400 | — | — | Validation failed (`message: \"Invalid input\"`, `error` = field → messages) |\n| 400 | — | — | `\"Please upgrade your account.\"` — plan gate on uploads/design size |\n| 401 | — | — | Missing or invalid credential |\n| 402 | `error.code` | `storage_quota_exceeded` | Media storage cap reached (only when `entitlement.gate_mode=hard`) |\n| 402 | top-level `code` | `insufficient_tokens` | Wallet balance empty (AI/token-billed operations) |\n| 403 | — | — | Authenticated but not permitted |\n| 404 | — | — | Not found. Also returned for another store's resource, and for a failed form-request authorization check — existence is never leaked |\n| 413 | — | — | `limit` above 100 on `/design-templates` and `/side-templates` only; every other list endpoint rejects it as a 400 validation failure |\n| 429 | — | — | Rate limited (`Retry-After` present) |\n| 500 | — | — | Internal error |\n\nIntegrators should branch on HTTP status, not on `message` — messages are not\na contract and are not localised.", "required": [ "error" ], "properties": { "error": { "properties": { "message": { "description": "Cross-cutting conventions published as reusable OpenAPI components:\nthe error envelopes, the error-code catalogue, cursor pagination, the\nrate-limit headers, `Idempotency-Key` and `X-Request-Id`.\n\nNo runtime behaviour. Documentation only.\n\nIMPORTANT: everything below documents the API **as it exists today**. The\nsingle-envelope error redesign is a breaking change and is deliberately NOT\ndescribed here as if it had shipped.", "type": "string", "example": "Unauthorized." }, "code": { "description": "Present only on the 402 storage-quota error.", "type": "string", "example": "storage_quota_exceeded" } }, "type": "object", "additionalProperties": true } }, "type": "object" }, "MessageError": { "title": "Error (flat envelope)", "description": "The envelope produced by `BaseController::not_found()`, `forbidden()`,\n`no_data()`, `check_user_tier()`, by the `unauth.token` and `auth.jwt`\nmiddleware, and by Laravel's own 429/500 handlers.\n\n```json\n{ \"message\": \"Not found\" }\n```\n\nThis is the second of the two envelopes in circulation. An endpoint can return\nthe nested `Error` shape for one failure mode and this flat shape for another —\nfor example `GET /webhooks/{webhook}` returns the flat shape for 404 but the\nnested shape for 401, because the two come from different layers.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Not found" } }, "type": "object" }, "ValidationError": { "title": "Validation error (HTTP 400)", "description": "Emitted by `App\\Http\\Requests\\BaseRequest::failedValidation()`.\n\n**This is a 400, not a 422.** `error` is a map of field name → array of human\nmessages. Nested and wildcard fields keep their dotted validation path, e.g.\n`products.0.name`, `design_area.width`.\n\n```json\n{\n \"error\": { \"name\": [\"The name field is required.\"] },\n \"message\": \"Invalid input\"\n}\n```", "required": [ "error", "message" ], "properties": { "error": { "description": "Field name → list of validation messages.", "type": "object", "example": { "name": [ "The name field is required." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "message": { "type": "string", "example": "Invalid input" } }, "type": "object" }, "StorageQuotaError": { "title": "Storage quota exceeded (HTTP 402)", "description": "Returned by the `quota.media` middleware on upload routes when the store is\nover its media storage cap **and** `config('entitlement.gate_mode')` is `hard`.\n\nIn `soft` mode the upload succeeds and the response instead carries an\n`X-Printcart-Storage` header. In `off` mode — the default — the middleware is a\nno-op and this response never occurs.", "required": [ "error" ], "properties": { "error": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "storage_quota_exceeded" ] }, "message": { "type": "string" }, "usage": { "properties": { "used_gb": { "type": "number", "format": "float" }, "cap_gb": { "type": "number", "format": "float" }, "tier": { "type": "string" } }, "type": "object" }, "cta": { "description": "Upgrade call-to-action. `label`/`url`/`plan` are the legacy flat form; `primary`/`secondary` are the current two-destination form. Both are always present.", "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "plan": { "type": "string" }, "primary": { "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "secondary": { "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "store_sid": { "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" }, "InsufficientTokensError": { "title": "Insufficient tokens (HTTP 402)", "description": "Returned by `BaseController::insufficientTokens()` for wallet-billed\noperations. Note the `code` is **top-level** here, not under `error` — and\n`error` is a string, not an object. This is the third distinct error shape in\nthe API.", "required": [ "code", "error", "message" ], "properties": { "code": { "type": "string", "enum": [ "insufficient_tokens" ] }, "error": { "type": "string", "enum": [ "INSUFFICIENT_TOKENS" ] }, "message": { "type": "string" }, "top_up_url": { "type": "string", "format": "uri" } }, "type": "object" }, "CursorPaginationLinks": { "title": "Cursor pagination links", "description": "Wave-1 list endpoints use Laravel **cursor** pagination (`cursorPaginate`), not\npage-number pagination. `first` and `last` are always `null` — a cursor\npaginator cannot know them. There is no `total` and no `last_page`; do not\nbuild a page-count UI from this response.\n\nWalk forward by following `next` (or by passing its `cursor` value back as the\n`cursor` query parameter) until it is `null`.", "properties": { "first": { "type": [ "string", "null" ], "example": null }, "last": { "type": [ "string", "null" ], "example": null }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" } }, "type": "object" }, "CursorPaginationMeta": { "title": "Cursor pagination meta", "properties": { "path": { "type": "string", "format": "uri" }, "per_page": { "type": "integer", "example": 20 }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "PageMeta": { "title": "Page-number pagination meta", "description": "A second, incompatible pagination shape used by a small number of endpoints\nthat call `paginate()` instead of `cursorPaginate()` — in Wave 1 that is\n`GET /projects/{project}/events`. It has a fixed page size and exposes totals,\nbut has no `links` block and takes a `page` query parameter rather than\n`cursor`.", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } }, "type": "object" }, "CountResponse": { "title": "Count response", "description": "Shape returned by the `/count` sub-resources.", "properties": { "data": { "properties": { "count": { "type": "integer", "example": 42 } }, "type": "object" }, "message": { "type": "string", "example": "Retrieved successfully" } }, "type": "object" }, "DeletedResponse": { "title": "Deleted response", "description": "Body returned by `BaseController::display_deleted()`. HTTP 200, not 204.", "properties": { "message": { "type": "string", "example": "Deleted successfully" } }, "type": "object" }, "AccountCreate": { "title": "Create account", "required": [ "name", "email", "password" ], "properties": { "name": { "description": "Wave-1 request body schemas, derived field-for-field from the Form Requests\nin `app/Http/Requests/**`.\n\nConventions used below:\n- `required` mirrors the `required` validation rule exactly.\n- A rule of `nullable` becomes `nullable: true`.\n- `Rule::in(Enum::getValues())` becomes an `enum`.\n- `exists:` / `unique:` constraints are stated in the description, since\nOpenAPI cannot express them.\n\nNo runtime behaviour. Documentation only.", "type": "string", "maxLength": 255 }, "email": { "description": "Must be unique across all accounts.", "type": "string", "format": "email" }, "password": { "description": "Minimum 8 characters, must contain letters, mixed case, numbers and symbols, and must not appear in a known-breach corpus (`uncompromised`).", "type": "string", "format": "password", "minLength": 8 } }, "type": "object" }, "SignInRequest": { "title": "Sign in", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "type": "object" }, "AccountUpdate": { "title": "Update account", "properties": { "name": { "description": "Must be unique across accounts (the caller's own record is ignored).", "type": "string", "maxLength": 255 }, "email": { "description": "Must be unique.", "type": [ "string", "null" ], "format": "email" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } }, "type": "object" }, "PasswordUpdate": { "title": "Change password", "required": [ "password", "new_password" ], "properties": { "password": { "description": "Current password.", "type": "string", "format": "password" }, "new_password": { "description": "Same strength rules as account creation.", "type": "string", "format": "password", "minLength": 8 } }, "type": "object" }, "PasswordResetRequest": { "title": "Complete password reset", "required": [ "new_password" ], "properties": { "new_password": { "type": "string", "format": "password", "minLength": 8 } }, "type": "object" }, "ForgotPasswordRequest": { "title": "Request password reset", "description": "Not validated by a Form Request. `UserController::forgotPassword` only tests `isset($data['email'])`; an unknown address yields 404 (`firstOrFail`), and an empty body reaches an uninitialised variable and 500s. Always send an `email`.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } }, "type": "object" }, "StoreCreate": { "title": "Create store", "description": "All fields are optional — `POST /stores` with an empty body creates a store with generated credentials.", "properties": { "store_name": { "type": "string" }, "google_font_api": { "type": [ "string", "null" ] }, "shop_url": { "description": "Must match an `https://`-style host pattern. Plain `http://` URLs are rejected.", "type": [ "string", "null" ] }, "integration": { "type": [ "string", "null" ], "enum": [ "wix", "shopify", "wordpress", "magento", "nbdesign", "codecanyon", "woocommerce", "bigcommerce", "shopify_private", "printcart_studio" ] }, "unsplash": { "type": [ "string", "null" ] }, "pixabay": { "type": [ "string", "null" ] }, "pexels": { "type": [ "string", "null" ] }, "setting_defaults": { "type": [ "object", "null" ], "additionalProperties": true }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "pod_setting": { "type": [ "object", "null" ], "additionalProperties": true } }, "type": "object" }, "StoreUpdate": { "title": "Update store", "description": "Same as `StoreCreate` plus `integration_details`. Note `integration_details` is validated as `json` — send it as a **JSON-encoded string**, not as an object.", "properties": { "store_name": { "type": "string" }, "google_font_api": { "type": [ "string", "null" ] }, "unsplash": { "type": [ "string", "null" ] }, "pixabay": { "type": [ "string", "null" ] }, "pexels": { "type": [ "string", "null" ] }, "setting_defaults": { "type": [ "object", "null" ], "additionalProperties": true }, "shop_url": { "type": [ "string", "null" ] }, "integration": { "type": [ "string", "null" ], "enum": [ "wix", "shopify", "wordpress", "magento", "nbdesign", "codecanyon", "woocommerce", "bigcommerce", "shopify_private", "printcart_studio" ] }, "integration_details": { "description": "JSON-encoded string.", "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "pod_setting": { "type": [ "object", "null" ], "additionalProperties": true } }, "type": "object" }, "StoreProfileUpdate": { "title": "Update store public profile", "description": "`shop_url` is **required** here even though this endpoint is about the brand profile — omitting it fails validation.", "required": [ "shop_url" ], "properties": { "shop_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "slug": { "description": "Lowercase kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). Unique across stores.", "type": "string", "maxLength": 160, "minLength": 3 }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "banner_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "tagline": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "industry": { "type": [ "string", "null" ], "maxLength": 120 }, "category_ids": { "description": "Numeric ids of categories whose `type` is the brand-profile type.", "type": [ "array", "null" ], "items": { "type": "integer" }, "maxItems": 5 }, "locations": { "type": [ "array", "null" ], "items": { "required": [ "label", "address_line1", "city", "country" ], "properties": { "label": { "type": "string", "maxLength": 120 }, "address_line1": { "type": "string", "maxLength": 255 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": "string", "maxLength": 120 }, "state": { "type": [ "string", "null" ], "maxLength": 120 }, "postal_code": { "type": [ "string", "null" ], "maxLength": 40 }, "country": { "type": "string", "maxLength": 120 }, "phone": { "type": [ "string", "null" ], "maxLength": 64 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "is_primary": { "type": "boolean" } }, "type": "object" }, "maxItems": 20 }, "social_links": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uri", "maxLength": 2048 }, "maxItems": 8 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "support_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "seo_title": { "type": [ "string", "null" ], "maxLength": 160 }, "seo_description": { "type": [ "string", "null" ], "maxLength": 320 }, "profile_public": { "type": "boolean" } }, "type": "object" }, "StoreDomainUpdate": { "title": "Update store domain", "required": [ "shop_url" ], "properties": { "shop_url": { "type": "string", "maxLength": 2048 } }, "type": "object" }, "ProductCreate": { "title": "Create product", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "dynamic_side": { "type": "boolean" }, "viewport_width": { "type": [ "number", "null" ], "format": "float" }, "viewport_height": { "type": [ "number", "null" ], "format": "float" }, "scale": { "type": [ "number", "null" ], "format": "float" }, "dpi": { "type": [ "integer", "null" ] }, "dimension_unit": { "description": "Defaults to `cm` when omitted.", "type": "string", "enum": [ "inch", "cm", "px" ] }, "status": { "type": "string", "enum": [ "publish", "draft", "trashed", "deleted" ] }, "allowed_file_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "jpg", "png", "ai", "ps", "pdf", "bmp", "iddd", "svg" ] } }, "enable_design": { "type": "boolean" }, "enable_upload": { "type": "boolean" }, "enable_pod": { "type": "boolean" }, "enable_request_quote": { "type": "boolean" }, "request_quote_options": { "type": [ "object", "null" ], "additionalProperties": true }, "product_image_id": { "description": "Uuid of an Image owned by this store (or a global image).", "type": [ "string", "null" ], "format": "uuid" }, "max_file_upload": { "type": [ "integer", "null" ], "minimum": 1 }, "min_jpg_dpi": { "type": [ "integer", "null" ], "minimum": 0 }, "type_id": { "type": "string", "enum": [ "simple", "variant", "variant_option" ] }, "description": { "type": [ "string", "null" ] }, "category_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "parent_id": { "description": "Uuid of an existing product. Note the **response** returns `parent_id` as a numeric id, so it cannot be round-tripped.", "type": [ "string", "null" ], "format": "uuid" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "first_order": { "type": [ "string", "null" ] }, "product_link": { "type": [ "string", "null" ] }, "image_gallery_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "design_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "upload_max_filesize": { "description": "Bytes. Accepted only up to the ceiling allowed by the account plan — the rule is injected dynamically by `checkUploadMaxFilesize()`.", "type": "integer" }, "integration_product_id": { "description": "Not declared in the validation rules but read by the controller: supplying an id that already exists on this store returns **400 `Duplicate Product`**.", "type": "string" } }, "type": "object" }, "ProductUpdate": { "title": "Update product", "description": "Note `status` on update is restricted to `publish|draft|trashed` — `deleted` is accepted on create but not on update. `type_id` and `parent_id` cannot be changed.", "properties": { "name": { "type": "string", "maxLength": 255 }, "dynamic_side": { "type": "boolean" }, "viewport_width": { "type": "number", "format": "float" }, "viewport_height": { "type": "number", "format": "float" }, "scale": { "type": "number", "format": "float" }, "dpi": { "type": "integer" }, "dimension_unit": { "type": "string", "enum": [ "inch", "cm", "px" ] }, "status": { "type": "string", "enum": [ "publish", "draft", "trashed" ] }, "allowed_file_types": { "type": "array", "items": { "type": "string", "enum": [ "jpg", "png", "ai", "ps", "pdf", "bmp", "iddd", "svg" ] } }, "enable_design": { "type": "boolean" }, "enable_upload": { "type": "boolean" }, "enable_pod": { "type": "boolean" }, "enable_request_quote": { "type": "boolean" }, "request_quote_options": { "type": [ "object", "null" ], "additionalProperties": true }, "product_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "max_file_upload": { "type": "integer", "minimum": 1 }, "min_jpg_dpi": { "type": "integer", "minimum": 0 }, "description": { "type": [ "string", "null" ] }, "category_ids": { "description": "Replaces the whole set — existing links are deleted first.", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "first_order": { "type": [ "string", "null" ] }, "product_link": { "type": [ "string", "null" ] }, "image_gallery_ids": { "description": "Replaces the whole gallery.", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "upload_max_filesize": { "type": "integer" } }, "type": "object" }, "ProductBatchCreate": { "title": "Create products (batch)", "required": [ "products" ], "properties": { "products": { "description": "Batch item fields match `ProductCreate` except that `category_ids` and `design_ids` are not accepted and `request_quote_options` / `metadata` must be **JSON-encoded strings** rather than objects.", "type": "array", "items": { "$ref": "#/components/schemas/ProductCreate" } } }, "type": "object" }, "ProductBatchUpdate": { "title": "Update products (batch)", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "description": "Remaining fields match `ProductUpdate`, with `request_quote_options` / `metadata` as JSON-encoded strings.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": true } } }, "type": "object" }, "BatchDeleteByIds": { "title": "Batch delete", "description": "The array key differs per resource: `products`, `sides`, `designs`, `templates`, `projects`, `images`. Each element is an object with a single `id`.", "properties": { "items": { "type": "array", "items": { "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "ProductImageAttach": { "title": "Attach product gallery image", "description": "Validated inline in `ProductController::uploadImage`.", "required": [ "image_id" ], "properties": { "image_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "CategoryCreate": { "title": "Create category / storage", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" } }, "type": "object" }, "CategoryUpdate": { "title": "Update category / storage", "properties": { "name": { "type": "string", "maxLength": 255 }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" } }, "type": "object" }, "SideCreate": { "title": "Create side", "description": "`product_id` is `nullable` in the rules, so a side can be created detached from\nany product — but a detached side has no `dimension_unit` and cannot be\nrendered. Supply it unless you are deliberately building a template side.\n\nGeometry is submitted in the same grouped form the response uses\n(`design_area`, `cut_line_margin`, `safe_zone_margin`, `side_image_size`), not\nas the flat database columns.", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "product_id": { "type": [ "string", "null" ], "format": "uuid" }, "scale": { "description": "Stored in the `ratio` column.", "type": "number", "format": "float" }, "status": { "type": "string", "enum": [ "publish", "draft", "trashed", "deleted" ] }, "side_image_id": { "description": "Background / mockup image.", "type": [ "string", "null" ], "format": "uuid" }, "img_overlay_id": { "type": [ "string", "null" ], "format": "uuid" }, "bg_type": { "type": [ "string", "null" ], "enum": [ "color", "image", "transparent" ] }, "bg_color_value": { "type": [ "string", "null" ] }, "show_overlay": { "type": [ "boolean", "null" ] }, "show_cut_line": { "description": "Stored in `show_bleed`.", "type": [ "boolean", "null" ] }, "show_safe_zone": { "type": [ "boolean", "null" ] }, "include_overlay": { "type": [ "boolean", "null" ] }, "background_included": { "type": [ "boolean", "null" ] }, "cut_line_margin": { "description": "Exactly the keys `x` and `y` — any other key fails validation.", "properties": { "x": { "type": "number", "format": "float" }, "y": { "type": "number", "format": "float" } }, "type": [ "object", "null" ] }, "safe_zone_margin": { "properties": { "x": { "type": "number", "format": "float" }, "y": { "type": "number", "format": "float" } }, "type": [ "object", "null" ] }, "side_image_size": { "description": "Exactly the keys `width` and `height`, both `> 0`.", "properties": { "width": { "type": "number", "format": "float", "exclusiveMinimum": 0 }, "height": { "type": "number", "format": "float", "exclusiveMinimum": 0 } }, "type": [ "object", "null" ] }, "design_area": { "description": "Exactly the keys `width`, `height`, `top`, `left`. `width`/`height` must be `> 0`; `top`/`left` must be `>= 0`.", "properties": { "width": { "type": "number", "format": "float", "exclusiveMinimum": 0 }, "height": { "type": "number", "format": "float", "exclusiveMinimum": 0 }, "top": { "type": "number", "format": "float", "minimum": 0 }, "left": { "type": "number", "format": "float", "minimum": 0 } }, "type": [ "object", "null" ] }, "area_design_type": { "type": [ "string", "null" ] }, "is_template": { "type": [ "boolean", "null" ] }, "lock_aspect_ratio": { "type": [ "boolean", "null" ] } }, "type": "object" }, "SideUpdate": { "title": "Update side", "description": "Same field set as `SideCreate`, with `name` optional.", "properties": { "name": { "type": "string", "maxLength": 255 }, "product_id": { "type": [ "string", "null" ], "format": "uuid" }, "scale": { "type": [ "number", "null" ], "format": "float" }, "status": { "type": [ "string", "null" ], "enum": [ "publish", "draft", "trashed", "deleted" ] }, "side_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "img_overlay_id": { "type": [ "string", "null" ], "format": "uuid" }, "bg_type": { "type": [ "string", "null" ], "enum": [ "color", "image", "transparent" ] }, "bg_color_value": { "type": [ "string", "null" ] }, "show_overlay": { "type": [ "boolean", "null" ] }, "show_cut_line": { "type": [ "boolean", "null" ] }, "show_safe_zone": { "type": [ "boolean", "null" ] }, "include_overlay": { "type": [ "boolean", "null" ] }, "background_included": { "type": [ "boolean", "null" ] }, "cut_line_margin": { "properties": { "x": { "type": "number", "format": "float" }, "y": { "type": "number", "format": "float" } }, "type": [ "object", "null" ] }, "safe_zone_margin": { "properties": { "x": { "type": "number", "format": "float" }, "y": { "type": "number", "format": "float" } }, "type": [ "object", "null" ] }, "side_image_size": { "properties": { "width": { "type": "number", "format": "float" }, "height": { "type": "number", "format": "float" } }, "type": [ "object", "null" ] }, "design_area": { "properties": { "width": { "type": "number", "format": "float" }, "height": { "type": "number", "format": "float" }, "top": { "type": "number", "format": "float" }, "left": { "type": "number", "format": "float" } }, "type": [ "object", "null" ] }, "area_design_type": { "type": [ "string", "null" ] }, "is_template": { "type": [ "boolean", "null" ] }, "lock_aspect_ratio": { "type": [ "boolean", "null" ] } }, "type": "object" }, "SideBatchCreate": { "title": "Create sides (batch)", "required": [ "sides" ], "properties": { "sides": { "type": "array", "items": { "$ref": "#/components/schemas/SideCreate" } } }, "type": "object" }, "SideBatchUpdate": { "title": "Update sides (batch)", "required": [ "sides" ], "properties": { "sides": { "type": "array", "items": { "description": "Remaining fields match `SideUpdate`.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": true } } }, "type": "object" }, "SideImportFromTemplate": { "title": "Import a side from a side template", "required": [ "template_id" ], "properties": { "template_id": { "description": "Must exist in `side_templates`.", "type": "string", "format": "uuid" }, "side_name_override": { "type": [ "string", "null" ], "maxLength": 50, "minLength": 2 } }, "type": "object" }, "SideApplyToProducts": { "title": "Copy sides onto other products", "required": [ "product_ids", "side_ids", "product_parent_id" ], "properties": { "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "side_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "product_parent_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "SideApplyToChildren": { "title": "Propagate a side to child products", "description": "`product_ids` is validated as a **string**, not an array — pass a comma-separated list.", "properties": { "product_ids": { "type": [ "string", "null" ] } }, "type": "object" }, "TemplateContainerCreate": { "title": "Create design/side template", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": [ "boolean", "null" ] }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "side_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "TemplateContainerUpdate": { "title": "Update design/side template", "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": [ "boolean", "null" ] }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "side_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "storages": { "description": "Category uuids to file the template under.", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "GlobalSideTemplateUpdate": { "title": "Update global side template", "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": [ "boolean", "null" ] }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "side_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "storages": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "wix_recommended": { "type": [ "boolean", "null" ] }, "wix_product_type": { "type": [ "string", "null" ], "maxLength": 255 } }, "type": "object" }, "TemplateApplyToProducts": { "title": "Apply a template to products", "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": [ "boolean", "null" ] }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "product_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "SideTemplateContribute": { "title": "Contribute a side template to products", "description": "The only endpoint in Wave 1 that accepts an idempotency key — and it takes it in the **body**, not as a header.", "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": [ "boolean", "null" ] }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "product_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "license": { "type": [ "string", "null" ], "maxLength": 255 }, "source_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "copyright_holder": { "type": [ "string", "null" ], "maxLength": 255 }, "contribution_note": { "type": [ "string", "null" ], "maxLength": 1000 }, "idempotency_key": { "type": [ "string", "null" ], "maxLength": 191 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } }, "type": "object" }, "TemplatePublish": { "title": "Publish a template", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": [ "boolean", "null" ] } }, "type": "object" }, "DesignGroupCreate": { "title": "Create design group", "required": [ "name" ], "properties": { "name": { "type": "string" }, "image_id": { "type": "string", "format": "uuid" }, "design_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "DesignGroupUpdate": { "title": "Update design group", "properties": { "name": { "type": "string" }, "image_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "DesignCreate": { "title": "Create design", "description": "Accepts `multipart/form-data` (when sending `design_file`) or JSON (when\nreferencing an already-uploaded `design_image_id`).\n\nExactly one of `side_id` / `product_id` is needed — each is `required_without`\nthe other. Likewise exactly one of `design_file` / `design_image_id`.\n\n`layers` is validated as a **string**: JSON-encode the canvas document before\nsending. The response returns it decoded.\n\nThe `/templates` family shares this exact request shape. `app/Http/Requests/Template/`\ncontains a parallel set of rules using `template_file` / `template_image_id`, but\nnothing imports them — `DesignController` type-hints the `Design\\` requests on\nevery route, including the `/templates` ones. Send `design_file` /\n`design_image_id` on `/templates` too.", "properties": { "side_id": { "description": "Required unless `product_id` is given.", "type": [ "string", "null" ], "format": "uuid" }, "product_id": { "description": "Required unless `side_id` is given.", "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "description": "Attach the design to an existing project. A project is created automatically when omitted.", "type": [ "string", "null" ], "format": "uuid" }, "design_file": { "description": "Required unless `design_image_id` is given. Multipart only.", "type": "string", "format": "binary" }, "design_image_id": { "description": "Required unless `design_file` is given.", "type": "string", "format": "uuid" }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "note": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "accepted", "processing", "declined", "trashed", "deleted" ] }, "viewport_width": { "type": [ "number", "null" ], "format": "float" }, "viewport_height": { "type": [ "number", "null" ], "format": "float" }, "is_uploader": { "type": [ "boolean", "null" ] }, "alt_image": { "type": [ "string", "null" ] }, "layers": { "description": "JSON-encoded canvas document.", "type": [ "string", "null" ] }, "designer_id": { "type": [ "string", "null" ] }, "buyer_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 } }, "type": "object" }, "DesignUpdate": { "title": "Update design", "properties": { "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "side_id": { "type": "string", "format": "uuid" }, "note": { "type": [ "string", "null" ] }, "preview_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "design_image_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "accepted", "processing", "declined", "trashed", "deleted" ] }, "viewport_width": { "type": [ "number", "null" ], "format": "float" }, "viewport_height": { "type": [ "number", "null" ], "format": "float" }, "layers": { "description": "JSON-encoded canvas document.", "type": [ "string", "null" ] }, "alt_image": { "type": [ "string", "null" ] }, "designer_id": { "type": [ "string", "null" ] } }, "type": "object" }, "DesignBatchCreate": { "title": "Create designs (batch)", "description": "Batch items additionally accept the photobook page fields `book_id`, `side_role`, `sequence`, `spread_index`, `left_page_no`, `right_page_no`, `layout`, which are carried onto the project item rather than the design.", "required": [ "designs" ], "properties": { "designs": { "type": "array", "items": { "$ref": "#/components/schemas/DesignCreate" } } }, "type": "object" }, "DesignBatchUpdate": { "title": "Update designs (batch)", "required": [ "designs" ], "properties": { "designs": { "type": "array", "items": { "description": "Remaining fields match `DesignUpdate`.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": true } } }, "type": "object" }, "DesignGenerate": { "title": "Generate print output", "properties": { "reset": { "description": "Force a re-render instead of returning the cached artefact.", "type": [ "boolean", "null" ] } }, "type": "object" }, "PresignedUploadRequest": { "title": "Request a presigned upload URL", "required": [ "path", "side_id" ], "properties": { "path": { "description": "Object key to write to.", "type": "string" }, "side_id": { "type": "string", "format": "uuid" }, "product_id": { "type": [ "string", "null" ], "format": "uuid" } }, "type": "object" }, "FontCreate": { "title": "Create font", "description": "Two different shapes are accepted on `POST /fonts` depending on whether a file\nis attached — `FontController::store` branches on the presence of `file`.\n\n- **Register a hosted font** (`application/json`): `name` + `url`.\n- **Upload a font file** (`multipart/form-data`): `file` + `name` (+ optional\n `family`), validated by `StoreFontRequest` with a `ttf,otf,woff,woff2`\n mime restriction and a per-plan size cap (default 50 MB).", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "url": { "description": "Hosted font URL. Validated against a host regex.", "type": [ "string", "null" ] }, "alias": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "subset": { "type": [ "string", "null" ] }, "file": { "description": "Multipart upload path only.", "type": "string", "format": "binary" }, "family": { "description": "Multipart upload path only.", "type": [ "string", "null" ], "maxLength": 255 } }, "type": "object" }, "FontUpdate": { "title": "Update font", "description": "`url` cannot be changed after creation — it is absent from the update rules.", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "alias": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "subset": { "type": [ "string", "null" ] } }, "type": "object" }, "ImageUpload": { "title": "Upload image", "description": "Multipart. Permitted extensions depend on `type`: the default set for artwork, and `svg,png` for cliparts. Oversized files for the account plan are rejected with **400 `Please upgrade your account.`**, not 402.", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "name": { "type": [ "string", "null" ] }, "alt": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "designs", "cliparts", "three_d_previews" ] }, "custom_width": { "type": [ "integer", "null" ], "minimum": 1 } }, "type": "object" }, "ImageBatchUpload": { "title": "Upload images (batch)", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "type": { "type": [ "string", "null" ], "enum": [ "designs", "cliparts", "three_d_previews" ] } }, "type": "object" }, "ClipartUpload": { "title": "Upload clipart", "required": [ "file" ], "properties": { "file": { "description": "One of `svg,png,jpg,jpeg,webp`.", "type": "string", "format": "binary" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "alt": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ] } }, "type": "object" }, "ClipartBatchUpload": { "title": "Upload cliparts (batch)", "description": "Batch upload is narrower than single upload: only `svg` and `png` are accepted.", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } } }, "type": "object" }, "StoreClipartUpload": { "title": "Upload clipart to the store library", "description": "Used by `POST /cliparts/mine`. Validated inline in the controller, so a failure returns Laravel's default **422** rather than the API's 400. Note `app/Http/Requests/StoreMediaClipartRequest.php` describes a different, stricter contract (2 MB cap, `category_id`, `tags[]`) but is never loaded by any route.", "required": [ "file" ], "properties": { "file": { "description": "Max 50 MB. One of `jpg,jpeg,png,webp,svg`.", "type": "string", "format": "binary" }, "name": { "description": "Defaults to the uploaded file name without its extension.", "type": [ "string", "null" ], "maxLength": 255 }, "cate_id": { "description": "Category identifier. `category` is accepted as a fallback alias.", "type": [ "string", "null" ], "maxLength": 256 }, "category": { "description": "Alias for `cate_id`, used only when `cate_id` is absent.", "type": [ "string", "null" ], "maxLength": 256 }, "tag": { "description": "A single free-text tag string, not an array.", "type": [ "string", "null" ], "maxLength": 256 }, "description": { "type": [ "string", "null" ] } }, "type": "object" }, "ProjectCreate": { "title": "Create project", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "processing", "reviewing", "accepted", "in_production", "fulfilled", "canceled", "trashed", "deleted", "refunded" ] }, "note": { "type": [ "string", "null" ] }, "design_ids": { "description": "Existing designs to move into this project.", "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "ProjectUpdate": { "title": "Update project", "description": "There is no way to set `order_detail`, `buyer_email` or any commercial field through this endpoint — those are written only by the platform integrations. A project created through the API will therefore always report `null` for `customer_email`, `total_price` and friends.", "properties": { "name": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "processing", "reviewing", "accepted", "in_production", "fulfilled", "canceled", "trashed", "deleted", "refunded" ] }, "note": { "type": [ "string", "null" ] } }, "type": "object" }, "ProjectBatchCreate": { "title": "Create projects (batch)", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCreate" } } }, "type": "object" }, "ProjectBatchUpdate": { "title": "Update projects (batch)", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": true } } }, "type": "object" }, "ProjectEventCreate": { "title": "Append a project event", "description": "Validated inline in `ProjectEventController::store` with `$request->validate()`,\nso a failure here returns Laravel's **422** default — unlike every Form Request\nin the API, which returns 400.\n\n`note` is the only accepted field. `event_type` is hard-coded to `note_added`\nand `actor_type` to `merchant`; you cannot record any other event type through\nthe API.", "required": [ "note" ], "properties": { "note": { "type": "string", "maxLength": 1000 } }, "type": "object" }, "ProjectFolderCreate": { "title": "Create project folder link", "description": "Validated inline in `ProjectFolderController::store`. A row with a null `project_id` creates an empty folder link.", "required": [ "category_id" ], "properties": { "category_id": { "description": "Must be a category owned by the calling store.", "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" } }, "type": "object" }, "WebhookCreate": { "title": "Create webhook subscription", "required": [ "event", "callback_url", "topic" ], "properties": { "event": { "type": "string", "enum": [ "POST", "PUT", "DELETE", "POST BATCH", "PUT BATCH", "DELETE BATCH" ] }, "callback_url": { "description": "Validated as a plain string — not as a URL. A malformed value is accepted at creation time and only fails at delivery.", "type": "string" }, "topic": { "type": "string", "enum": [ "user", "projects", "products", "designs", "sides", "templates" ] } }, "type": "object" }, "WebhookUpdate": { "title": "Update webhook subscription", "description": "On update `callback_url` is required but `event` and `topic` are not — the reverse of what a PUT usually implies.", "required": [ "callback_url" ], "properties": { "event": { "type": "string", "enum": [ "POST", "PUT", "DELETE", "POST BATCH", "PUT BATCH", "DELETE BATCH" ] }, "callback_url": { "type": "string" }, "topic": { "type": "string", "enum": [ "user", "projects", "products", "designs", "sides", "templates" ] } }, "type": "object" }, "MultipartCreate": { "title": "Begin a multipart upload", "description": "Validated inline with `Validator::make`, so failures come back through `BaseController::display_invalid_input()` as **400** with the `{error, message}` envelope.", "required": [ "file_name" ], "properties": { "file_name": { "description": "Object key to create.", "type": "string" } }, "type": "object" }, "MultipartPart": { "title": "Upload one multipart part", "description": "Send the part bytes as `file_stream`. Its `required` rule is commented out in the controller, so an omitted stream fails later inside the S3 call rather than at validation.", "required": [ "part_number", "upload_id" ], "properties": { "part_number": { "description": "1-based part index.", "type": "integer", "minimum": 1 }, "upload_id": { "description": "From the create step.", "type": "string", "format": "uuid" }, "file_stream": { "type": "string", "format": "binary" } }, "type": "object" }, "MultipartComplete": { "title": "Finish a multipart upload", "required": [ "upload_id" ], "properties": { "upload_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "EntitlementBadge": { "title": "Entitlement badge fields", "description": "Additive fields merged into content resources (images, cliparts, design\ntemplates, side templates) **only** when the request passed through the\n`entitlement.attach` middleware and an entitlement resolved. Routes without\nthat middleware never return them.\n\nContent is never hidden by these fields — the item still returns its real URL.\nThey only tell a UI whether to paint a \"Premium\" chip.", "properties": { "tier_required": { "description": "Global/curated assets require `premium`; a store's own uploads are `free`.", "type": "string", "enum": [ "free", "premium" ] }, "store_qualified": { "type": "boolean" }, "badge": { "type": [ "string", "null" ], "enum": [ "premium", "not_qualified", null ] } }, "type": "object" }, "Image": { "title": "Image", "description": "`ImageResource`. `url` is absolute — the stored relative path is prefixed with\nthe CDN base at serialisation time.\n\nNested image fields on other resources (`product_image`, `side_image`,\n`img_overlay`, `preview`) always serialise to an object; when no image is\nattached, every field inside it is `null` rather than the whole object being\n`null`. Test `image.id !== null`, not `image !== null`.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "thumbnails": { "description": "Generated thumbnail variants, keyed by size. Null when none were generated.", "type": [ "object", "null" ], "additionalProperties": true }, "alt": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "tier_required": { "$ref": "#/components/schemas/EntitlementBadge/properties/tier_required" }, "store_qualified": { "$ref": "#/components/schemas/EntitlementBadge/properties/store_qualified" }, "badge": { "$ref": "#/components/schemas/EntitlementBadge/properties/badge" } }, "type": "object" }, "Storage": { "title": "Storage (category)", "description": "`StorageResource` / `SideTemplateStorageResource` / `DesignTemplateCategoryResource`. A node in the nested-set category tree.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "description": "Present on `DesignTemplateCategoryResource` only.", "type": "string" }, "parent_storage_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Category": { "title": "Category (tree node)", "description": "`CategoryResource`, used by the product-category endpoints. `childs` is\nrecursive and is `null` (not `[]`) when the node is a leaf.\n\n`note` is serialised but is not in the `Category` model's `$fillable` and has no\ncast — it is always `null` unless the column was written outside the model.", "properties": { "id": { "type": "string", "format": "uuid" }, "store_id": { "description": "Numeric internal store id. `null` for global categories. This is the one place a numeric id leaks into a public payload.", "type": [ "integer", "null" ] }, "name": { "type": "string" }, "url": { "description": "Relative path built as `/category/{slug}`.", "type": "string" }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "category_image": { "$ref": "#/components/schemas/Image" }, "childs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Category" } } }, "type": "object" }, "Store": { "title": "Store", "description": "`StoreResource`. Several groups of fields are conditional:\n\n- **Credentials** (`sid`, `secret`, `unauth_token`, `api_key`,\n `google_font_api_key`, `unsplash_key`, `pixabay_key`, `pexels_key`) require\n an owner-authenticated request **and** an explicit opt-in:\n `?include=credentials` (or `include=api_credentials`, or\n `include_credentials=1`). The one exception is\n `GET /stores/store-details` authenticated with Basic `sid:secret`, which\n returns them without the opt-in for backwards compatibility.\n An `X-PrintCart-Unauth-Token` caller can never receive them.\n- **`store_id` / `user_id`** (numeric) are owner-only but need no opt-in.\n- **`sync_status` / `last_synced_at` / `auth_status`** are omitted when the\n request carries `X-PrintCart-Unauth-Token`.\n- **`profile_categories` / `categories` / `locations` / `brand_readiness`** are\n present only on the profile and store-details endpoints.\n- **`widget_installed` / `new_products_count` / `last_sync_failed`** appear only\n when `integration_type` is `wix`; `view_store_url` only for `bigcommerce`.\n\n`auth_status` is hard-coded to `\"ok\"` — there is no expiry signal in\n`integration_details`, so an expired platform connection is indistinguishable\nfrom a live one. Do not build alerting on it.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "description": "The `store_name` column.", "type": "string" }, "slug": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "banner_url": { "type": [ "string", "null" ], "format": "uri" }, "tagline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "social_links": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uri" } }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ], "format": "uri" }, "seo_title": { "type": [ "string", "null" ] }, "seo_description": { "type": [ "string", "null" ] }, "profile_public": { "type": "boolean" }, "sync_status": { "description": "Derived from the latest SyncRequest. Omitted for unauth-token callers.", "type": "string", "enum": [ "idle", "syncing", "failed" ] }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "auth_status": { "description": "Always `\"ok\"` — see schema description.", "type": "string", "enum": [ "ok" ] }, "sid": { "description": "Store id half of the Basic credential. Conditional — see schema description.", "type": "string" }, "secret": { "description": "Secret half of the Basic credential. Server-side only. Conditional.", "type": "string" }, "unauth_token": { "description": "Public token for `X-PrintCart-Unauth-Token`. Conditional.", "type": "string" }, "api_key": { "description": "Alias of `unauth_token`. Conditional.", "type": "string" }, "google_font_api_key": { "type": [ "string", "null" ] }, "unsplash_key": { "type": [ "string", "null" ] }, "pixabay_key": { "type": [ "string", "null" ] }, "pexels_key": { "type": [ "string", "null" ] }, "store_id": { "description": "Numeric store id. Owner-only.", "type": "integer" }, "user_id": { "description": "Numeric owning-account id. Owner-only.", "type": "integer" }, "shop_url": { "type": [ "string", "null" ] }, "integration_type": { "type": [ "string", "null" ], "enum": [ "wix", "shopify", "wordpress", "magento", "nbdesign", "codecanyon", "woocommerce", "bigcommerce", "shopify_private", "printcart_studio" ] }, "is_integrated": { "type": "boolean" }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "setting_defaults": { "type": [ "object", "null" ], "additionalProperties": true }, "pod_setting": { "type": [ "object", "null" ], "additionalProperties": true }, "owner": { "description": "Only when the controller eager-loaded the owning user.", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AuthSession": { "title": "Authenticated session", "description": "Returned by account creation and sign-in. The JWT has no refresh token; call `POST /account/signIn` or `GET /account/render-jwt` again when it expires.", "properties": { "user": { "$ref": "#/components/schemas/Account" }, "token_type": { "type": "string", "enum": [ "bearer" ] }, "access_token": { "description": "JWT. Send as `Authorization: Bearer `.", "type": "string" } }, "type": "object" }, "Account": { "title": "Account (user)", "description": "`UserResource`. The account that owns stores. `is_admin` is `1`/`0`, not a boolean.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "administrator", "vendor", "user" ] }, "tier": { "type": "string", "enum": [ "free", "active", "premium", "advanced", "enterprise" ] }, "email_verified_at": { "description": "Sign-in does **not** require a verified email.", "type": [ "string", "null" ], "format": "date-time" }, "is_admin": { "type": "integer", "enum": [ 0, 1 ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Product": { "title": "Product", "description": "`ProductResource`. `image_galleries` is merged in only on `/products/*` paths\n(i.e. single-product reads), not on the collection.\n\n`merchant_identifier` is a convenience: `integration_product_id`, else\n`public_slug`, else the uuid.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "publish", "draft", "trashed", "deleted" ] }, "dynamic_side": { "type": "boolean" }, "viewport_width": { "type": [ "number", "null" ], "format": "float" }, "viewport_height": { "type": [ "number", "null" ], "format": "float" }, "scale": { "type": [ "number", "null" ], "format": "float" }, "dpi": { "type": [ "integer", "null" ] }, "allowed_file_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "jpg", "png", "ai", "ps", "pdf", "bmp", "iddd", "svg" ] } }, "max_file_upload": { "type": [ "integer", "null" ] }, "min_jpg_dpi": { "type": [ "integer", "null" ] }, "dimension_unit": { "type": "string", "enum": [ "inch", "cm", "px" ] }, "enable_design": { "type": "boolean" }, "enable_upload": { "type": "boolean" }, "enable_pod": { "type": "boolean" }, "enable_request_quote": { "type": "boolean" }, "request_quote_options": { "type": [ "object", "null" ], "additionalProperties": true }, "upload_max_filesize": { "description": "Bytes.", "type": [ "integer", "null" ] }, "integration_product_id": { "description": "The product id in the connected platform (Shopify/Wix/Woo).", "type": [ "string", "null" ] }, "public_slug": { "type": [ "string", "null" ] }, "merchant_identifier": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "product_image": { "$ref": "#/components/schemas/Image" }, "image_galleries": { "description": "Single-product reads only.", "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "first_order": { "type": [ "string", "null" ] }, "product_link": { "type": [ "string", "null" ] }, "pod_product_uuid": { "type": [ "string", "null" ] }, "is_pod_imported": { "type": "boolean" }, "needs_setup": { "type": "boolean" }, "setup_status": { "type": "string", "enum": [ "needs_setup", "ready" ] }, "readiness": { "description": "Computed by `ProductReadinessService`. Shape is service-defined and may gain fields.", "type": "object", "additionalProperties": true }, "parent_id": { "description": "Numeric parent product id. Note this is **not** a uuid, unlike every other id on this resource, and it cannot be fed back into `parent_id` on create/update, which expects a uuid.", "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Side": { "title": "Side", "description": "`SideResource`. A print surface on a product: front, back, inner page, etc.\n\nGeometry is reported in grouped objects rather than the flat column names used\nin the database. `scale` on the response is the model's `ratio` column.\n\n`dimension_unit` is inherited from the owning product and is `\"\"` (empty\nstring, not null) when the side has no product.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scale": { "description": "Pixels per `dimension_unit`. Serialised from the `ratio` column.", "type": [ "number", "null" ], "format": "float" }, "dimension_unit": { "type": "string", "enum": [ "inch", "cm", "px", "" ] }, "status": { "type": "string", "enum": [ "publish", "draft", "trashed", "deleted" ] }, "design_area": { "description": "The printable area, in the product's dimension unit.", "properties": { "width": { "type": [ "number", "null" ], "format": "float" }, "height": { "type": [ "number", "null" ], "format": "float" }, "top": { "type": [ "number", "null" ], "format": "float" }, "left": { "type": [ "number", "null" ], "format": "float" } }, "type": "object" }, "show_cut_line": { "description": "Whether the bleed/cut line is drawn. Serialised from `show_bleed`.", "type": [ "boolean", "null" ] }, "cut_line_margin": { "description": "Bleed. `x` = left/right, `y` = top/bottom.", "properties": { "x": { "type": [ "number", "null" ], "format": "float" }, "y": { "type": [ "number", "null" ], "format": "float" } }, "type": "object" }, "show_safe_zone": { "type": [ "boolean", "null" ] }, "safe_zone_margin": { "properties": { "x": { "type": [ "number", "null" ], "format": "float" }, "y": { "type": [ "number", "null" ], "format": "float" } }, "type": "object" }, "side_image_size": { "description": "Size of the mockup image. Serialised from `product_width` / `product_height`.", "properties": { "width": { "type": [ "number", "null" ], "format": "float" }, "height": { "type": [ "number", "null" ], "format": "float" } }, "type": "object" }, "side_image": { "$ref": "#/components/schemas/Image" }, "product": { "$ref": "#/components/schemas/Product", "description": "Omitted when the side is embedded inside a Design." }, "bg_type": { "type": [ "string", "null" ], "enum": [ "color", "image", "transparent" ] }, "bg_color_value": { "type": [ "string", "null" ] }, "img_overlay": { "$ref": "#/components/schemas/Image" }, "background_included": { "type": [ "boolean", "null" ] }, "show_overlay": { "type": [ "boolean", "null" ] }, "include_overlay": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "area_design_type": { "type": [ "string", "null" ] }, "is_template": { "type": [ "boolean", "null" ] }, "parent_id": { "description": "Numeric parent side id, not a uuid.", "type": [ "integer", "null" ] }, "source_global_side_template": { "description": "Set when the side was created via import-from-template.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "link": { "type": "string" } }, "type": [ "object", "null" ] }, "lock_aspect_ratio": { "type": [ "boolean", "null" ] } }, "type": "object" }, "DesignTemplate": { "title": "Design template", "description": "`DesignTemplateResource`. `sides` is included on single-template reads only. Backed by the `side_templates` table — design templates and side templates are the same table with different presentation.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "preview": { "oneOf": [ { "$ref": "#/components/schemas/Image" }, { "type": "null" } ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "sides": { "description": "Single-template reads only.", "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "tier_required": { "$ref": "#/components/schemas/EntitlementBadge/properties/tier_required" }, "store_qualified": { "$ref": "#/components/schemas/EntitlementBadge/properties/store_qualified" }, "badge": { "$ref": "#/components/schemas/EntitlementBadge/properties/badge" } }, "type": "object" }, "SideTemplate": { "title": "Side template", "description": "`SideTemplateResource`. A reusable side geometry (with optional artwork) that can be imported onto a product.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "wix_recommended": { "type": "boolean" }, "wix_product_type": { "type": [ "string", "null" ] }, "preview": { "oneOf": [ { "$ref": "#/components/schemas/Image" }, { "type": "null" } ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "sides": { "description": "Single-template reads only.", "type": "array", "items": { "$ref": "#/components/schemas/Side" } }, "tier_required": { "$ref": "#/components/schemas/EntitlementBadge/properties/tier_required" }, "store_qualified": { "$ref": "#/components/schemas/EntitlementBadge/properties/store_qualified" }, "badge": { "$ref": "#/components/schemas/EntitlementBadge/properties/badge" } }, "type": "object" }, "DesignGroup": { "title": "Design group", "description": "`DesignGroupResource`. Backed by the `template_groups` table; reachable under both `/design-groups` and `/template-groups`.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "preview_image": { "$ref": "#/components/schemas/Image" }, "template_items": { "description": "Single-group GET only.", "type": "array", "items": { "$ref": "#/components/schemas/Design" } } }, "type": "object" }, "Font": { "title": "Font", "description": "`FontResource`. `url` is rewritten to the CDN base only for store-uploaded fonts; externally hosted fonts are returned verbatim.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "type": { "type": [ "string", "null" ] }, "subset": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Clipart": { "title": "Clipart (store library)", "description": "`MediaClipartResource`, returned by `/cliparts/mine` and `/cliparts/global`.\n\n`id` here is the **numeric** primary key, not a uuid — this resource predates\nthe uuid convention and was not migrated.\n\nThe older `/cliparts` endpoints return an `Image`-shaped payload instead.", "properties": { "id": { "type": "integer" }, "store_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "cate_id": { "type": [ "integer", "null" ] }, "file": { "type": "string", "format": "uri" }, "file_thumb": { "type": [ "string", "null" ] }, "file_size": { "description": "Bytes.", "type": [ "integer", "null" ] }, "alias": { "type": [ "string", "null" ] }, "tag": { "type": [ "string", "null" ] }, "tier_required": { "$ref": "#/components/schemas/EntitlementBadge/properties/tier_required" }, "store_qualified": { "$ref": "#/components/schemas/EntitlementBadge/properties/store_qualified" }, "badge": { "$ref": "#/components/schemas/EntitlementBadge/properties/badge" } }, "type": "object" }, "Design": { "title": "Design", "description": "`DesignResource`. A saved customizer document for one side (or one product,\nwhen the product has no sides).\n\n`layers` is the canvas document. It is stored as JSON and returned as JSON, but\nis **submitted as a JSON-encoded string** — see `DesignCreate.layers`.\n\n`designer` values other than `name` are masked with `*` when the owning account\nis on the `free` tier; `designer.is_pro` reports which branch was taken. The\nmasking is applied only on `/designs*` paths.", "properties": { "id": { "type": "string", "format": "uuid" }, "note": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "accepted", "processing", "declined", "trashed", "deleted" ] }, "side": { "description": "The side this design belongs to, with its own `product` key stripped. `null` when the design is attached directly to a product.", "oneOf": [ { "$ref": "#/components/schemas/Side" }, { "type": "null" } ] }, "product": { "$ref": "#/components/schemas/Product" }, "project": { "$ref": "#/components/schemas/Project", "description": "Omitted on `/projects/*` responses to avoid recursion." }, "preview_image": { "$ref": "#/components/schemas/Image" }, "design_image": { "$ref": "#/components/schemas/Image", "description": "The flattened print artwork. `width` and `height` are stripped from this copy." }, "original_side": { "description": "Snapshot of the side geometry at save time, so re-rendering is stable if the side is later edited.", "type": [ "object", "null" ], "additionalProperties": true }, "original_output_options": { "type": [ "object", "null" ], "additionalProperties": true }, "layers": { "description": "Canvas objects.", "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "viewport": { "properties": { "width": { "type": [ "number", "null" ], "format": "float" }, "height": { "type": [ "number", "null" ], "format": "float" } }, "type": "object" }, "preview": { "properties": { "mockup": { "$ref": "#/components/schemas/Image" }, "design": { "$ref": "#/components/schemas/Image" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "parent_id": { "type": [ "string", "null" ] }, "designer": { "description": "Free-form designer attribution plus the injected `is_pro` boolean.", "type": [ "object", "null" ], "additionalProperties": true }, "is_uploader": { "description": "`true` when the buyer uploaded finished artwork instead of designing in the customizer.", "type": [ "boolean", "null" ] } }, "type": "object" }, "Project": { "title": "Project (order)", "description": "`ProjectResource`. A project is Printcart's order object; when a store is\nconnected to a platform, one platform order becomes one project.\n\nMost commercial fields (`reference_order_id`, `customer_*`, `total_price`,\n`currency`, `shipping_price`, `tax`) are **derived at read time** from the\nfree-form `order_detail` blob written by whichever integration created the\nproject. They are best-effort: the resource probes a list of candidate paths\n(`customer.email`, `billing.email`, `shipping_address.email`, …) and returns the\nfirst non-empty one, falling back to the linked buyer record. Expect `null` for\nprojects created directly through the API with no `order_detail`.\n\n`total_price` falls back to summing `line_items` when no total is present.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "reviewing", "accepted", "in_production", "fulfilled", "canceled", "trashed", "deleted", "refunded" ] }, "note": { "type": [ "string", "null" ] }, "reference_order_id": { "description": "Platform order number pulled out of `order_detail`. String or integer depending on the source platform.", "type": [ "string", "integer", "null" ] }, "is_sample": { "type": "boolean" }, "order_detail": { "description": "Raw platform order payload. Present on `/projects` and `/projects/*` responses only.", "type": [ "object", "null" ], "additionalProperties": true }, "store_name": { "type": [ "string", "null" ] }, "customer_name": { "type": [ "string", "null" ] }, "customer_email": { "type": [ "string", "null" ], "format": "email" }, "customer_phone": { "type": [ "string", "null" ] }, "total_price": { "type": [ "number", "null" ], "format": "float" }, "currency": { "type": [ "string", "null" ] }, "shipping_price": { "type": [ "number", "null" ], "format": "float" }, "tax": { "type": [ "number", "null" ], "format": "float" }, "customer_orders_count": { "type": [ "integer", "null" ] }, "customer_ltv": { "type": [ "number", "null" ], "format": "float" }, "project_items": { "description": "Single-project reads only.", "type": "array", "items": { "$ref": "#/components/schemas/ProjectItem" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ProjectItem": { "title": "Project item (line item)", "description": "`ProjectItemResource`. The shape **changes depending on the URL**: on\n`/projects/*` it carries `quantity` + `designs`; everywhere else it carries\n`project` + `side` + `product` instead. The two variants share only `id`,\n`created_at` and `updated_at`.", "properties": { "id": { "type": "string", "format": "uuid" }, "project": { "$ref": "#/components/schemas/Project", "description": "Non-`/projects/*` paths only." }, "side": { "description": "Non-`/projects/*` paths only, and only when the item is a side.", "oneOf": [ { "$ref": "#/components/schemas/Side" }, { "type": "null" } ] }, "product": { "description": "Non-`/projects/*` paths only, and only when the item is a product.", "oneOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "null" } ] }, "quantity": { "description": "`/projects/*` paths only.", "type": "integer" }, "designs": { "description": "`/projects/*` paths only.", "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ProjectEvent": { "title": "Project event", "description": "An entry in a project's audit trail. Hand-assembled in `ProjectEventController`\nrather than by an API Resource, so it exposes the **numeric** `id` alongside the\n`uuid` — the only Wave-1 payload that does both.\n\n`metadata`, `actor_name`, `from_status` and `to_status` are returned by the list\nendpoint but not by the create endpoint.", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "actor_type": { "type": [ "string", "null" ] }, "actor_name": { "type": [ "string", "null" ] }, "actor_id": { "type": [ "string", "integer", "null" ] }, "from_status": { "type": [ "string", "null" ] }, "to_status": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Webhook": { "title": "Webhook subscription", "description": "`WebhookResource`. One subscription = one (topic, event) pair pointing at one\ncallback URL.\n\n**Delivery only happens when the backend runs with `APP_ENV=production`.** In\nany other environment `Webhooks::sendingWebhooks()` returns without\ndispatching, so a staging store will never call your endpoint.", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "POST", "PUT", "DELETE", "POST BATCH", "PUT BATCH", "DELETE BATCH" ] }, "callback_url": { "type": "string", "format": "uri" }, "topic": { "type": "string", "enum": [ "user", "projects", "products", "designs", "sides", "templates" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WebhookDelivery": { "title": "Webhook delivery (what Printcart POSTs to you)", "description": "The body Printcart sends to your `callback_url`.\n\n```json\n{ \"data\": { \"data\": { …resource… }, \"message\": \"Created successfully\" } }\n```\n\nThe outer `data` is added by the delivery job; the inner object is exactly the\nAPI Resource that the triggering request returned, including its `message`.\n\n### Signature verification\n\n- Header: `Signature`\n- Algorithm: `hash_hmac('sha256', json_encode(body), secret)`\n- Secret: base64(`sid:secret`) for store-scoped subscriptions — that is, the\n same string you put after `Basic ` in the Authorization header. For the\n platform-wide `user` topic the secret is the internal `WEBHOOK_USER_SECRET`.\n\nCompare with a constant-time comparison. Sign over the **raw request body**,\nnot a re-encoded copy.\n\n### Retries\n\n3 attempts, exponential backoff, 3-second request timeout. There is no replay\nendpoint and no delivery-log endpoint.", "properties": { "data": { "type": "object", "additionalProperties": true } }, "type": "object" }, "ApiKey": { "title": "API key", "description": "An API key as the API returns it. The secret half is structurally absent — it is\nreturned exactly once, in the `key` field beside this object, on creation and on\nrotation. There is no endpoint that can show it again; a lost key is rotated,\nnot recovered.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "description": "Decides the prefix and the blast radius.", "type": "string", "enum": [ "account_secret", "store_secret", "store_publishable" ] }, "name": { "description": "Label chosen at creation, for the audit trail.", "type": "string" }, "key_id": { "description": "Public identifier. Safe to log; appears in the events feed.", "type": "string" }, "last_four": { "type": "string" }, "masked": { "description": "Display form, e.g. `sk_live_…a1b2`.", "type": "string" }, "scopes": { "description": "Effective scopes: the custom set if one was given, otherwise the default for this `kind`.", "type": "array", "items": { "type": "string" } }, "custom_scopes": { "description": "True when the key was created with an explicit scope list rather than the default.", "type": "boolean" }, "allowed_origins": { "description": "Browser origins allowed to present this key. Empty = unrestricted.", "type": "array", "items": { "type": "string" } }, "allowed_ips": { "type": "array", "items": { "type": "string" } }, "store_uuid": { "description": "Present on store-scoped keys.", "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_ip": { "type": [ "string", "null" ] }, "use_count": { "type": "integer" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "grace_until": { "description": "Set by rotation: the old key keeps working until this moment, so a deploy cannot race a rotation.", "type": [ "string", "null" ], "format": "date-time" }, "status": { "description": "Derived from the timestamps above. `rotating` means a replacement exists and this key still works until `grace_until`.", "type": "string", "enum": [ "active", "rotating", "expired", "revoked" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "responses": { "Unauthorized": { "description": "Missing or invalid credential. Envelope depends on which middleware rejected the request: `basic`/`admin` return `{\"error\":{\"message\":…}}`, `unauth.token`/`auth.jwt` return `{\"message\":…}`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MessageError" } ] } } } }, "Forbidden": { "description": "Authenticated but not permitted. Upgrading a plan will not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "NotFound": { "description": "Resource does not exist, or belongs to another store. Cross-store access is reported as 404 so existence is never leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "ValidationFailed": { "description": "Validation failed. **HTTP 400, not 422.**", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "LimitTooLarge": { "description": "`limit` exceeded 100.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageError" } } } }, "StorageQuota": { "description": "Media storage cap reached (`entitlement.gate_mode=hard` only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageQuotaError" } } } }, "MultipartV2Invalid": { "description": "Validation failed. **HTTP 422** with a field-keyed `errors` bag — not the 400 `ValidationFailed` envelope used elsewhere.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The multipart upload metadata is invalid." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "MultipartV2StorageUnavailable": { "description": "S3 rejected or could not serve the multipart operation. Nothing was persisted; the upload is still `pending` and the call can be retried.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "code": { "type": "string", "example": "multipart_upload_backend_unavailable" } }, "type": "object" } } } } }, "parameters": { "limit": { "name": "limit", "in": "query", "description": "Page size. Default 20. Values above 100 are rejected, never silently clamped. Most list endpoints reject them as a **400** validation failure (`error.limit`); `/design-templates` and `/side-templates` answer **413** instead. Handle both.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, "cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor taken from `meta.next_cursor` / `meta.prev_cursor` of a previous response.", "required": false, "schema": { "type": "string" } }, "sort": { "name": "sort", "in": "query", "description": "Sort direction. Default `desc`.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, "sortBy": { "name": "sortBy", "in": "query", "description": "Column to order by. Default `id`. Not validated — an unknown column produces a 500.", "required": false, "schema": { "type": "string", "default": "id" } }, "search": { "name": "s", "in": "query", "description": "Free-text search. `search` is accepted as an alias.", "required": false, "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "**Not implemented as a general facility.** The API does not currently store and\nreplay POST responses by `Idempotency-Key`.\n\nIdempotency exists only where it is enforced in the data model:\n\n- wallet transactions and top-up sessions — `unique(wallet_id, idempotency_key)`\n- order handoffs, production-job events, procurement-request events\n- `PUT /side-templates/{sideTemplate}/products` accepts `idempotency_key` **in\n the JSON body** (not as a header) to de-duplicate asset contributions\n\nSending this header on any other POST has no effect. It is declared here so\nthat the eventual generalisation has a documented home, and so integrators are\nnot misled into believing retries are already safe.", "required": false, "schema": { "type": "string", "maxLength": 191 } }, "XRequestId": { "name": "X-Request-Id", "in": "header", "description": "**Not implemented.** The API neither emits nor echoes `X-Request-Id` today, and\nerror bodies carry no `request_id`. Support requests must currently be\ncorrelated by timestamp, store sid and endpoint.\n\nDeclared here so that the header has one documented definition when it is\nadded.", "required": false, "schema": { "type": "string" } }, "AcceptVersion": { "name": "Accept-Version", "in": "header", "description": "**Not implemented.** Sending this header has no effect on any response. There is exactly one version of every response shape today.", "required": false, "schema": { "type": "string", "example": "2026-09-01" } } }, "headers": { "X-RateLimit-Limit": { "description": "Requests permitted in the current window. Currently 1000/minute for every authenticated principal, keyed by principal id (or client IP when unauthenticated). The limit is **not** tier-dependent today.", "schema": { "type": "integer", "example": 1000 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "example": 999 } }, "Retry-After": { "description": "Seconds to wait before retrying. Present on 429 responses only.", "schema": { "type": "integer", "example": 42 } }, "X-RateLimit-Reset": { "description": "Unix timestamp at which the current window resets. Present on 429 responses only.", "schema": { "type": "integer" } }, "X-Printcart-Storage": { "description": "Emitted on a successful upload when the store is over its media cap and `entitlement.gate_mode` is `soft`, e.g. `over; used=12.40; cap=10.00; tier=free`. Never emitted in the default `off` mode.", "schema": { "type": "string" } } }, "securitySchemes": { "apiKey": { "type": "http", "description": "A first-class Printcart API key — the scheme to build against. Everything below\nit is legacy and carries a deprecation header.\n\n Authorization: Bearer sk_live_…\n\nThree prefixes, three blast radii:\n\n| Prefix | Scope | Where it may live |\n|---|---|---|\n| `sk_acc_live_…` | account — every store on the account | server only |\n| `sk_live_…` | one store, secret | server only |\n| `pk_live_…` | one store, publishable | safe in a browser bundle |\n\nA publishable key deliberately carries a narrower default scope set than the\nlegacy unauth token, so swapping one for the other is not a like-for-like\nsubstitution — check the scope catalog first.\n\nKeys are created, rotated and revoked through `/account/api-keys` and\n`/stores/{store}/api-keys`. Rotation issues the replacement immediately and\nleaves the old key valid for a grace period, so a deploy never races a rotation.\nEvery use is recorded; `GET .../api-keys/{key}/events` is the audit trail.\n\n`X-Printcart-Key: ` performs the same lookup, for clients that cannot set\nan `Authorization` header. Call `GET /auth/whoami` to see what a credential\nactually resolves to.", "scheme": "bearer" }, "storeBasic": { "type": "http", "description": "HTTP Basic where the username is the store `sid` and the password is the store\n`secret`, i.e. `Authorization: Basic ` + base64(`sid:secret`).\n\nBoth values are returned by `GET /stores/store-details` and by the store\ncredential endpoints. `secret` is a server-side-only credential — never ship it\nto a browser.\n\nImplemented by `App\\Http\\Middleware\\AuthBasic`. On failure it returns **401**\nwith `{\"error\":{\"message\":\"Unauthorized.\"}}`.", "scheme": "basic" }, "unauthToken": { "type": "apiKey", "description": "The store's public token, safe to embed in a storefront or customizer bundle.\nReturned as `unauth_token` / `api_key` on the store credential payload.\n\nImplemented by `App\\Http\\Middleware\\UnAuthToken`. That middleware also accepts\n`Authorization: Basic sid:secret` and `Bearer ` + `X-PrintCart-Store-Sid`.\nOn failure it returns **401** with `{\"message\":\"Unauthorized.\"}` — note the\nenvelope differs from the Basic middleware's.", "name": "X-PrintCart-Unauth-Token", "in": "header" }, "accountJwt": { "type": "http", "description": "Account-level JWT issued by `POST /account/signIn` (or `GET /account/render-jwt`\nwhen already holding store credentials). Resolves a `User`, not a `Store`.\n\nTo act on a specific store the JWT must be accompanied by the\n`X-PrintCart-Store-Sid` header (`storeSid` scheme); the store must belong to the\nauthenticated user, otherwise the request is rejected as unauthorized.", "bearerFormat": "JWT", "scheme": "bearer" }, "storeSid": { "type": "apiKey", "description": "Selects which of the account's stores a JWT-authenticated request acts on.\nRequired alongside `accountJwt` on every store-scoped operation. Sending a JWT\nwithout this header on a store-scoped route yields **401**, not 403.", "name": "X-PrintCart-Store-Sid", "in": "header" } } }, "security": [ { "storeBasic": [] } ], "tags": [ { "name": "Authentication", "description": "Account creation, sign-in, JWT issue, password reset, store credential rotation." }, { "name": "Stores", "description": "Store lifecycle, settings, public profile and API credentials." }, { "name": "Products", "description": "Product CRUD, batch operations, variants, images and categories." }, { "name": "Sides", "description": "Print sides: geometry, bleed, safe zone, background and overlay artwork." }, { "name": "Templates", "description": "Design templates, side templates, template categories and storages." }, { "name": "Fonts & assets", "description": "Fonts, cliparts, images and chunked multipart upload. Two multipart families: `/multipart-uploads-v2/*` issues a presigned PUT URL per part so bytes go straight to S3 (prefer it for large files, and it can be aborted), while the older `/multipart/*` proxies every part through the API and takes the upload id in the body rather than the path." }, { "name": "Designs", "description": "Saved designs, template designs, fonts-by-layer and print-ready output generation." }, { "name": "Projects", "description": "Projects (orders), project items, project events and folders." }, { "name": "Webhooks", "description": "Outbound webhook subscriptions, topics, payload shape and signature verification." } ] }