{ "openapi": "3.1.0", "info": { "title": "PRINTOOLS API", "version": "1.0.0", "description": "The PRINTOOLS public REST API. This document is generated from the live route table and service GraphQL SDL; do not edit it by hand.\n\nEvery 2xx response has {status, message, data}. Every non-2xx response has {error, message, status: false}.\n\nTenant credential: send X-API-Key only. It is bound to one shop. X-PrintTools-Organization-Id is optional for that credential and, if sent, must match its shop.\n\nPartner credential: send X-API-Key, X-API-Secret, Authorization: Bearer , and X-PrintTools-Organization-Id. The OAuth flow is documented at https://app.printools.io/api/index.html#partner-auth.\n\nRead live limits from GET /v1/reference/limits. Field shapes are projected from operation declarations; local endpoints have explicit handler-derived schemas." }, "servers": [ { "url": "https://api.printools.io", "description": "Production" } ], "externalDocs": { "description": "Getting started, OAuth and webhook guidance", "url": "https://app.printools.io/api/index.html" }, "components": { "securitySchemes": { "tenantApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Tenant credential. This is sufficient by itself." }, "partnerApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Partner application client ID." }, "partnerApiSecret": { "type": "apiKey", "in": "header", "name": "X-API-Secret", "description": "Partner application secret." }, "partnerBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Cognito access token obtained through OAuth." } }, "schemas": { "Success": { "type": "object", "required": [ "status", "message", "data" ], "properties": { "status": { "type": "boolean", "description": "The actual resolver result. It can be false when an operation returns false or null without throwing." }, "message": { "type": "string", "example": "OK" }, "data": {} }, "description": "Every 2xx response uses this envelope." }, "Error": { "type": "object", "required": [ "error", "message", "status" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string" }, "status": { "type": "boolean", "const": false } }, "description": "Every non-2xx response uses this envelope." }, "Output_QuotePage": { "type": "object", "description": "A page of quotes plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Quote" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Input_ListFilterInput": { "type": "object", "description": "One advanced-filter condition for a list query — mirrors the client's\nFilterBuilderButton. Shared across list services (see quote-service for the\nfull field docs).", "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "field", "op" ] }, "Output_QuoteFacets": { "type": "object", "description": "Distinct values for the quotes list's select filters (sales rep).", "properties": { "salesReps": { "type": "array", "items": { "type": "string" } } }, "required": [ "salesReps" ] }, "Output_Quote": { "type": "object", "properties": { "id": { "type": "string" }, "quoteRef": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "clientId": { "type": "string" }, "contactId": { "type": "string" }, "shippingAddressId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "deliveryMethod": { "type": "string" }, "deliveryDate": { "type": "string", "format": "date" }, "productionDeadline": { "type": "string", "format": "date" }, "invoiceDueDate": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "subtotalExGst": { "type": "number" }, "gstAmount": { "type": "number" }, "totalIncGst": { "type": "number" }, "taxRateId": { "type": "string" }, "taxName": { "type": "string" }, "taxRatePct": { "type": "number" }, "mockId": { "type": "string" }, "jobId": { "type": "string" }, "jobRef": { "type": "string", "description": "The linked job's own `jobRef` (CB-05), resolved server-side from the job row —\nnever derived from `jobId`. Null when the quote has no job, when `jobId` points\nat a row that no longer exists (these link columns carry no FK) or is not\nvisible to the caller's tenant, and when the linked job's own ref is null.\nRead-only: no mutation input sets it." }, "invoiceId": { "type": "string" }, "invoiceStatus": { "type": "string" }, "sentToEmail": { "type": "string" }, "sentAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Output_QuoteGroup" } } }, "required": [ "id", "status", "subtotalExGst", "gstAmount", "totalIncGst", "createdAt", "updatedAt", "groups" ] }, "Input_CreateQuoteInput": { "type": "object", "properties": { "quoteRef": { "type": "string" }, "status": { "type": "string" }, "reference": { "type": "string" }, "clientId": { "type": "string" }, "contactId": { "type": "string" }, "shippingAddressId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "notes": { "type": "string" } } }, "Input_UpdateQuoteInput": { "type": "object", "properties": { "quoteRef": { "type": "string" }, "status": { "type": "string" }, "reference": { "type": "string" }, "clientId": { "type": "string" }, "contactId": { "type": "string" }, "shippingAddressId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "deliveryMethod": { "type": "string" }, "deliveryDate": { "type": "string", "format": "date" }, "productionDeadline": { "type": "string", "format": "date" }, "invoiceDueDate": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "subtotalExGst": { "type": "number" }, "gstAmount": { "type": "number" }, "totalIncGst": { "type": "number" }, "taxRateId": { "type": "string" }, "taxName": { "type": "string" }, "taxRatePct": { "type": "number" } } }, "Input_SendQuoteInput": { "type": "object", "properties": { "emailTo": { "type": "string" }, "emailSubject": { "type": "string" }, "emailBodyMarkdown": { "type": "string" }, "ccSelfEmail": { "type": "string" } }, "required": [ "emailTo", "emailSubject", "emailBodyMarkdown" ] }, "Output_Job": { "type": "object", "properties": { "id": { "type": "string" }, "jobRef": { "type": "string" }, "jobName": { "type": "string" }, "status": { "type": "string" }, "quoteId": { "type": "string" }, "quoteRef": { "type": "string", "description": "The linked quote's own `quoteRef` (CB-05), resolved server-side from the quote\nrow — never derived from `quoteId`. Null when the job has no quote, when\n`quoteId` points at a row that no longer exists (these link columns carry no\nFK) or is not visible to the caller's tenant, and when the linked quote's own\nref is null. Read-only: no mutation input sets it." }, "customerId": { "type": "string" }, "contactId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "reference": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Enum_JobPriority" }, "shipPickupDate": { "type": "string", "format": "date" }, "productionDeadline": { "type": "string", "format": "date" }, "deliveryMethod": { "type": "string" }, "shippingBranding": { "type": "string" }, "shippingAddressId": { "type": "string" }, "paymentType": { "type": "string" }, "invoiceStatus": { "type": "string" }, "lastQuoteSyncDate": { "type": "string", "format": "date-time" }, "quoteOutOfSync": { "type": "boolean", "description": "True when this job was created from a quote (`quoteId` set) AND the source\nquote has been edited since the last conversion/sync — i.e. the quote's\n`updatedAt` is newer than the job's `lastQuoteSyncDate`. The Converted quote\nstays editable, so this flags that the job tree has drifted from the quote;\ncall `syncJobFromQuote` to re-clone. Always false for jobs with no quote." }, "totalQuantity": { "type": "integer", "description": "READ-ONLY units of CLOTHING on the whole job (CU-86d427fpb) — the sum, over\nthe garment lines of every group, of each line's variant quantities, falling\nback to the line's own `quantity` when it has no variants. Money lines\n(`Other`) contribute nothing: they carry no garment (JB-05).\n\nComputed at read time, not stored, and NOT a sum of the groups'\n`totalQuantity` — that column is written when a job is cloned from its quote\nand does not follow later line edits, so the two can disagree. This one\nalways matches what the job screen totals.\n\n0 for a job with no lines. That is a real answer, not an absence — no\nmutation input sets this field." }, "poStatus": { "$ref": "#/components/schemas/Enum_JobPoStatus", "description": "READ-ONLY, computed at read time from the job's linked ACTIVE Purchase Orders\n(cancelled/inactive POs excluded), rolled up across them (Phase 2.5):\nNotCreated (no PO) · Created (POs exist, none sent yet) · Sent (≥1 PO past\napproved) · Received (all POs received/completed). Not stored; no mutation\nsets it." }, "materialsStatus": { "$ref": "#/components/schemas/Enum_JobMaterialsStatus", "description": "READ-ONLY, computed at read time from the active POs' line items (Phase 2.5):\nNotPurchased (no PO / no line items) · Ordered (some line items not yet\nreceived) · Received (all line items received). Not stored; no mutation sets it." }, "scheduledStartDate": { "type": "string", "format": "date" }, "scheduledEndDate": { "type": "string", "format": "date" }, "estimatedDuration": { "type": "number" }, "jobNotes": { "type": "string" }, "clientNotes": { "type": "string" }, "customFieldValues": { "description": "Operator custom-field VALUES keyed by field id (definitions in orgSettings)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobGroup" } }, "activity": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobActivity" } } }, "required": [ "id", "status", "priority", "invoiceStatus", "quoteOutOfSync", "totalQuantity", "poStatus", "materialsStatus", "estimatedDuration", "customFieldValues", "createdAt", "updatedAt", "groups", "activity" ] }, "Output_QuoteGroup": { "type": "object", "properties": { "id": { "type": "string" }, "quoteId": { "type": "string" }, "name": { "type": "string" }, "totalQuantity": { "type": "integer" }, "sortOrder": { "type": "integer" }, "rollUpDecoration": { "type": "boolean" }, "rollUpSetup": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Output_QuoteLine" }, "description": "`lines` and `decorations` are two collections sharing ONE `sortOrder`\nsequence (F-26). To render a group in the operator's order, merge them and\nsort by `sortOrder` — do not concatenate lines-then-decorations, which is\nwhat made a surcharge unable to sit below a decoration. To reorder, renumber\nacross BOTH collections." }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Output_QuoteGroupDecoration" } } }, "required": [ "id", "quoteId", "name", "totalQuantity", "sortOrder", "rollUpDecoration", "rollUpSetup", "createdAt", "updatedAt", "lines", "decorations" ] }, "Input_CreateQuoteGroupInput": { "type": "object", "properties": { "quoteId": { "type": "string" }, "name": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "quoteId", "name" ] }, "Input_UpdateQuoteGroupInput": { "type": "object", "properties": { "name": { "type": "string" }, "totalQuantity": { "type": "integer" }, "sortOrder": { "type": "integer" }, "rollUpDecoration": { "type": "boolean" }, "rollUpSetup": { "type": "boolean" } } }, "Output_QuoteLine": { "type": "object", "properties": { "id": { "type": "string" }, "quoteGroupId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "valueType": { "$ref": "#/components/schemas/Enum_LineValueType", "description": "Flat or Percentage. Applies to a Discount AND (F-26) a Surcharge — a rate on\na line, whichever direction it points." }, "percentage": { "type": "number", "description": "The rate, when valueType is Percentage. Null otherwise." }, "discountValueType": { "$ref": "#/components/schemas/Enum_DiscountValueType" }, "discountPercentage": { "type": "number" }, "customImageUrl": { "type": "string", "description": "Per-line image override; null falls back to the catalogue thumbnail." }, "sortOrder": { "type": "integer", "description": "Position in the group's row sequence — shared with the group's DECORATIONS\nsince F-26, so a surcharge or discount can sit below a decoration. Omit on\ncreate to append." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Output_QuoteVariant" } } }, "required": [ "id", "quoteGroupId", "lineType", "productName", "quantity", "unitPriceExGst", "sortOrder", "createdAt", "updatedAt", "variants" ] }, "Input_CreateQuoteLineInput": { "type": "object", "properties": { "quoteGroupId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "unitPriceExGst": { "type": "number" }, "quantity": { "type": "integer" }, "valueType": { "$ref": "#/components/schemas/Enum_LineValueType" }, "percentage": { "type": "number" }, "discountValueType": { "$ref": "#/components/schemas/Enum_DiscountValueType", "description": "Deprecated alias of valueType (F-26). valueType wins when both are sent." }, "discountPercentage": { "type": "number", "description": "Deprecated alias of percentage (F-26). percentage wins when both are sent." }, "sortOrder": { "type": "integer", "description": "Omit to append to the end of the group's row sequence (lines + decorations)." }, "customImageUrl": { "type": "string" } }, "required": [ "quoteGroupId", "productName" ] }, "Input_QuoteVariantInput": { "type": "object", "properties": { "size": { "type": "string" }, "colour": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "buyPrice": { "type": "number" }, "extraCost": { "type": "number" }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType" }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → `manual`, the safe answer for any client that does not know about\nownership yet. A client that let a group resolve the markup must send\n`group` EXPLICITLY (CU-86d46hu37 AC 12)." }, "isCustomLine": { "type": "boolean" }, "showOnDocuments": { "type": "boolean", "description": "Omitted → rolled up, the default for every custom variant (QU-02)." }, "sortOrder": { "type": "integer" } }, "required": [ "quantity" ] }, "Input_UpdateQuoteLineInput": { "type": "object", "properties": { "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "valueType": { "$ref": "#/components/schemas/Enum_LineValueType" }, "percentage": { "type": "number" }, "discountValueType": { "$ref": "#/components/schemas/Enum_DiscountValueType", "description": "Deprecated alias of valueType (F-26). valueType wins when both are sent." }, "discountPercentage": { "type": "number", "description": "Deprecated alias of percentage (F-26). percentage wins when both are sent." }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string" } } }, "Output_QuoteGroupDecoration": { "type": "object", "properties": { "id": { "type": "string" }, "quoteGroupId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod", "description": "The decoration technique. Recorded from the quote stage since CU-86d43a1qr —\nit is agreed with the customer when the price is, not discovered on the floor.\nSame enum as `JobGroupDecoration.method`, and literally the same Postgres\ntype, so conversion copies it." }, "position": { "type": "string", "description": "Where the print goes — FREE TEXT (CU-86d4571me).\n\nWas a nine-value enum whose escape hatch was `Other`, which could not carry\nwhat the \"other\" actually was: \"2cm down from neckline\", \"side of caps\",\n\"over pocket\", \"under collar\". An escape hatch that cannot hold the\nexplanation is not one, and the shop floor was reading a bare \"Other\".\n\nIt also ABSORBS the old `placement`, which was a second free-text field for\nthe same fact (\"2cm below collar\", \"centred on pocket\"). Two fields meant two\nplaces to look and two chances to disagree; there is one now.\n\nThe nine former values (Front, Back, Left Sleeve, Right Sleeve, Neck,\nLower Back, Left Chest, Right Chest, Other) are CLIENT-SIDE SUGGESTIONS\nONLY — the server constrains nothing but trims the value and caps its\nlength. Stored as the display label, so the job, the proof, the PDF, the\nportal and the job sheet all show the same string.\n\nNull means no position has been named. Empty is refused rather than stored." }, "quantity": { "type": "integer" }, "setupCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "unitCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The markup connecting the per-unit COST to the per-unit CHARGE, stored so it\nsurvives a reopen (CU-86d46hu37).\n\nA decoration used to persist nothing here: the client back-solved a markup\nfrom cost and charge every time the dialog opened, which is why a decoration\nsaved with a PERCENTAGE markup always reopened showing a flat dollar amount —\na back-solved percentage is rarely exact, so the back-solve had to prefer\nflat. Null on rows written before these columns existed; those still\nback-solve, exactly as every row did before." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Who owns the per-unit markup — see `MarkupSource`. `group` re-bands on every\nquantity or cost move; `manual` never does." }, "setupMarkupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The same three facts for the SETUP lane, which is a genuinely separate\nmarkup: a setup markup group is matched by `appliesToSetupCost` (exclusive of\nthe per-unit groups) and bands on the SETUP cost, not the per-unit one. One\nlane can be group-owned while the other is not.\n\nInert unless `includeSetupCost` — there is no charge to mark up when the\nsetup is not being charged." }, "setupMarkupValue": { "type": "number" }, "setupMarkupSource": { "$ref": "#/components/schemas/Enum_MarkupSource" }, "rollUp": { "type": "boolean", "description": "Fold this decoration's UNIT charge into the garment unit price rather than\npricing it on its own row (CU-86d416yvz).\n\nPER DECORATION. `QuoteGroup.rollUpDecoration` folded every decoration in the\ngroup or none of them, which made the dialog's per-decoration toggle a lie —\nturning it on for the embroidery also folded the screen print. The group\nflags are still readable this release and no longer feed the calculation.\n\nDisplay only: the group subtotal, the quote total and the margin are the\nsame number either way. What changes is where the customer reads the money." }, "rollUpSetup": { "type": "boolean", "description": "Same for the SETUP charge. Inert unless `includeSetupCost` is true — there is\nnothing to fold when the setup is not being charged, the pairing the group\nflag already had." }, "showOnDocuments": { "type": "boolean", "description": "Draw this decoration's row on customer-facing documents at all.\n\nDistinct from `rollUp`, and they answer different questions — the quote\ndocument, the PDF and the portal all honour both:\n\n rollUp only the row is listed, its price reads \"Included\"\n rollUp + hidden no row anywhere; the money is inside the garment price\n\nHidden with `rollUp: false` would leave the itemised rows summing to less\nthan the customer pays, so hiding a row implies the fold.\n\nDefaults true — every decoration prints today and this must not change how a\nlive quote reads. Note the opposite default to `QuoteVariant.showOnDocuments`,\nwhich folds by default because a courier fee itemised as a garment variant\nwas the complaint there." }, "description": { "type": "string" }, "widthCm": { "type": "number", "description": "Print dimensions in CENTIMETRES (BE-04 / Q-24 / CU-86d43a1qr). The unit is\nfixed by the schema, not stored per row — renderers print \"30 × 25 cm\"; the\ncolumn only ever holds the number. Nullable: most decorations carry no\ndimensions, and 0 is a measurement, not an absence.\n\nThese were `width`/`height` in millimetres until CU-86d43a1qr, while the proof\nspec describing the same print stored centimetres — so one job printed\n`300 × 250 mm` on the quote and `30 × 25 cm` on the proof. Every stage stores\ncm now and nothing converts." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number", "description": "How far below the collar the print starts, in cm." }, "screenCount": { "type": "integer", "description": "Screens to burn — screen printing only. Null when it does not apply." }, "screenMeshGrade": { "type": "string", "description": "Mesh grade for those screens, e.g. `156`." }, "colourCount": { "type": "integer", "description": "How many ink colours the print uses. Free of `colours` — an operator can price a 4-colour print before naming the inks." }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationColour" }, "description": "The inks, in the operator's order. At most one is flagged `isBase`, and it renders first." }, "specialInstructions": { "type": "string", "description": "Internal shop notes — **never customer-facing**. Named to match\n`JobGroupDecoration.specialInstructions` so quote and job share one\nvocabulary. `description` is the Title and prints on the quote document, so\nit could not be reused for this. Deliberately absent from\n`PortalQuoteDecoration` and from the PDF renderer — internal by\nconstruction, the way `Mock.layers` is withheld from `PortalMock`." }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Position in the group's row sequence — the SAME sequence as the group's\nLINES since F-26, not a separate one. Omit on create to append." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "quoteGroupId", "quantity", "baseUnitCost", "baseSetupCost", "includeSetupCost", "markupSource", "setupMarkupSource", "rollUp", "rollUpSetup", "showOnDocuments", "colours", "sortOrder", "createdAt", "updatedAt" ] }, "Input_CreateQuoteGroupDecorationInput": { "type": "object", "properties": { "quoteGroupId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The per-unit markup as saved — see QuoteGroupDecoration.markupType." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual. A group-resolved markup must send `group` explicitly (AC 12)." }, "setupMarkupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The setup lane's own markup — see QuoteGroupDecoration.setupMarkupType." }, "setupMarkupValue": { "type": "number" }, "setupMarkupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual, as for markupSource." }, "rollUp": { "type": "boolean", "description": "Fold this decoration's unit charge into the garment price — see QuoteGroupDecoration.rollUp." }, "rollUpSetup": { "type": "boolean", "description": "Fold its setup charge. Inert unless includeSetupCost." }, "showOnDocuments": { "type": "boolean", "description": "Draw the row on customer-facing documents. Defaults true." }, "description": { "type": "string" }, "widthCm": { "type": "number", "description": "Centimetres — see QuoteGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "specialInstructions": { "type": "string", "description": "Internal only — see QuoteGroupDecoration.specialInstructions." }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "quoteGroupId" ] }, "Input_UpdateQuoteGroupDecorationInput": { "type": "object", "properties": { "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The per-unit markup as saved — see QuoteGroupDecoration.markupType." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual. A group-resolved markup must send `group` explicitly (AC 12)." }, "setupMarkupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The setup lane's own markup — see QuoteGroupDecoration.setupMarkupType." }, "setupMarkupValue": { "type": "number" }, "setupMarkupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual, as for markupSource." }, "rollUp": { "type": "boolean", "description": "Fold this decoration's unit charge into the garment price — see QuoteGroupDecoration.rollUp." }, "rollUpSetup": { "type": "boolean", "description": "Fold its setup charge. Inert unless includeSetupCost." }, "showOnDocuments": { "type": "boolean", "description": "Draw the row on customer-facing documents. Defaults true." }, "description": { "type": "string" }, "widthCm": { "type": "number", "description": "Centimetres — see QuoteGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "specialInstructions": { "type": "string", "description": "Internal only — see QuoteGroupDecoration.specialInstructions." }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "Output_BulkResult": { "type": "object", "description": "The one shape every bulk mutation answers in, so the client renders one summary.\n`requested` is what the target RESOLVED to on the server, not what the client\nguessed. `refused` and `failed` are counted separately on purpose: a rule\ndeclining a row (an AS Colour garment, a draft purchase order) is not a failure,\nand collapsing the two makes correct behaviour read as breakage.\n\nShared across list services.", "properties": { "requested": { "type": "integer" }, "affected": { "type": "integer" }, "refused": { "type": "integer" }, "failed": { "type": "integer" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/Output_BulkItemOutcome" } } }, "required": [ "requested", "affected", "refused", "failed", "outcomes" ] }, "Input_BulkTargetInput": { "type": "object", "description": "A bulk selection, as it travels to a bulk mutation. Exactly ONE branch is\npopulated: `ids` for hand-picked rows (the common case), or the filter branch\n(`filters` / `search` / `excludeIds`) for \"select all matching\". Supplying both\nis a validation error rather than a silent reconciliation.\n\nThe filter branch reuses the SAME `ListFilterInput` the list query was issued\nwith, so bulk never grows a second filter language, and `excludeIds` carries the\nrows the operator un-ticked while select-all-matching was on.\n\nThe filter branch is RE-EVALUATED AT EXECUTION TIME: a row created between the\noperator ticking select-all-matching and confirming IS included. That is the\nhonest meaning of \"everything matching this filter\", and it is why a confirm\ndialog must show `bulkTargetCount`'s answer rather than a client-side tally.\n\nShared across list services.", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ListFilterInput" } }, "search": { "type": "string" }, "excludeIds": { "type": "array", "items": { "type": "string" } } } }, "Output_JobPage": { "type": "object", "description": "A page of jobs plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Job" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Output_JobFacets": { "type": "object", "description": "Distinct values for the jobs list's select filters (sales rep).", "properties": { "salesReps": { "type": "array", "items": { "type": "string" } } }, "required": [ "salesReps" ] }, "Output_JobActivity": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "taskId": { "type": "string", "description": "The production task this entry is about, when it is about one — task-scoped\nentries are links, and this is what they open. Null for job-level events, and\nnull again once the task is deleted: the entry deliberately outlives the task,\nbecause the record of what was done to it is the point. Render a null-task\nentry as plain text, never as a dead link." }, "activityType": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "description": "A system row's detail line, or — on a comment — the comment body itself." }, "performedBy": { "type": "string", "description": "The actor's email. On a comment, its author." }, "editedAt": { "type": "string", "format": "date-time", "description": "Set once a comment has been edited. Always null on a system row." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "jobId", "activityType", "title", "createdAt" ] }, "Input_CreateJobInput": { "type": "object", "description": "Blank-job creation (createJob). All optional; status defaults to 'Draft'.", "properties": { "jobName": { "type": "string" }, "status": { "type": "string" }, "customerId": { "type": "string" }, "contactId": { "type": "string" }, "reference": { "type": "string" }, "jobNotes": { "type": "string" } } }, "Input_UpdateJobInput": { "type": "object", "properties": { "jobRef": { "type": "string" }, "jobName": { "type": "string" }, "status": { "type": "string" }, "contactId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "reference": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Enum_JobPriority" }, "shipPickupDate": { "type": "string", "format": "date" }, "productionDeadline": { "type": "string", "format": "date" }, "deliveryMethod": { "type": "string" }, "shippingBranding": { "type": "string" }, "shippingAddressId": { "type": "string" }, "paymentType": { "type": "string" }, "invoiceStatus": { "type": "string" }, "scheduledStartDate": { "type": "string", "format": "date" }, "scheduledEndDate": { "type": "string", "format": "date" }, "estimatedDuration": { "type": "number" }, "jobNotes": { "type": "string" }, "clientNotes": { "type": "string" }, "customFieldValues": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "Output_JobGroup": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "name": { "type": "string" }, "totalQuantity": { "type": "integer" }, "sortOrder": { "type": "integer" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobLine" } }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobGroupDecoration" } } }, "required": [ "id", "jobId", "name", "totalQuantity", "sortOrder", "createdAt", "updatedAt", "lines", "decorations" ] }, "Input_CreateJobGroupInput": { "type": "object", "properties": { "jobId": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "jobId", "name" ] }, "Input_UpdateJobGroupInput": { "type": "object", "properties": { "name": { "type": "string" }, "totalQuantity": { "type": "integer" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "Output_JobLine": { "type": "object", "properties": { "id": { "type": "string" }, "jobGroupId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string", "description": "The image the FLOOR should look at: the Quick Mock composite carried over from\n`QuoteLine.customImageUrl` at conversion, or null to fall back to the garment's\ncatalogue photo. A snapshot, deliberately — revising the mock later must not\nchange what a job already in production is printing." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobVariant" } } }, "required": [ "id", "jobGroupId", "lineType", "productName", "quantity", "unitPriceExGst", "sortOrder", "createdAt", "updatedAt", "variants" ] }, "Input_CreateJobLineInput": { "type": "object", "properties": { "jobGroupId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "unitPriceExGst": { "type": "number" }, "quantity": { "type": "integer" }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string" } }, "required": [ "jobGroupId", "productName" ] }, "Input_JobVariantInput": { "type": "object", "properties": { "size": { "type": "string" }, "colour": { "type": "string" }, "quantity": { "type": "integer" }, "producedQuantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "buyPrice": { "type": "number" }, "extraCost": { "type": "number" }, "sortOrder": { "type": "integer" } }, "required": [ "quantity" ] }, "Input_UpdateJobLineInput": { "type": "object", "properties": { "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string", "description": "Omitted leaves the stored image alone, so the wizard rewriting a job's lines\ncannot blank a mock it does not know about. Explicit null clears it — the same\ncontract `UpdateQuoteLineInput.customImageUrl` already uses." } } }, "Output_JobGroupDecoration": { "type": "object", "properties": { "id": { "type": "string" }, "jobGroupId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "description": { "type": "string" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationColour" }, "description": "The inks, in the operator's order. At most one is flagged `isBase`, and it renders first." }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "setupCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "unitCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "widthCm": { "type": "number", "description": "Print dimensions in CENTIMETRES, carried across by `convertQuoteToJob` — the\nfloor needs them (BE-04 / Q-24). See `QuoteGroupDecoration.widthCm` for why\nthe unit is no longer millimetres." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number", "description": "How far below the collar the print starts, in cm." }, "specialInstructions": { "type": "string" }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "jobGroupId", "colours", "baseUnitCost", "baseSetupCost", "includeSetupCost", "sortOrder", "createdAt", "updatedAt" ] }, "Input_CreateJobGroupDecorationInput": { "type": "object", "properties": { "jobGroupId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "description": { "type": "string" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "widthCm": { "type": "number", "description": "Centimetres — see JobGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "specialInstructions": { "type": "string" }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "jobGroupId" ] }, "Input_UpdateJobGroupDecorationInput": { "type": "object", "properties": { "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "description": { "type": "string" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "widthCm": { "type": "number", "description": "Centimetres — see JobGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "specialInstructions": { "type": "string" }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "Input_BulkJobPatchInput": { "type": "object", "description": "Fields a bulk job update may set. Every field is optional and an omitted field is\nleft untouched — this is a PATCH, not a replacement.\n\n`customFieldValues` carries ST-01 status-group values and is MERGED into each\nrow's existing blob. That distinction is load-bearing: the column holds every\nstatus group and custom field on the job, so a replacing write would silently\nwipe Fulfilment on 200 jobs while the operator was setting Shipping.", "properties": { "status": { "type": "string" }, "priority": { "type": "string" }, "salesRepEmail": { "type": "string" }, "customFieldValues": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "Output_CustomerPage": { "type": "object", "description": "A page of customers plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Customer" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Output_Customer": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_CustomerKind" }, "name": { "type": "string" }, "businessName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "abn": { "type": "string" }, "tier": { "type": "string" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "portalToken": { "type": "string" }, "defaultBillingAddressId": { "type": "string" }, "defaultShippingAddressId": { "type": "string" }, "primaryContactId": { "type": "string" }, "archivedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Contact" } }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Output_CustomerAddress" } } }, "required": [ "id", "kind", "isActive", "createdAt", "updatedAt", "contacts", "addresses" ] }, "Input_CreateCustomerInput": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_CustomerKind" }, "businessName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "abn": { "type": "string" }, "tier": { "type": "string" }, "notes": { "type": "string" }, "portalToken": { "type": "string" } }, "required": [ "kind" ] }, "Input_UpdateCustomerInput": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_CustomerKind" }, "businessName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "abn": { "type": "string" }, "tier": { "type": "string" }, "notes": { "type": "string" }, "defaultBillingAddressId": { "type": "string" }, "defaultShippingAddressId": { "type": "string" }, "primaryContactId": { "type": "string" } } }, "Output_Contact": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "isPrimary": { "type": "boolean" }, "fullName": { "type": "string" }, "roleTitle": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "includeInAccountingEmails": { "type": "boolean", "description": "Copy this person on the accounting provider's outgoing documents. Maps onto\nXero's `ContactPerson.IncludeInEmails` — the only recipient switch Xero\nexposes, and a property of the PERSON on the business record because a Xero\ninvoice has no per-invoice recipient field.\n\nDefaults false: only the business's own address is written to until the shop\ndeliberately opts somebody in." } }, "required": [ "id", "customerId", "isPrimary", "fullName", "createdAt", "updatedAt", "includeInAccountingEmails" ] }, "Input_CreateContactInput": { "type": "object", "properties": { "customerId": { "type": "string" }, "fullName": { "type": "string" }, "isPrimary": { "type": "boolean" }, "roleTitle": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": "string" }, "includeInAccountingEmails": { "type": "boolean" } }, "required": [ "customerId", "fullName" ] }, "Input_UpdateContactInput": { "type": "object", "properties": { "fullName": { "type": "string" }, "isPrimary": { "type": "boolean" }, "roleTitle": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": "string" }, "includeInAccountingEmails": { "type": "boolean" } } }, "Output_CustomerAddress": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_AddressKind" }, "fullAddress": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "suburb": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "customerId", "kind", "country", "isDefault", "createdAt", "updatedAt" ] }, "Input_CreateAddressInput": { "type": "object", "properties": { "customerId": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_AddressKind" }, "fullAddress": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "suburb": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "isDefault": { "type": "boolean" } }, "required": [ "customerId" ] }, "Input_UpdateAddressInput": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_AddressKind" }, "fullAddress": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "suburb": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "Input_BulkCreateCustomerInput": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Input_CreateCustomerInput" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Input_BulkCustomerContactInput" } } }, "required": [ "customer" ] }, "Output_GarmentPage": { "type": "object", "description": "A page of garment styles plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Enum_GarmentStatus": { "type": "string", "enum": [ "on_hand", "order_in", "unavailable" ] }, "Output_GarmentFacets": { "type": "object", "description": "Distinct values for the garments list's select filters.", "properties": { "suppliers": { "type": "array", "items": { "type": "string" } }, "brands": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "suppliers", "brands", "categories" ] }, "Output_GarmentAsset": { "type": "object", "properties": { "id": { "type": "string" }, "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "side": { "$ref": "#/components/schemas/Enum_GarmentAssetSide" }, "sizeLabel": { "type": "string" }, "image": { "type": "string" }, "safeArea": { "$ref": "#/components/schemas/Output_GarmentAssetSafeArea" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "styleCode", "name", "color", "side", "image", "isActive", "createdAt", "updatedAt" ] }, "Output_GarmentCatalogueItem": { "type": "object", "properties": { "id": { "type": "string" }, "styleCode": { "type": "string" }, "styleName": { "type": "string" }, "supplier": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "composition": { "type": "string" }, "fabric": { "type": "string" }, "boxQty": { "type": "integer" }, "unitPrice": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "source": { "$ref": "#/components/schemas/Enum_CatalogSource" }, "externalId": { "type": "string" }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "vendorId": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/Output_Vendor" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "styleCode", "styleName", "source", "createdAt", "updatedAt" ] }, "Output_GarmentVariant": { "type": "object", "properties": { "id": { "type": "string" }, "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "stockCode": { "type": "string" }, "color": { "type": "string" }, "colorHex": { "type": "string" }, "size": { "type": "string" }, "countryOfManufacture": { "type": "string" }, "stockOnHand": { "type": "integer" }, "stockReserved": { "type": "integer" }, "supplierStock": { "type": "integer" }, "stockByLocation": { "type": "array", "items": { "$ref": "#/components/schemas/Output_SupplierStockAtLocation" } }, "nextDeliveryEta": { "type": "string", "format": "date-time" }, "isDiscontinued": { "type": "boolean" }, "unitPrice": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } }, "source": { "$ref": "#/components/schemas/Enum_CatalogSource" }, "externalId": { "type": "string" }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "styleCode", "color", "size", "stockOnHand", "stockReserved", "supplierStock", "stockByLocation", "isDiscontinued", "images", "source", "createdAt", "updatedAt" ] }, "Input_CreateGarmentInput": { "type": "object", "properties": { "styleCode": { "type": "string" }, "styleName": { "type": "string" }, "supplier": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "composition": { "type": "string" }, "fabric": { "type": "string" }, "boxQty": { "type": "integer" }, "unitPrice": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "vendorId": { "type": "string" }, "vendorName": { "type": "string", "description": "Vendor by NAME, honoured by `bulkUpsertGarments` ONLY — `createGarment` and `bulkCreateGarments` share this input type but reject it, rather than accepting a vendor they would not link. Resolved case-insensitively, created as type Supplier if unknown, inside this call's transaction. Distinct from `supplier`, which stays free text." } }, "required": [ "styleCode", "styleName" ] }, "Input_UpdateGarmentInput": { "type": "object", "properties": { "styleCode": { "type": "string" }, "styleName": { "type": "string" }, "supplier": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "composition": { "type": "string" }, "fabric": { "type": "string" }, "boxQty": { "type": "integer" }, "unitPrice": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "vendorId": { "type": "string" } } }, "Input_CreateGarmentVariantInput": { "type": "object", "properties": { "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "stockCode": { "type": "string" }, "color": { "type": "string" }, "colorHex": { "type": "string" }, "size": { "type": "string" }, "countryOfManufacture": { "type": "string" }, "stockOnHand": { "type": "integer" }, "stockReserved": { "type": "integer" }, "supplierStock": { "type": "integer" }, "unitPrice": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "styleCode", "color", "size" ] }, "Input_UpdateGarmentVariantInput": { "type": "object", "properties": { "stockCode": { "type": "string" }, "color": { "type": "string" }, "colorHex": { "type": "string" }, "size": { "type": "string" }, "countryOfManufacture": { "type": "string" }, "stockOnHand": { "type": "integer" }, "stockReserved": { "type": "integer" }, "supplierStock": { "type": "integer" }, "unitPrice": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } } } }, "Input_CreateGarmentAssetInput": { "type": "object", "properties": { "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "side": { "$ref": "#/components/schemas/Enum_GarmentAssetSide" }, "sizeLabel": { "type": "string" }, "image": { "type": "string" }, "safeArea": { "$ref": "#/components/schemas/Input_GarmentAssetSafeAreaInput" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "styleCode", "name", "color", "image" ] }, "Input_UpdateGarmentAssetInput": { "type": "object", "properties": { "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "side": { "$ref": "#/components/schemas/Enum_GarmentAssetSide" }, "sizeLabel": { "type": "string" }, "image": { "type": "string" }, "safeArea": { "$ref": "#/components/schemas/Input_GarmentAssetSafeAreaInput" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" } } }, "Output_BulkGarmentImportResult": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } }, "skippedStyleCodes": { "type": "array", "items": { "type": "string" }, "description": "Style codes that were not written: existing ones in CreateOnly, brand-new ones in UpdateExisting, or ambiguous codes matching multiple garments." }, "skippedAsColourStyleCodes": { "type": "array", "items": { "type": "string" }, "description": "Style codes that resolved to an AS Colour (supplier-owned) row — never written, in any mode." }, "vendorsCreated": { "type": "array", "items": { "type": "string" }, "description": "Vendors created as part of this call, by name." } }, "required": [ "created", "updated", "skippedStyleCodes", "skippedAsColourStyleCodes", "vendorsCreated" ] }, "Enum_BulkImportMode": { "type": "string", "enum": [ "CreateOnly", "UpdateExisting", "CreateAndUpdate" ] }, "Input_BulkGarmentPatchInput": { "type": "object", "description": "Fields a bulk garment update may set. Omitted = untouched.\n\n`stockOnHand` is a VARIANT property: it is written to every variant of each\nselected style, because a style has no single stock level — it has one per\ncolour/size. `status`, `vendorId` and `markupGroupId` are style properties.", "properties": { "status": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "stockOnHand": { "type": "integer" }, "vendorId": { "type": "string" }, "markupGroupId": { "type": "string" } } }, "Output_BulkVariantImportResult": { "type": "object", "properties": { "createdCount": { "type": "integer" }, "updatedCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "skippedAsColourStyleCodes": { "type": "array", "items": { "type": "string" } }, "skippedUnknownStyleCodes": { "type": "array", "items": { "type": "string" }, "description": "Style codes whose variants were skipped because no garment with that style code exists." }, "duplicateRowsMerged": { "type": "integer", "description": "Rows in this call that repeated an earlier row's (garment, colour, size) and\nwere merged into it, last-wins. Reported, never thrown: this used to abort\nthe whole batch, so one duplicated row in a supplier sheet discarded the\nother 999." } }, "required": [ "createdCount", "updatedCount", "skippedCount", "skippedAsColourStyleCodes", "skippedUnknownStyleCodes", "duplicateRowsMerged" ] }, "Output_BulkSetGarmentStockResult": { "type": "object", "properties": { "garmentsUpdated": { "type": "integer" }, "variantsUpdated": { "type": "integer" } }, "required": [ "garmentsUpdated", "variantsUpdated" ] }, "Output_DecorationPage": { "type": "object", "description": "A page of decoration services plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationCatalogueItem" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Output_DecorationFacets": { "type": "object", "description": "Distinct values for the decorations list's select filters (method).", "properties": { "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "methods" ] }, "Output_DecorationCatalogueItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_DecorationMethod" }, "description": { "type": "string" }, "setupCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "screenCount": { "type": "integer" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationPriceBreak" } }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "vendorId": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/Output_Vendor" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "method", "screenCount", "priceBreaks", "isActive", "createdAt", "updatedAt" ] }, "Input_CreateDecorationInput": { "type": "object", "properties": { "name": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_DecorationMethod" }, "description": { "type": "string" }, "setupCost": { "type": "number" }, "screenCount": { "type": "integer" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationPriceBreakInput" } }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "vendorId": { "type": "string" } }, "required": [ "name", "method" ] }, "Input_UpdateDecorationInput": { "type": "object", "properties": { "name": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_DecorationMethod" }, "description": { "type": "string" }, "setupCost": { "type": "number" }, "screenCount": { "type": "integer" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationPriceBreakInput" } }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "vendorId": { "type": "string" } } }, "Input_BulkDecorationPatchInput": { "type": "object", "description": "Fields a bulk decoration update may set. Omitted = untouched.\n\nNo markup group, deliberately: `decoration_catalogue_items` has no such column\nand no pricing path that would read one — a decoration prices through its own\nprice breaks and setup cost, while markup groups are a garment-pricing concept.", "properties": { "vendorId": { "type": "string" }, "isActive": { "type": "boolean" } } }, "Output_PreBuiltItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/Enum_PreBuiltItemStatus" }, "notes": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "computedUnitPriceExGst": { "type": "number" }, "computedTotalQuantity": { "type": "integer" }, "totalQuantity": { "type": "integer", "description": "The AUTHORED quantity, as a quote group carries one (CU-86d45h8cw) — distinct\nfrom `computedTotalQuantity`, which is a cached sum of what the contents add\nup to. This is the number an insert copies onto the new group, so a pack meant\nas \"25 polos\" arrives as 25 rather than as whatever the lines happen to total." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PreBuiltItemLine" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PreBuiltItemVariant" } }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PreBuiltItemDecoration" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "status", "tags", "computedUnitPriceExGst", "computedTotalQuantity", "totalQuantity", "lines", "variants", "decorations", "createdAt", "updatedAt" ] }, "Input_SavePreBuiltItemInput": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/Enum_PreBuiltItemStatus" }, "notes": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "computedUnitPriceExGst": { "type": "number" }, "computedTotalQuantity": { "type": "integer" }, "totalQuantity": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemLineInput" } }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemDecorationInput" } } }, "required": [ "name" ] }, "Enum_PreBuiltItemStatus": { "type": "string", "enum": [ "draft", "active", "inactive" ] }, "Output_PurchaseOrderPage": { "type": "object", "description": "A page of purchase orders plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PurchaseOrder" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Enum_POStatus": { "type": "string", "enum": [ "Draft", "Pending", "Approved", "Sent", "PartiallyReceived", "Received", "Completed", "Cancelled" ] }, "Enum_POSentStatus": { "type": "string", "enum": [ "NotSent", "Sent", "Delivered", "Confirmed" ] }, "Output_PurchaseOrder": { "type": "object", "properties": { "id": { "type": "string" }, "poNumber": { "type": "string" }, "title": { "type": "string" }, "referenceNumber": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "deadline": { "type": "string", "format": "date" }, "subtotalExGst": { "type": "number" }, "taxRatePct": { "type": "number" }, "gstAmount": { "type": "number" }, "totalIncGst": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_POStatus" }, "sentStatus": { "$ref": "#/components/schemas/Enum_POSentStatus" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PurchaseOrderLineItem" } }, "vendors": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Vendor" } } }, "required": [ "id", "poNumber", "subtotalExGst", "taxRatePct", "gstAmount", "totalIncGst", "status", "sentStatus", "isActive", "createdAt", "updatedAt", "lineItems", "vendors" ] }, "Input_CreatePurchaseOrderInput": { "type": "object", "properties": { "title": { "type": "string" }, "referenceNumber": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "deadline": { "type": "string", "format": "date" }, "taxRatePct": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_POStatus" }, "sentStatus": { "$ref": "#/components/schemas/Enum_POSentStatus" } } }, "Input_UpdatePurchaseOrderInput": { "type": "object", "properties": { "title": { "type": "string" }, "referenceNumber": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "deadline": { "type": "string", "format": "date" }, "taxRatePct": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_POStatus" }, "sentStatus": { "$ref": "#/components/schemas/Enum_POSentStatus" } } }, "Input_CreatePOLineItemInput": { "type": "object", "properties": { "purchaseOrderId": { "type": "string" }, "itemType": { "$ref": "#/components/schemas/Enum_POLineItemType" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "colour": { "type": "string" }, "size": { "type": "string" }, "quantity": { "type": "integer" }, "rate": { "type": "number" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "purchaseOrderId" ] }, "Input_UpdatePOLineItemInput": { "type": "object", "properties": { "itemType": { "$ref": "#/components/schemas/Enum_POLineItemType" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "colour": { "type": "string" }, "size": { "type": "string" }, "quantity": { "type": "integer" }, "rate": { "type": "number" }, "ordered": { "type": "boolean" }, "quantityOrdered": { "type": "integer" }, "quantityOnBackorder": { "type": "integer" }, "backorderDate": { "type": "string", "format": "date" }, "received": { "type": "boolean" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "Input_ReceivePOLineItemInput": { "type": "object", "properties": { "ordered": { "type": "boolean" }, "quantityOrdered": { "type": "integer" }, "received": { "type": "boolean" }, "quantityOnBackorder": { "type": "integer" }, "backorderDate": { "type": "string", "format": "date" } } }, "Enum_BulkReceiveMode": { "type": "string", "description": "Whether a bulk receive marks every outstanding line received, or un-receives them.", "enum": [ "receive_all", "unreceive_all" ] }, "Output_VendorPage": { "type": "object", "description": "A page of vendors plus the unpaginated total (for page counts).", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Vendor" } }, "totalCount": { "type": "integer" } }, "required": [ "items", "totalCount" ] }, "Output_Vendor": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_VendorKind" }, "serviceTypes": { "type": "array", "items": { "$ref": "#/components/schemas/Enum_VendorServiceType" } }, "logoUrl": { "type": "string" }, "ordersWebsite": { "type": "string" }, "accountNumber": { "type": "string" }, "defaultLeadTimeDays": { "type": "integer" }, "minimumOrder": { "type": "number" }, "proximityNotes": { "type": "string" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "isManaged": { "type": "boolean", "description": "True when PrinTools provisions this vendor rather than the shop creating it\n— currently only the AS Colour record every org is seeded with, and which the\ngarment catalogue links its AS Colour styles to. A managed vendor is edited\nlike any other (the account number, contacts and addresses on it are the\nshop's own), but it cannot be archived: the catalogue's link to it ignores\n`isActive`, so archiving would hide nothing and only break purchase orders\nfor every AS Colour style." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Output_VendorContact" } }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Output_VendorAddress" } } }, "required": [ "id", "name", "kind", "serviceTypes", "isActive", "isManaged", "createdAt", "updatedAt", "contacts", "addresses" ] }, "Input_CreateVendorInput": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_VendorKind" }, "serviceTypes": { "type": "array", "items": { "$ref": "#/components/schemas/Enum_VendorServiceType" } }, "logoUrl": { "type": "string" }, "ordersWebsite": { "type": "string" }, "accountNumber": { "type": "string" }, "defaultLeadTimeDays": { "type": "integer" }, "minimumOrder": { "type": "number" }, "proximityNotes": { "type": "string" }, "notes": { "type": "string" } } }, "Input_UpdateVendorInput": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_VendorKind" }, "serviceTypes": { "type": "array", "items": { "$ref": "#/components/schemas/Enum_VendorServiceType" } }, "logoUrl": { "type": "string" }, "ordersWebsite": { "type": "string" }, "accountNumber": { "type": "string" }, "defaultLeadTimeDays": { "type": "integer" }, "minimumOrder": { "type": "number" }, "proximityNotes": { "type": "string" }, "notes": { "type": "string" } } }, "Output_VendorAddress": { "type": "object", "properties": { "id": { "type": "string" }, "vendorId": { "type": "string" }, "label": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "vendorId", "createdAt", "updatedAt" ] }, "Input_CreateVendorAddressInput": { "type": "object", "properties": { "vendorId": { "type": "string" }, "label": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "vendorId" ] }, "Input_UpdateVendorAddressInput": { "type": "object", "properties": { "label": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "Output_VendorContact": { "type": "object", "properties": { "id": { "type": "string" }, "vendorId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "vendorId", "createdAt", "updatedAt" ] }, "Input_CreateVendorContactInput": { "type": "object", "properties": { "vendorId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } }, "required": [ "vendorId" ] }, "Input_UpdateVendorContactInput": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "Output_Mock": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "quoteGroupId": { "type": "string", "description": "The quote group this mock illustrates. Multi-option quotes carry one mock per option; `Quote.mockId` stays the quote-level primary." }, "quoteLineId": { "type": "string", "description": "The quote line this mock's composite mirrors onto (via QuoteLine.customImageUrl), so the mock reaches the quote document and quotePdf." }, "name": { "type": "string" }, "garmentAssetId": { "type": "string" }, "baseImageUrl": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "parentMockId": { "type": "string" }, "approvedAt": { "type": "string", "format": "date-time" }, "approvedByName": { "type": "string" }, "approvedByEmail": { "type": "string" }, "rejectionReason": { "type": "string" }, "previewUrl": { "type": "string" }, "layers": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "version", "layers", "createdAt", "updatedAt" ] }, "Input_CreateMockInput": { "type": "object", "properties": { "name": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "quoteGroupId": { "type": "string" }, "quoteLineId": { "type": "string" }, "garmentAssetId": { "type": "string" }, "baseImageUrl": { "type": "string" }, "status": { "type": "string" }, "parentMockId": { "type": "string" }, "previewUrl": { "type": "string" }, "layers": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "Input_UpdateMockInput": { "type": "object", "properties": { "name": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "quoteGroupId": { "type": "string" }, "quoteLineId": { "type": "string" }, "garmentAssetId": { "type": "string" }, "baseImageUrl": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "parentMockId": { "type": "string" }, "rejectionReason": { "type": "string" }, "previewUrl": { "type": "string" }, "layers": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "Output_Proof": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "jobGroupId": { "type": "string" }, "jobGroupDecorationId": { "type": "string" }, "mockId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "optionLabel": { "type": "string" }, "imageUrl": { "type": "string" }, "imageFileName": { "type": "string" }, "version": { "type": "integer" }, "parentProofId": { "type": "string" }, "status": { "$ref": "#/components/schemas/Enum_ProofStatus" }, "sentToClientAt": { "type": "string", "format": "date-time" }, "sentToEmail": { "type": "string" }, "clientDecisionAt": { "type": "string", "format": "date-time" }, "clientDecisionByName": { "type": "string" }, "clientNotes": { "type": "string" }, "approvedByEmail": { "type": "string" }, "approvedByName": { "type": "string" }, "rejectionReason": { "type": "string" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "placementSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/Output_ProofPlacementSpec" } }, "itemLinks": { "type": "array", "items": { "$ref": "#/components/schemas/Output_ProofItemLink" } } }, "required": [ "id", "jobId", "title", "version", "status", "sortOrder", "createdAt", "updatedAt", "placementSpecs", "itemLinks" ] }, "Input_CreateProofInput": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobGroupId": { "type": "string" }, "jobGroupDecorationId": { "type": "string" }, "mockId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "optionLabel": { "type": "string" }, "imageUrl": { "type": "string" }, "imageFileName": { "type": "string" }, "sortOrder": { "type": "integer" }, "placementSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofPlacementSpecInput" } }, "itemLinks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofItemLinkInput" } } }, "required": [ "jobId", "title" ] }, "Input_UpdateProofInput": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "optionLabel": { "type": "string" }, "imageUrl": { "type": "string" }, "imageFileName": { "type": "string" }, "sortOrder": { "type": "integer" }, "placementSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofPlacementSpecInput" }, "description": "Replace-on-write when provided; omitted = untouched." }, "itemLinks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofItemLinkInput" }, "description": "Replace-on-write when provided (splits reset to unconfirmed); omitted = untouched." } } }, "Enum_ProofStatus": { "type": "string", "enum": [ "Draft", "InternallyApproved", "SentToClient", "ClientApproved", "ClientRejected", "NeedsRevision" ] }, "Enum_ProofClientDecision": { "type": "string", "enum": [ "Approved", "Rejected" ] }, "Output_ProofItemLink": { "type": "object", "properties": { "id": { "type": "string" }, "proofId": { "type": "string" }, "jobGroupId": { "type": "string" }, "jobLineId": { "type": "string", "description": "PT-05 — the garment LINE this link covers, within the group. A group may hold\nseveral garment lines, and a size split has to land on exactly one of them.\n\nNull only on links written before PT-05 whose group held anything other than\none garment line: the migration backfilled the unambiguous case and refused to\ninvent an attribution for the rest. Those keep the old behaviour, ambiguity\nerror included, until the proof is re-linked." }, "quantity": { "type": "integer" }, "sizeSplit": { "type": "array", "items": { "$ref": "#/components/schemas/Output_SizeQty" } }, "sizeSplitConfirmed": { "type": "boolean" } }, "required": [ "id", "proofId", "jobGroupId", "quantity", "sizeSplit", "sizeSplitConfirmed" ] }, "Input_SizeQtyInput": { "type": "object", "properties": { "size": { "type": "string" }, "qty": { "type": "integer" } }, "required": [ "size", "qty" ] }, "Output_ProductionTask": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "$ref": "#/components/schemas/Enum_TaskCategory" }, "decorationMethod": { "type": "string" }, "status": { "type": "string" }, "assignedToEmail": { "type": "string" }, "assignedToName": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "jobGroupDecorationId": { "type": "string" }, "decorationItemId": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "completedByEmail": { "type": "string" }, "attachmentUrl": { "type": "string" }, "attachmentFileName": { "type": "string" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "jobId", "title", "category", "decorationMethod", "status", "sortOrder", "createdAt", "updatedAt" ] }, "Output_MyProductionTask": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Output_ProductionTask" }, "job": { "$ref": "#/components/schemas/Output_MyTaskJobContext" } }, "required": [ "task", "job" ] }, "Output_TaskExtras": { "type": "object", "properties": { "checklist": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobTaskChecklistItem" } }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobTaskComment" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobTaskAttachment" } } }, "required": [ "checklist", "comments", "attachments" ] }, "Input_CreateProductionTaskInput": { "type": "object", "properties": { "jobId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "$ref": "#/components/schemas/Enum_TaskCategory" }, "decorationMethod": { "type": "string" }, "assignedToEmail": { "type": "string" }, "assignedToName": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "jobGroupDecorationId": { "type": "string" }, "decorationItemId": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "jobId", "title" ] }, "Input_UpdateProductionTaskInput": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "category": { "$ref": "#/components/schemas/Enum_TaskCategory" }, "decorationMethod": { "type": "string" }, "status": { "type": "string" }, "assignedToEmail": { "type": "string" }, "assignedToName": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "attachmentUrl": { "type": "string" }, "attachmentFileName": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "Input_BulkTaskPatchInput": { "type": "object", "description": "Fields a bulk production-task update may set. Omitted = untouched.", "properties": { "status": { "type": "string" }, "assignedToEmail": { "type": "string" }, "assignedToName": { "type": "string" }, "dueDate": { "type": "string", "format": "date" } } }, "Output_JobTaskComment": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "authorEmail": { "type": "string" }, "authorName": { "type": "string" }, "body": { "type": "string" }, "editedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "taskId", "authorEmail", "body", "createdAt" ] }, "Input_CreateTaskCommentInput": { "type": "object", "properties": { "taskId": { "type": "string" }, "body": { "type": "string" } }, "required": [ "taskId", "body" ] }, "Input_UpdateTaskCommentInput": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] }, "Output_JobTaskChecklistItem": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" }, "completed": { "type": "boolean" }, "completedAt": { "type": "string", "format": "date-time" }, "position": { "type": "integer" } }, "required": [ "id", "taskId", "text", "completed", "position" ] }, "Input_CreateTaskChecklistItemInput": { "type": "object", "properties": { "taskId": { "type": "string" }, "text": { "type": "string" }, "position": { "type": "integer" } }, "required": [ "taskId", "text" ] }, "Input_UpdateTaskChecklistItemInput": { "type": "object", "properties": { "text": { "type": "string" }, "completed": { "type": "boolean" }, "position": { "type": "integer" } } }, "Output_JobTaskAttachment": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "fileUrl": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "uploadedByEmail": { "type": "string" }, "uploadedByName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "taskId", "fileUrl", "filename", "createdAt" ] }, "Input_CreateTaskAttachmentInput": { "type": "object", "properties": { "taskId": { "type": "string" }, "fileUrl": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" } }, "required": [ "taskId", "fileUrl", "filename" ] }, "Output_PdfExport": { "type": "object", "properties": { "url": { "type": "string", "description": "Presigned GET (15 min) — download immediately." } }, "required": [ "url" ] }, "Output_MediaUploadTarget": { "type": "object", "properties": { "uploadUrl": { "type": "string" }, "fileUrl": { "type": "string" } }, "required": [ "uploadUrl", "fileUrl" ] }, "Input_CreateMediaUploadInput": { "type": "object", "properties": { "kind": { "type": "string" }, "contentType": { "type": "string" }, "contentLength": { "type": "integer", "description": "Size of the file in bytes. Optional for now — omitting it keeps the old\nbehaviour, where nothing bounds how much the presigned PUT may carry. When\nsupplied it is checked against the per-type cap (25 MB image / 100 MB pdf)\nAND pinned into the signature, so the upload is rejected by S3 unless its\nContent-Length matches exactly. Send it whenever the size is known." } }, "required": [ "kind", "contentType" ] }, "Output_Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "quoteId": { "type": "string" }, "clientId": { "type": "string" }, "contactId": { "type": "string" }, "invoiceRef": { "type": "string", "description": "INV-YYYY-NNNN, per-org sequence." }, "currency": { "type": "string" }, "subtotalCents": { "type": "integer", "description": "Money in cents (dollars -> cents, round half-up)." }, "gstCents": { "type": "integer" }, "amountCents": { "type": "integer" }, "status": { "type": "string", "description": "Draft | AwaitingPayment | Pending | Paid | PaymentFailed | Refunded | Void" }, "dueDate": { "type": "string", "format": "date" }, "lineItemsSnapshot": { "description": "Locked copy of the quote tree at generation time." }, "notes": { "type": "string" }, "pinchPaymentLinkUrl": { "type": "string", "description": "Hosted Pinch payment link; null for manual-payment invoices.\n\nAlso null — for every read and every mutation return — while the org's\n`payments` settings area has `paymentLinksEnabled: false`. The column is left\nintact underneath, so re-enabling the toggle restores the link without\nre-minting it at Pinch." }, "pinchPaymentId": { "type": "string", "description": "Pinch payment id (pmt_...) once a platform payment lands (C3)." }, "xeroInvoiceId": { "type": "string", "description": "Accounting-sync receipts (Epic D): set once pushed; null = not synced." }, "qboSalesReceiptId": { "type": "string" }, "xeroPaymentId": { "type": "string", "description": "Xero payment id once the payment is recorded in Xero; null = invoice pushed but payment not synced." }, "xeroInvoiceUrl": { "type": "string", "description": "Deep link to this invoice in Xero; null until pushed." }, "qboInvoiceId": { "type": "string", "description": "QB-01 — the COLLECTABLE QuickBooks Invoice, set by pushInvoiceToQuickBooks.\nDistinct from qboSalesReceiptId, which is the paid-record document the\ndispatcher writes for a shop that never presses the manual action; an\ninvoice carries one or the other, never both." }, "qboPaymentId": { "type": "string", "description": "QuickBooks payment id once the payment is booked there; null = invoice pushed but payment not synced." }, "qboInvoiceUrl": { "type": "string", "description": "Deep link to this invoice in QuickBooks; null until pushed." }, "paidMethod": { "type": "string", "description": "pinch | bank_transfer | cash | card | other | xero | quickbooks (how Paid happened)." }, "paidReference": { "type": "string" }, "paidAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "pinchRefundId": { "type": "string", "description": "Pinch refund id (rfd_...); null for off-platform refunds." }, "refundedAmountCents": { "type": "integer" }, "refundReason": { "type": "string" }, "refundedAt": { "type": "string", "format": "date-time" }, "voidReason": { "type": "string", "description": "Why the invoice was voided; null unless status is Void." }, "voidedAt": { "type": "string", "format": "date-time" }, "paymentClaimedAt": { "type": "string", "format": "date-time", "description": "Client-declared off-platform payment (\"remittance advice\"), submitted from the portal.\nNOT a payment record — the shop must verify it. Cleared by markInvoicePaid (confirmed),\ndismissPaymentClaim (rejected) and the Pinch webhook `paid` path (a real payment makes\nthe claim moot)." }, "paymentClaimedMethod": { "type": "string", "description": "bank_transfer | cash | other — the portal's claim vocabulary." }, "paymentClaimedReference": { "type": "string" }, "paymentClaimedNote": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "quoteId", "invoiceRef", "currency", "subtotalCents", "gstCents", "amountCents", "status", "lineItemsSnapshot", "createdAt", "updatedAt" ] }, "Input_SendInvoiceInput": { "type": "object", "description": "Parity with SendQuoteInput (F-29). Send Invoice is now the Send Quote flow — a\nReview step then a Compose & Send step with `{{tokens}}` and a live preview — so\nthe operator composes a subject and can copy themselves, exactly as on a quote.\nThe field names differ from the quote's (`toEmail` vs `emailTo`) only because\nthis input shipped first; renaming it would break every deployed client.", "properties": { "toEmail": { "type": "string" }, "emailSubject": { "type": "string", "description": "Operator-composed subject. Omitted or blank → the server default,\n`Invoice {ref}`, which is what every send used before F-29." }, "emailBodyMarkdown": { "type": "string", "description": "The WHOLE email body as Markdown, with `{{tokens}}` already resolved by the\nclient — the same contract as `SendQuoteInput.emailBodyMarkdown`. When set,\nthe server composes nothing: no invoice summary block is prepended." }, "ccSelfEmail": { "type": "string", "description": "Copy the sending rep, as on a quote." }, "message": { "type": "string", "description": "A note PREPENDED to a server-composed summary (ref, amount due, due date, pay\nlink). Kept working for clients that predate F-29." } }, "required": [ "toEmail" ] }, "Input_MarkInvoicePaidInput": { "type": "object", "properties": { "method": { "type": "string", "description": "bank_transfer | cash | card | other (pinch payments record themselves)." }, "reference": { "type": "string", "description": "Bank/receipt reference for the audit trail." }, "paidAt": { "type": "string", "format": "date-time", "description": "When the payment landed; defaults to now." } }, "required": [ "method" ] }, "Input_VoidInvoiceInput": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why it was voided — surfaced on the invoice and in the audit trail." } } }, "Input_RefundInvoiceInput": { "type": "object", "properties": { "amountCents": { "type": "integer", "description": "Cents; omit for a full refund. Must not exceed the invoice total." }, "reason": { "type": "string" } } }, "Output_XeroInvoicePushResult": { "type": "object", "description": "XR-01 — the outcome of pushing a generated invoice into Xero as a collectable document.", "properties": { "invoiceId": { "type": "string" }, "xeroInvoiceId": { "type": "string" }, "xeroInvoiceUrl": { "type": "string", "description": "Deep link to the invoice in Xero's web UI; null if it cannot be built." }, "alreadyPushed": { "type": "boolean", "description": "True when the invoice was already in Xero and this call was a no-op." }, "xeroPaymentId": { "type": "string", "description": "The Xero Payment booked in the SAME call, set only when the invoice was\nalready Paid in PrintTools (a settled sale is pushed as invoice + payment, so\nXero never shows the customer owing money they have already paid). Null for\nthe ordinary collectable push." }, "documentStatus": { "type": "string", "description": "The document created by this call; null when the push was already complete." } }, "required": [ "invoiceId", "xeroInvoiceId", "alreadyPushed" ] }, "Output_QuickBooksInvoicePushResult": { "type": "object", "description": "QB-01 — the outcome of pushing a generated invoice into QuickBooks as a collectable document.", "properties": { "invoiceId": { "type": "string" }, "qboInvoiceId": { "type": "string" }, "qboInvoiceUrl": { "type": "string", "description": "Deep link to the invoice in the QuickBooks web UI; null if it cannot be built." }, "alreadyPushed": { "type": "boolean", "description": "True when the invoice was already in QuickBooks and this call was a no-op." } }, "required": [ "invoiceId", "qboInvoiceId", "alreadyPushed" ] }, "Enum_JobPriority": { "type": "string", "enum": [ "Normal", "Rush" ] }, "Enum_JobPoStatus": { "type": "string", "enum": [ "NotCreated", "Created", "Sent", "Received" ] }, "Enum_JobMaterialsStatus": { "type": "string", "enum": [ "NotPurchased", "Ordered", "Received" ] }, "Enum_QuoteLineType": { "type": "string", "enum": [ "Garment", "Decoration", "Service", "Cost", "Discount", "Surcharge", "Other" ] }, "Enum_LineValueType": { "type": "string", "enum": [ "Flat", "Percentage" ] }, "Enum_DiscountValueType": { "type": "string", "enum": [ "Flat", "Percentage" ] }, "Output_QuoteVariant": { "type": "object", "properties": { "id": { "type": "string" }, "quoteLineId": { "type": "string" }, "size": { "type": "string" }, "colour": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "buyPrice": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "extraCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The markup that connects cost to sell, stored so it survives a reopen\n(BE-01 / Q-16). Cost is `buyPrice + extraCost`; sell is\n`percentage ? cost + cost·value/100 : cost + value`. Null on rows written\nbefore the column existed — read those back by back-solving from cost and\nsell, as the client did for every row previously. `MarkupType` is the enum\ncatalog-service already declares." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Whether the markup above belongs to a markup GROUP or to the operator\n(CU-86d46hu37). `group` re-resolves through the group's matrix whenever the\nquantity or the cost moves — on reopen as much as on create — while `manual`\nis left alone and holds its saved sell price through a cost edit.\n\nNever null: rows written before the column existed read `manual`, which is\nprecisely how they behaved." }, "isCustomLine": { "type": "boolean", "description": "A cost that belongs to the line but is not per-garment — freight is the\nexample (BE-02 / Q-14). Stored as a variant with no size and no colour; the\nflag is what tells one from a half-filled variant, since the size sort, the\nquote document and the PDF all walk these rows." }, "showOnDocuments": { "type": "boolean", "description": "Whether a CUSTOM variant is itemised on the documents the customer sees —\nquote, invoice, PDF, portal (QU-02).\n\nFalse, the default, folds its money into the garment line's total and draws\nno row anywhere. True prints one row reading `Custom variant`, quantity 1,\nwith size and colour blank. Either way the money is identical: a line's\ntotal already sums every variant beneath it, custom rows included.\n\nIgnored on a real size/colour variant — that row IS the itemisation." }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "quoteLineId", "quantity", "unitPriceExGst", "markupSource", "isCustomLine", "showOnDocuments", "sortOrder", "createdAt", "updatedAt" ] }, "Enum_MarkupType": { "type": "string", "enum": [ "percentage", "flat_rate" ] }, "Enum_MarkupSource": { "type": "string", "description": "WHO owns a markup, and therefore whether it may be re-resolved through its\nmarkup group's matrix (CU-86d46hu37).\n\n`group` — a markup group resolved the number, so it re-bands on every quantity\nor cost change, on create and on reopen alike; the sell price moves with it.\n`manual` — an operator typed the markup, flipped its \\$/% toggle, or overrode\nthe sell price. Never re-banded, and a cost edit back-solves to hold the saved\nsell fixed, which is the edit-lock that stops a live quote repricing itself.\n\nStored `not null default 'manual'`, so every row written before this existed is\noperator-owned and behaves exactly as it did. A create path that means `group`\nmust SAY `group` — relying on the default silently reintroduces the bug the\nenum exists to fix.", "enum": [ "group", "manual" ] }, "Enum_JobDecorationMethod": { "type": "string", "enum": [ "ScreenPrinting", "Embroidery", "DtfTransfer", "Dtg", "Vinyl", "Sublimation", "HeatTransfer", "Outsourced", "Other" ] }, "Output_DecorationColour": { "type": "object", "properties": { "name": { "type": "string" }, "isBase": { "type": "boolean" } }, "required": [ "name", "isBase" ] }, "Input_DecorationColourInput": { "type": "object", "properties": { "name": { "type": "string" }, "isBase": { "type": "boolean" } }, "required": [ "name" ] }, "Output_BulkItemOutcome": { "type": "object", "description": "What happened to one row in a bulk action. `reason` is null only for `ok`.", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/Enum_BulkOutcomeStatus" }, "reason": { "type": "string" } }, "required": [ "id", "status" ] }, "Output_JobVariant": { "type": "object", "properties": { "id": { "type": "string" }, "jobLineId": { "type": "string" }, "size": { "type": "string" }, "colour": { "type": "string" }, "quantity": { "type": "integer" }, "producedQuantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "buyPrice": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "extraCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "jobLineId", "quantity", "producedQuantity", "unitPriceExGst", "sortOrder", "createdAt", "updatedAt" ] }, "Enum_CustomerKind": { "type": "string", "enum": [ "Business", "Individual" ] }, "Enum_AddressKind": { "type": "string", "enum": [ "Billing", "Shipping", "Other" ] }, "Input_BulkCustomerContactInput": { "type": "object", "properties": { "fullName": { "type": "string" }, "isPrimary": { "type": "boolean" }, "roleTitle": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "fullName" ] }, "Enum_GarmentAssetSide": { "type": "string", "enum": [ "front", "back", "left_sleeve", "right_sleeve", "other" ] }, "Output_GarmentAssetSafeArea": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "x", "y", "w", "h" ] }, "Enum_CatalogSource": { "type": "string", "enum": [ "manual", "ascolour" ] }, "Output_SupplierStockAtLocation": { "type": "object", "description": "Supplier stock at one warehouse (AS Colour inventory is per-location).", "properties": { "location": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "location", "quantity" ] }, "Input_GarmentAssetSafeAreaInput": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "x", "y", "w", "h" ] }, "Enum_DecorationMethod": { "type": "string", "enum": [ "screen_printing", "embroidery", "dtg", "heat_transfer", "sublimation", "vinyl", "other" ] }, "Output_DecorationPriceBreak": { "type": "object", "properties": { "quantityRange": { "type": "string" }, "price": { "type": "number" } }, "required": [ "quantityRange", "price" ] }, "Input_DecorationPriceBreakInput": { "type": "object", "properties": { "quantityRange": { "type": "string" }, "price": { "type": "number" } }, "required": [ "quantityRange", "price" ] }, "Output_PreBuiltItemLine": { "type": "object", "properties": { "id": { "type": "string" }, "preBuiltItemId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_PreBuiltLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string", "description": "JB-13's standalone charge is a TITLE with no product behind it." }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPriceExGst": { "type": "number" }, "valueType": { "$ref": "#/components/schemas/Enum_PreBuiltLineValueType", "description": "A discount or surcharge expressed as a RATE rather than a dollar amount\n(CU-86d45h8cw). Same pair, same spelling, as `QuoteLine.valueType` /\n`percentage` — the insert copies a pre-built line straight onto a quote line,\nso two spellings of the same two words would only be somewhere to drift.\n\nWithout these a 10% discount authored on a pre-built item round-tripped as $0." }, "percentage": { "type": "number" }, "customImageUrl": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "id", "preBuiltItemId", "lineType", "quantity", "unitPriceExGst", "sortOrder" ] }, "Output_PreBuiltItemVariant": { "type": "object", "properties": { "id": { "type": "string" }, "preBuiltItemLineId": { "type": "string" }, "size": { "type": "string" }, "colour": { "type": "string" }, "quantity": { "type": "number" }, "buyPrice": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "extraCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "markupType": { "$ref": "#/components/schemas/Enum_PreBuiltMarkupType" }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Who owns the markup above — see `MarkupSource`. A pre-built item is inserted\ninto a quote at a different quantity from the one it was built at, so a\ngroup-owned markup is exactly the kind that should re-band on the way in\n(CU-86d46hu37). Rows saved before this read `manual`." }, "unitPriceExGst": { "type": "number" }, "sortOrder": { "type": "integer", "description": "The order the operator authored, not the order the sizes sort in." }, "isCustomLine": { "type": "boolean", "description": "QU-02's pair (CU-86d45h8cw). A CUSTOM variant is a cost attached to the\ngarment — a courier fee, a rush charge — that rolls into its price;\n`showOnDocuments` is whether it is itemised on the customer's copy. Neither\nsurvived a pre-built save before, so a rush charge came back as an ordinary\nsize row called nothing." }, "showOnDocuments": { "type": "boolean" } }, "required": [ "id", "preBuiltItemLineId", "quantity", "markupType", "markupValue", "markupSource", "unitPriceExGst", "sortOrder", "isCustomLine", "showOnDocuments" ] }, "Output_PreBuiltItemDecoration": { "type": "object", "properties": { "id": { "type": "string" }, "preBuiltItemId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "string" }, "quantity": { "type": "number" }, "unitCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "setupCost": { "type": "number", "description": "Present only when the credential includes the costs.read scope." }, "baseUnitCost": { "type": "number", "description": "Cost per unit (COGS basis, margin correctness); null -> 0." }, "baseSetupCost": { "type": "number", "description": "One-off setup cost basis; null -> 0." }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_PreBuiltMarkupType", "description": "How the CHARGE is derived from the cost basis (CU-86d45h8cw). Variants have\nalways carried these; decorations did not, which is why a pre-built decoration\nwas charged at cost with no margin. Rows written before this read `Flat` / `0`\n— their stored `unitCost` is already the charge and stays authoritative, so\ntheir margin reads as zero until the item is re-saved." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Who owns the markup above — see `MarkupSource`. A pre-built item is inserted\ninto a quote at a different quantity from the one it was built at, so a\ngroup-owned markup is exactly the kind that should re-band on the way in\n(CU-86d46hu37). Rows saved before this read `manual`." }, "notes": { "type": "string" }, "widthCm": { "type": "number", "description": "The print spec, field-for-field as `QuoteGroupDecoration` carries it\n(CU-86d45h8cw). The pre-built builder opens the quote's own decoration\ndialog, which collects every one of these; before this they were collected\nand then dropped on save.\n\nDimensions are CENTIMETRES and nullable — a decoration with no measured print\nkeeps null rather than gaining a confident 0." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationColour" } }, "specialInstructions": { "type": "string", "description": "Internal shop notes — never customer-facing." }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "rollUp": { "type": "boolean", "description": "The three display answers CU-86d416yvz moved onto the decoration row: fold the\nunit charge into the garment price, fold the setup charge, and whether the row\nis drawn on customer-facing documents at all. Stored here so a decoration\nauthored as folded stays folded through save and insert." }, "rollUpSetup": { "type": "boolean" }, "showOnDocuments": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "required": [ "id", "preBuiltItemId", "quantity", "includeSetupCost", "markupType", "markupValue", "markupSource", "colours", "rollUp", "rollUpSetup", "showOnDocuments", "sortOrder" ] }, "Input_SavePreBuiltItemLineInput": { "type": "object", "properties": { "lineType": { "$ref": "#/components/schemas/Enum_PreBuiltLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPriceExGst": { "type": "number" }, "valueType": { "$ref": "#/components/schemas/Enum_PreBuiltLineValueType" }, "percentage": { "type": "number" }, "customImageUrl": { "type": "string" }, "sortOrder": { "type": "integer" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemVariantInput" } } } }, "Input_SavePreBuiltItemDecorationInput": { "type": "object", "properties": { "decorationItemId": { "type": "string" }, "method": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "string" }, "quantity": { "type": "number" }, "unitCost": { "type": "number" }, "setupCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_PreBuiltMarkupType" }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual. A group-resolved markup must send `group` explicitly." }, "notes": { "type": "string" }, "widthCm": { "type": "number" }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "specialInstructions": { "type": "string" }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "rollUp": { "type": "boolean" }, "rollUpSetup": { "type": "boolean" }, "showOnDocuments": { "type": "boolean" }, "sortOrder": { "type": "integer" } } }, "Output_PurchaseOrderLineItem": { "type": "object", "properties": { "id": { "type": "string" }, "purchaseOrderId": { "type": "string" }, "itemType": { "$ref": "#/components/schemas/Enum_POLineItemType" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "colour": { "type": "string" }, "size": { "type": "string" }, "quantity": { "type": "integer" }, "rate": { "type": "number" }, "ordered": { "type": "boolean" }, "quantityOrdered": { "type": "integer" }, "quantityOnBackorder": { "type": "integer" }, "backorderDate": { "type": "string", "format": "date" }, "received": { "type": "boolean" }, "notes": { "type": "string" }, "subtotal": { "type": "number" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "purchaseOrderId", "itemType", "name", "quantity", "rate", "ordered", "received", "subtotal", "sortOrder", "createdAt", "updatedAt" ] }, "Enum_POLineItemType": { "type": "string", "enum": [ "Product", "Decoration", "Other" ] }, "Enum_VendorKind": { "type": "string", "enum": [ "InventorySupplier", "OutsourceVendor", "Both" ] }, "Enum_VendorServiceType": { "type": "string", "enum": [ "ScreenPrint", "Embroidery", "Digitising", "DTF", "Other" ] }, "Output_ProofPlacementSpec": { "type": "object", "properties": { "id": { "type": "string" }, "proofId": { "type": "string" }, "placement": { "type": "string" }, "method": { "type": "string" }, "widthCm": { "type": "number" }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationColour" } }, "sortOrder": { "type": "integer" }, "jobGroupDecorationId": { "type": "string", "description": "The job-group decoration this spec describes. Null for a spec typed by hand for a print that isn't on the quote." }, "groupName": { "type": "string", "description": "PR-01 WS-1.2 — server-resolved display fields, projected the same way PortalProofItemLink projects group/style/colour (portal-service/schema.graphql). Read-only; null when jobGroupDecorationId is null or the decoration no longer resolves." }, "styleName": { "type": "string" }, "colour": { "type": "string" }, "decorationName": { "type": "string", "description": "The decoration's own label, as the quote shows it." } }, "required": [ "id", "proofId", "placement", "colours", "sortOrder" ] }, "Input_ProofPlacementSpecInput": { "type": "object", "properties": { "placement": { "type": "string" }, "method": { "type": "string" }, "widthCm": { "type": "number" }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" } }, "sortOrder": { "type": "integer" }, "jobGroupDecorationId": { "type": "string", "description": "PR-01 WS-1.1 — nullable by design: a manually-typed placement (no decoration on the quote) saves this null; see D-2/D-3." } }, "required": [ "placement" ] }, "Input_ProofItemLinkInput": { "type": "object", "properties": { "jobGroupId": { "type": "string" }, "jobLineId": { "type": "string", "description": "PT-05 — the garment line within the group. Omit it and the server resolves the\ngroup's sole garment line (the only thing a pre-PT-05 caller could have\nmeant); a group with several then links with no line, exactly as before.\nValidated to be a garment line of the named group on this proof's job." }, "quantity": { "type": "integer" }, "sizeSplit": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SizeQtyInput" } } }, "required": [ "jobGroupId", "quantity" ] }, "Output_SizeQty": { "type": "object", "properties": { "size": { "type": "string" }, "qty": { "type": "integer" } }, "required": [ "size", "qty" ] }, "Enum_TaskCategory": { "type": "string", "enum": [ "Artwork", "Stock", "Ink", "Screen", "Production", "QC", "Packaging", "Other" ] }, "Output_MyTaskJobContext": { "type": "object", "properties": { "id": { "type": "string" }, "jobRef": { "type": "string" }, "jobName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt" ] }, "Enum_BulkOutcomeStatus": { "type": "string", "description": "Per-row verdict for a bulk action. `refused` is a rule saying no; `failed` is an error.", "enum": [ "ok", "refused", "failed" ] }, "Enum_PreBuiltLineType": { "type": "string", "enum": [ "garment", "other", "discount", "surcharge" ] }, "Enum_PreBuiltLineValueType": { "type": "string", "enum": [ "Flat", "Percentage" ] }, "Enum_PreBuiltMarkupType": { "type": "string", "enum": [ "percentage", "flat", "flat_rate" ] }, "Input_SavePreBuiltItemVariantInput": { "type": "object", "properties": { "size": { "type": "string" }, "colour": { "type": "string" }, "quantity": { "type": "number" }, "buyPrice": { "type": "number" }, "extraCost": { "type": "number" }, "markupType": { "$ref": "#/components/schemas/Enum_PreBuiltMarkupType" }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual. A group-resolved markup must send `group` explicitly." }, "unitPriceExGst": { "type": "number" }, "sortOrder": { "type": "integer", "description": "Omit to take the variant's position in the list." }, "isCustomLine": { "type": "boolean" }, "showOnDocuments": { "type": "boolean" } } }, "Local_CustomField": { "type": "object", "required": [ "id", "name", "type", "entity" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "status" ] }, "entity": { "type": "string", "enum": [ "job" ], "default": "job" }, "options": { "type": "array", "items": {} } } }, "Local_CreateCustomField": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "status" ] }, "entity": { "type": "string", "enum": [ "job" ], "default": "job" }, "options": { "type": "array", "items": {} } } }, "Local_UpdateCustomField": { "type": "object", "description": "PATCH semantics. The field id comes from the path and cannot be changed.", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "status" ] }, "entity": { "type": "string", "enum": [ "job" ] }, "options": { "type": "array", "items": {} } } }, "Local_CustomStatus": { "type": "object", "required": [ "id", "kind", "value", "palette" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "job", "quote", "task" ] }, "value": { "type": "string" }, "label": { "type": "string" }, "palette": { "type": "string", "enum": [ "draft", "ready", "active", "paused", "complete", "spot", "teal", "indigo", "purple", "pink", "lime", "static" ] } } }, "Local_CreateCustomStatus": { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "job", "quote", "task" ] }, "value": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "palette": { "type": "string", "enum": [ "draft", "ready", "active", "paused", "complete", "spot", "teal", "indigo", "purple", "pink", "lime", "static" ], "default": "static" } } }, "Local_UpdateCustomStatus": { "type": "object", "description": "PATCH semantics. The status id comes from the path and cannot be changed.", "properties": { "kind": { "type": "string", "enum": [ "job", "quote", "task" ] }, "value": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "palette": { "type": "string", "enum": [ "draft", "ready", "active", "paused", "complete", "spot", "teal", "indigo", "purple", "pink", "lime", "static" ] } } }, "Local_DeletedResource": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "Local_CreateWebhook": { "type": "object", "required": [ "event", "targetUrl" ], "properties": { "event": { "type": "string", "description": "A current value from GET /v1/reference/events." }, "targetUrl": { "type": "string", "format": "uri", "description": "Public HTTPS URL on port 443." } } }, "Local_WebhookSubscription": { "type": "object", "required": [ "id", "eventType", "targetUrl", "secretPrefix", "isActive", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "targetUrl": { "type": "string", "format": "uri" }, "secretPrefix": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Local_WebhookCreated": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Local_WebhookSubscription" }, { "type": "object", "required": [ "signingSecret" ], "properties": { "signingSecret": { "type": "string" } } } ] }, { "type": "object", "required": [ "existing" ], "properties": { "existing": { "$ref": "#/components/schemas/Local_WebhookSubscription" } }, "description": "Returned for an existing subscription. The secret is not returned again." } ] }, "Local_WebhookSecretRotation": { "type": "object", "required": [ "id", "signingSecret", "secretPrefix", "overlapExpiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "signingSecret": { "type": "string" }, "secretPrefix": { "type": "string" }, "overlapExpiresAt": { "type": "string", "format": "date-time" } } }, "Local_WebhookDelivery": { "type": "object", "required": [ "id", "eventType", "status", "attempts", "nextAttemptAt", "deliveredAt", "lastError", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer", "minimum": 0 }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "Local_WebhookRetry": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending" } } }, "Local_Scope": { "type": "object", "required": [ "key", "resource", "action", "label", "description", "readOnly", "sensitive" ], "properties": { "key": { "type": "string" }, "resource": { "type": "string" }, "action": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "readOnly": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "sensitivityNote": { "type": "string" } } }, "Local_WhoAmI": { "type": "object", "required": [ "orgId", "credentialId", "partnerName", "scopes", "actor" ], "properties": { "orgId": { "type": "string", "format": "uuid" }, "credentialId": { "type": "string", "format": "uuid" }, "partnerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "actor": { "oneOf": [ { "type": "object", "required": [ "kind", "operatorEmail" ], "properties": { "kind": { "const": "credential" }, "operatorEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "kind", "userId", "role" ], "properties": { "kind": { "const": "user" }, "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string" } } } ] } } } } }, "x-scopes": [ { "key": "quotes.read", "label": "Read quotes", "description": "Quotes, groups, lines, decorations and quote PDFs.", "readOnly": true, "sensitive": false }, { "key": "quotes.write", "label": "Write quotes", "description": "Create, edit, delete, duplicate, send and convert a quote to a job.", "readOnly": false, "sensitive": false }, { "key": "jobs.read", "label": "Read jobs", "description": "Jobs, groups, lines, decorations and the job activity feed. This includes every internal comment on every job, and the activity feed names your staff.", "readOnly": true, "sensitive": false }, { "key": "jobs.write", "label": "Write jobs", "description": "Create, edit, delete, duplicate and sync a job from its quote. Includes comments.", "readOnly": false, "sensitive": false }, { "key": "customers.read", "label": "Read customers", "description": "Customers, contacts and addresses. Personal data.", "readOnly": true, "sensitive": false }, { "key": "customers.write", "label": "Write customers", "description": "Create, edit, archive and tier customers, and their contacts and addresses. Personal data.", "readOnly": false, "sensitive": false }, { "key": "garments.read", "label": "Read garments", "description": "Garments, variants and assets — your own items and the supplier catalogue.", "readOnly": true, "sensitive": false }, { "key": "garments.write", "label": "Write garments", "description": "Create, edit, delete and bulk-upsert garments, variants, stock and status.", "readOnly": false, "sensitive": false }, { "key": "decorations.read", "label": "Read decorations", "description": "Decoration methods and their facets.", "readOnly": true, "sensitive": false }, { "key": "decorations.write", "label": "Write decorations", "description": "Create, edit and delete decoration methods, individually or in bulk.", "readOnly": false, "sensitive": false }, { "key": "prebuiltitems.read", "label": "Read pre-built items", "description": "Pre-built items.", "readOnly": true, "sensitive": false }, { "key": "prebuiltitems.write", "label": "Write pre-built items", "description": "Save and delete pre-built items, and set their status in bulk.", "readOnly": false, "sensitive": false }, { "key": "purchaseorders.read", "label": "Read purchase orders", "description": "Purchase orders and their line items, by job and by vendor. Supplier cost data.", "readOnly": true, "sensitive": false }, { "key": "purchaseorders.write", "label": "Write purchase orders", "description": "Create, edit, archive and receive purchase orders and their lines. Supplier cost data.", "readOnly": false, "sensitive": false }, { "key": "vendors.read", "label": "Read vendors", "description": "Vendors, their addresses and their contacts.", "readOnly": true, "sensitive": false }, { "key": "vendors.write", "label": "Write vendors", "description": "Create, edit, archive and activate vendors, addresses and contacts.", "readOnly": false, "sensitive": false }, { "key": "proofs.read", "label": "Read proofs", "description": "Proofs, their revision history and mocks.", "readOnly": true, "sensitive": false }, { "key": "proofs.write", "label": "Write proofs", "description": "Create, edit, delete, send and revise proofs, and manage mocks.", "readOnly": false, "sensitive": false }, { "key": "proofs.approve", "label": "Approve proofs", "description": "Record a client decision, confirm a size split, or set a proof status directly.", "readOnly": false, "sensitive": true }, { "key": "tasks.read", "label": "Read production tasks", "description": "Production tasks, assignees, checklists and task comments.", "readOnly": true, "sensitive": false }, { "key": "tasks.write", "label": "Write production tasks", "description": "Create, edit, delete, comment on, check off and attach to production tasks.", "readOnly": false, "sensitive": false }, { "key": "invoices.read", "label": "Read invoices", "description": "Invoices, invoices by quote and invoice PDFs.", "readOnly": true, "sensitive": false }, { "key": "invoices.write", "label": "Write invoices", "description": "Generate an invoice from a quote, send it, and declare a payment claim.", "readOnly": false, "sensitive": false }, { "key": "invoices.settle", "label": "Settle invoices", "description": "Mark paid, unmark, void, refund and dismiss a payment claim.", "readOnly": false, "sensitive": true }, { "key": "invoices.sync", "label": "Sync invoices to accounting", "description": "Push an invoice to Xero or QuickBooks.", "readOnly": false, "sensitive": true }, { "key": "documents.read", "label": "Read documents", "description": "Quote, invoice and job-sheet PDFs. Returns a presigned link valid for 900 seconds — cache the document, never the URL.", "readOnly": true, "sensitive": false }, { "key": "media.write", "label": "Upload media", "description": "Request a presigned upload URL for artwork, mocks and task attachments.", "readOnly": false, "sensitive": false }, { "key": "customfields.read", "label": "Read custom fields", "description": "Custom field definitions.", "readOnly": true, "sensitive": false }, { "key": "customfields.write", "label": "Write custom fields", "description": "Create, edit and delete custom field definitions.", "readOnly": false, "sensitive": true }, { "key": "customstatuses.read", "label": "Read custom statuses", "description": "Custom status definitions.", "readOnly": true, "sensitive": false }, { "key": "customstatuses.write", "label": "Write custom statuses", "description": "Create, edit and delete custom status definitions.", "readOnly": false, "sensitive": true }, { "key": "costs.read", "label": "Read cost fields", "description": "Buy price, extra cost, setup cost and unit cost on every read that carries them. Without this scope those fields are projected out of every response.", "readOnly": true, "sensitive": true }, { "key": "webhooks.read", "label": "Read webhook subscriptions", "description": "List webhook subscriptions and their delivery history.", "readOnly": true, "sensitive": false }, { "key": "webhooks.write", "label": "Manage webhook subscriptions", "description": "Create and delete webhook subscriptions, rotate their signing secrets, and replay a failed delivery.", "readOnly": false, "sensitive": false } ], "paths": { "/v1/me": { "get": { "summary": "The org, credential and granted scopes this request authenticated as.", "operationId": "get_v1_me", "tags": [ "me" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_WhoAmI" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/me' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/reference/types": { "get": { "summary": "The lookup bundle every write endpoint depends on.", "operationId": "get_v1_reference_types", "tags": [ "reference" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Live named vocabularies. Keys can grow; do not hard-code enum values." } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/reference/types' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/reference/statuses": { "get": { "summary": "Built-in status vocabularies, including which purchase-order statuses are derived and therefore not settable.", "operationId": "get_v1_reference_statuses", "tags": [ "reference" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {}, "description": "Built-in status vocabularies and their settable/derived classification." } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/reference/statuses' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/reference/decorations": { "get": { "summary": "Decoration methods, positions and their vocabularies.", "operationId": "get_v1_reference_decorations", "tags": [ "reference" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "methods", "positions" ], "properties": { "methods": { "type": "array", "items": { "type": "string" } }, "positions": { "type": "array", "items": { "type": "string" } } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/reference/decorations' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/reference/scopes": { "get": { "summary": "The scope catalogue, served from its single source.", "operationId": "get_v1_reference_scopes", "tags": [ "reference" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "scopes" ], "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Local_Scope" } } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/reference/scopes' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/reference/events": { "get": { "summary": "The webhook event catalogue.", "operationId": "get_v1_reference_events", "tags": [ "reference" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/reference/events' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/reference/limits": { "get": { "summary": "Rate limits, batch ceilings and page size, from the one limits module.", "operationId": "get_v1_reference_limits", "tags": [ "reference" ], "description": "Any valid credential. No API scope is required.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {}, "description": "Live rate, batch, paging, request-size, webhook and presigned-URL limits. The shape is extensible." } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/reference/limits' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes": { "get": { "summary": "List quotes.", "operationId": "get_v1_quotes", "tags": [ "quotes" ], "description": "Requires the scope quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional clientId filter." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortDirection filter." }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortField filter." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional status filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuotePage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/quotes' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a quote.", "operationId": "post_v1_quotes", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteRef": { "type": "string" }, "status": { "type": "string" }, "reference": { "type": "string" }, "clientId": { "type": "string" }, "contactId": { "type": "string" }, "shippingAddressId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "notes": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "quoteRef": "example", "status": "example", "reference": "example", "clientId": "example", "contactId": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Quote" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"quoteRef\":\"example\",\"status\":\"example\",\"reference\":\"example\",\"clientId\":\"example\",\"contactId\":\"example\"}'" } ] } }, "/v1/quotes/facets": { "get": { "summary": "Filter facets for the quote list.", "operationId": "get_v1_quotes_facets", "tags": [ "quotes" ], "description": "Requires the scope quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteFacets" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/quotes/facets' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}": { "get": { "summary": "One quote with its groups, lines and decorations.", "operationId": "get_v1_quotes_quoteId", "tags": [ "quotes" ], "description": "Requires the scope quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.read" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Quote" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a quote.", "operationId": "patch_v1_quotes_quoteId", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteRef": { "type": "string" }, "status": { "type": "string" }, "reference": { "type": "string" }, "clientId": { "type": "string" }, "contactId": { "type": "string" }, "shippingAddressId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "deliveryMethod": { "type": "string" }, "deliveryDate": { "type": "string", "format": "date" }, "productionDeadline": { "type": "string", "format": "date" }, "invoiceDueDate": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "subtotalExGst": { "type": "number" }, "gstAmount": { "type": "number" }, "totalIncGst": { "type": "number" }, "taxRateId": { "type": "string" }, "taxName": { "type": "string" }, "taxRatePct": { "type": "number" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "quoteRef": "example", "status": "example", "reference": "example", "clientId": "example", "contactId": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Quote" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"quoteRef\":\"example\",\"status\":\"example\",\"reference\":\"example\",\"clientId\":\"example\",\"contactId\":\"example\"}'" } ] }, "delete": { "summary": "Delete a quote.", "operationId": "delete_v1_quotes_quoteId", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}/duplicate": { "post": { "summary": "Duplicate a quote.", "operationId": "post_v1_quotes_quoteId_duplicate", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Quote" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/duplicate' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}/send": { "post": { "summary": "Email a quote to the customer.", "operationId": "post_v1_quotes_quoteId_send", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailTo": { "type": "string" }, "emailSubject": { "type": "string" }, "emailBodyMarkdown": { "type": "string" }, "ccSelfEmail": { "type": "string" } }, "required": [ "emailTo", "emailSubject", "emailBodyMarkdown" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "emailTo": "example", "emailSubject": "example", "emailBodyMarkdown": "example", "ccSelfEmail": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Quote" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/send' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"emailTo\":\"example\",\"emailSubject\":\"example\",\"emailBodyMarkdown\":\"example\",\"ccSelfEmail\":\"example\"}'" } ] } }, "/v1/quotes/{quoteId}/convert-to-job": { "post": { "summary": "Convert a quote into a job.", "operationId": "post_v1_quotes_quoteId_convert_to_job", "tags": [ "quotes" ], "description": "Requires ALL of the scopes quotes.write, jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write", "jobs.write" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markAccepted": { "type": "boolean" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "markAccepted": true } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Job" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/convert-to-job' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"markAccepted\":true}'" } ] } }, "/v1/quotes/{quoteId}/groups": { "post": { "summary": "Add a group to a quote.", "operationId": "post_v1_quotes_quoteId_groups", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "name" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "sortOrder": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteGroup" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/groups' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"sortOrder\":1}'" } ] } }, "/v1/quote-groups/{groupId}": { "patch": { "summary": "Update a quote group.", "operationId": "patch_v1_quote_groups_groupId", "tags": [ "quote-groups" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "totalQuantity": { "type": "integer" }, "sortOrder": { "type": "integer" }, "rollUpDecoration": { "type": "boolean" }, "rollUpSetup": { "type": "boolean" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "totalQuantity": 1, "sortOrder": 1, "rollUpDecoration": true, "rollUpSetup": true } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteGroup" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/quote-groups/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"totalQuantity\":1,\"sortOrder\":1,\"rollUpDecoration\":true,\"rollUpSetup\":true}'" } ] }, "delete": { "summary": "Delete a quote group.", "operationId": "delete_v1_quote_groups_groupId", "tags": [ "quote-groups" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/quote-groups/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quote-groups/{groupId}/lines": { "post": { "summary": "Add a line to a quote group.", "operationId": "post_v1_quote_groups_groupId_lines", "tags": [ "quote-groups" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteGroupId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "unitPriceExGst": { "type": "number" }, "quantity": { "type": "integer" }, "valueType": { "$ref": "#/components/schemas/Enum_LineValueType" }, "percentage": { "type": "number" }, "discountValueType": { "$ref": "#/components/schemas/Enum_DiscountValueType", "description": "Deprecated alias of valueType (F-26). valueType wins when both are sent." }, "discountPercentage": { "type": "number", "description": "Deprecated alias of percentage (F-26). percentage wins when both are sent." }, "sortOrder": { "type": "integer", "description": "Omit to append to the end of the group's row sequence (lines + decorations)." }, "customImageUrl": { "type": "string" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Input_QuoteVariantInput" } } }, "required": [ "productName", "quoteGroupId" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "quoteGroupId": "example", "lineType": "Garment", "garmentCatalogueItemId": "example", "productName": "example", "productSku": "example", "title": "example", "description": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteLine" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quote-groups/11111111-2222-3333-4444-555555555555/lines' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"quoteGroupId\":\"example\",\"lineType\":\"Garment\",\"garmentCatalogueItemId\":\"example\",\"productName\":\"example\",\"productSku\":\"example\",\"title\":\"example\",\"description\":\"example\"}'" } ] } }, "/v1/quote-lines/{lineId}": { "patch": { "summary": "Update a quote line.", "operationId": "patch_v1_quote_lines_lineId", "tags": [ "quote-lines" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "valueType": { "$ref": "#/components/schemas/Enum_LineValueType" }, "percentage": { "type": "number" }, "discountValueType": { "$ref": "#/components/schemas/Enum_DiscountValueType", "description": "Deprecated alias of valueType (F-26). valueType wins when both are sent." }, "discountPercentage": { "type": "number", "description": "Deprecated alias of percentage (F-26). percentage wins when both are sent." }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Input_QuoteVariantInput" } } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "lineType": "Garment", "garmentCatalogueItemId": "example", "productName": "example", "productSku": "example", "title": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteLine" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/quote-lines/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"lineType\":\"Garment\",\"garmentCatalogueItemId\":\"example\",\"productName\":\"example\",\"productSku\":\"example\",\"title\":\"example\"}'" } ] }, "delete": { "summary": "Delete a quote line.", "operationId": "delete_v1_quote_lines_lineId", "tags": [ "quote-lines" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/quote-lines/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quote-groups/{groupId}/decorations": { "post": { "summary": "Attach a decoration to a quote group.", "operationId": "post_v1_quote_groups_groupId_decorations", "tags": [ "quote-groups" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteGroupId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The per-unit markup as saved — see QuoteGroupDecoration.markupType." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual. A group-resolved markup must send `group` explicitly (AC 12)." }, "setupMarkupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The setup lane's own markup — see QuoteGroupDecoration.setupMarkupType." }, "setupMarkupValue": { "type": "number" }, "setupMarkupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual, as for markupSource." }, "rollUp": { "type": "boolean", "description": "Fold this decoration's unit charge into the garment price — see QuoteGroupDecoration.rollUp." }, "rollUpSetup": { "type": "boolean", "description": "Fold its setup charge. Inert unless includeSetupCost." }, "showOnDocuments": { "type": "boolean", "description": "Draw the row on customer-facing documents. Defaults true." }, "description": { "type": "string" }, "widthCm": { "type": "number", "description": "Centimetres — see QuoteGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "specialInstructions": { "type": "string", "description": "Internal only — see QuoteGroupDecoration.specialInstructions." }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "quoteGroupId" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "quoteGroupId": "example", "decorationItemId": "example", "method": "ScreenPrinting", "position": "example", "quantity": 1, "setupCost": 1.5 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteGroupDecoration" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quote-groups/11111111-2222-3333-4444-555555555555/decorations' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"quoteGroupId\":\"example\",\"decorationItemId\":\"example\",\"method\":\"ScreenPrinting\",\"position\":\"example\",\"quantity\":1,\"setupCost\":1.5}'" } ] } }, "/v1/quote-group-decorations/{decorationId}": { "patch": { "summary": "Update a quote-group decoration.", "operationId": "patch_v1_quote_group_decorations_decorationId", "tags": [ "quote-group-decorations" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "markupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The per-unit markup as saved — see QuoteGroupDecoration.markupType." }, "markupValue": { "type": "number" }, "markupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual. A group-resolved markup must send `group` explicitly (AC 12)." }, "setupMarkupType": { "$ref": "#/components/schemas/Enum_MarkupType", "description": "The setup lane's own markup — see QuoteGroupDecoration.setupMarkupType." }, "setupMarkupValue": { "type": "number" }, "setupMarkupSource": { "$ref": "#/components/schemas/Enum_MarkupSource", "description": "Omitted → manual, as for markupSource." }, "rollUp": { "type": "boolean", "description": "Fold this decoration's unit charge into the garment price — see QuoteGroupDecoration.rollUp." }, "rollUpSetup": { "type": "boolean", "description": "Fold its setup charge. Inert unless includeSetupCost." }, "showOnDocuments": { "type": "boolean", "description": "Draw the row on customer-facing documents. Defaults true." }, "description": { "type": "string" }, "widthCm": { "type": "number", "description": "Centimetres — see QuoteGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "specialInstructions": { "type": "string", "description": "Internal only — see QuoteGroupDecoration.specialInstructions." }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "decorationItemId": "example", "method": "ScreenPrinting", "position": "example", "quantity": 1, "setupCost": 1.5 } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuoteGroupDecoration" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/quote-group-decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"decorationItemId\":\"example\",\"method\":\"ScreenPrinting\",\"position\":\"example\",\"quantity\":1,\"setupCost\":1.5}'" } ] }, "delete": { "summary": "Remove a decoration from a quote group.", "operationId": "delete_v1_quote_group_decorations_decorationId", "tags": [ "quote-group-decorations" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/quote-group-decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/bulk/delete": { "post": { "summary": "Delete every quote matching a target.", "operationId": "post_v1_quotes_bulk_delete", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/bulk/delete' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/quotes/bulk/duplicate": { "post": { "summary": "Duplicate every quote matching a target.", "operationId": "post_v1_quotes_bulk_duplicate", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/bulk/duplicate' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/quotes/bulk/status": { "post": { "summary": "Set the status of every quote matching a target.", "operationId": "post_v1_quotes_bulk_status", "tags": [ "quotes" ], "description": "Requires the scope quotes.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "status": { "type": "string" } }, "required": [ "status", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "status": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/bulk/status' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"status\":\"example\"}'" } ] } }, "/v1/quotes/bulk/convert-to-jobs": { "post": { "summary": "Convert every quote matching a target into a job.", "operationId": "post_v1_quotes_bulk_convert_to_jobs", "tags": [ "quotes" ], "description": "Requires ALL of the scopes quotes.write, jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.write", "jobs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/bulk/convert-to-jobs' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/jobs": { "get": { "summary": "List jobs, newest first.", "operationId": "get_v1_jobs", "tags": [ "jobs" ], "description": "Requires the scope jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional customerId filter." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortDirection filter." }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortField filter." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional status filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobPage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a job.", "operationId": "post_v1_jobs", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Blank-job creation (createJob). All optional; status defaults to 'Draft'.", "properties": { "jobName": { "type": "string" }, "status": { "type": "string" }, "customerId": { "type": "string" }, "contactId": { "type": "string" }, "reference": { "type": "string" }, "jobNotes": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "jobName": "example", "status": "example", "customerId": "example", "contactId": "example", "reference": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Job" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"jobName\":\"example\",\"status\":\"example\",\"customerId\":\"example\",\"contactId\":\"example\",\"reference\":\"example\"}'" } ] } }, "/v1/jobs/facets": { "get": { "summary": "Filter facets for the job list.", "operationId": "get_v1_jobs_facets", "tags": [ "jobs" ], "description": "Requires the scope jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobFacets" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/facets' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}": { "get": { "summary": "One job with its groups, lines and decorations.", "operationId": "get_v1_jobs_jobId", "tags": [ "jobs" ], "description": "Requires the scope jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Job" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a job.", "operationId": "patch_v1_jobs_jobId", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobRef": { "type": "string" }, "jobName": { "type": "string" }, "status": { "type": "string" }, "contactId": { "type": "string" }, "salesRepEmail": { "type": "string" }, "reference": { "type": "string" }, "priority": { "$ref": "#/components/schemas/Enum_JobPriority" }, "shipPickupDate": { "type": "string", "format": "date" }, "productionDeadline": { "type": "string", "format": "date" }, "deliveryMethod": { "type": "string" }, "shippingBranding": { "type": "string" }, "shippingAddressId": { "type": "string" }, "paymentType": { "type": "string" }, "invoiceStatus": { "type": "string" }, "scheduledStartDate": { "type": "string", "format": "date" }, "scheduledEndDate": { "type": "string", "format": "date" }, "estimatedDuration": { "type": "number" }, "jobNotes": { "type": "string" }, "clientNotes": { "type": "string" }, "customFieldValues": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "jobRef": "example", "jobName": "example", "status": "example", "contactId": "example", "salesRepEmail": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Job" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"jobRef\":\"example\",\"jobName\":\"example\",\"status\":\"example\",\"contactId\":\"example\",\"salesRepEmail\":\"example\"}'" } ] }, "delete": { "summary": "Delete a job.", "operationId": "delete_v1_jobs_jobId", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}/activity": { "get": { "summary": "The job activity feed. Names the staff who acted.", "operationId": "get_v1_jobs_jobId_activity", "tags": [ "jobs" ], "description": "Requires the scope jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_JobActivity" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/activity' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}/duplicate": { "post": { "summary": "Duplicate a job.", "operationId": "post_v1_jobs_jobId_duplicate", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Job" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/duplicate' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}/sync-from-quote": { "post": { "summary": "Re-sync a job from the quote it came from.", "operationId": "post_v1_jobs_jobId_sync_from_quote", "tags": [ "jobs" ], "description": "Requires ALL of the scopes jobs.write, quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write", "quotes.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Job" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/sync-from-quote' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}/groups": { "post": { "summary": "Add a group to a job.", "operationId": "post_v1_jobs_jobId_groups", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "name" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "notes": "example", "sortOrder": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobGroup" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/groups' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"notes\":\"example\",\"sortOrder\":1}'" } ] } }, "/v1/job-groups/{groupId}": { "patch": { "summary": "Update a job group.", "operationId": "patch_v1_job_groups_groupId", "tags": [ "job-groups" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "totalQuantity": { "type": "integer" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "totalQuantity": 1, "notes": "example", "sortOrder": 1 } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobGroup" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/job-groups/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"totalQuantity\":1,\"notes\":\"example\",\"sortOrder\":1}'" } ] }, "delete": { "summary": "Delete a job group.", "operationId": "delete_v1_job_groups_groupId", "tags": [ "job-groups" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/job-groups/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/job-groups/{groupId}/lines": { "post": { "summary": "Add a line to a job group.", "operationId": "post_v1_job_groups_groupId_lines", "tags": [ "job-groups" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobGroupId": { "type": "string" }, "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "unitPriceExGst": { "type": "number" }, "quantity": { "type": "integer" }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Input_JobVariantInput" } } }, "required": [ "jobGroupId", "productName" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "jobGroupId": "example", "lineType": "Garment", "garmentCatalogueItemId": "example", "productName": "example", "productSku": "example", "title": "example", "description": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobLine" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/job-groups/11111111-2222-3333-4444-555555555555/lines' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"jobGroupId\":\"example\",\"lineType\":\"Garment\",\"garmentCatalogueItemId\":\"example\",\"productName\":\"example\",\"productSku\":\"example\",\"title\":\"example\",\"description\":\"example\"}'" } ] } }, "/v1/job-lines/{lineId}": { "patch": { "summary": "Update a job line.", "operationId": "patch_v1_job_lines_lineId", "tags": [ "job-lines" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lineType": { "$ref": "#/components/schemas/Enum_QuoteLineType" }, "garmentCatalogueItemId": { "type": "string" }, "productName": { "type": "string" }, "productSku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceExGst": { "type": "number" }, "sortOrder": { "type": "integer" }, "customImageUrl": { "type": "string", "description": "Omitted leaves the stored image alone, so the wizard rewriting a job's lines\ncannot blank a mock it does not know about. Explicit null clears it — the same\ncontract `UpdateQuoteLineInput.customImageUrl` already uses." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Input_JobVariantInput" } } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "lineType": "Garment", "garmentCatalogueItemId": "example", "productName": "example", "productSku": "example", "title": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobLine" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/job-lines/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"lineType\":\"Garment\",\"garmentCatalogueItemId\":\"example\",\"productName\":\"example\",\"productSku\":\"example\",\"title\":\"example\"}'" } ] }, "delete": { "summary": "Delete a job line.", "operationId": "delete_v1_job_lines_lineId", "tags": [ "job-lines" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/job-lines/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/job-groups/{groupId}/decorations": { "post": { "summary": "Attach a decoration to a job group.", "operationId": "post_v1_job_groups_groupId_decorations", "tags": [ "job-groups" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobGroupId": { "type": "string" }, "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "description": { "type": "string" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "widthCm": { "type": "number", "description": "Centimetres — see JobGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "specialInstructions": { "type": "string" }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "jobGroupId" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "jobGroupId": "example", "decorationItemId": "example", "method": "ScreenPrinting", "position": "example", "quantity": 1, "description": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobGroupDecoration" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/job-groups/11111111-2222-3333-4444-555555555555/decorations' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"jobGroupId\":\"example\",\"decorationItemId\":\"example\",\"method\":\"ScreenPrinting\",\"position\":\"example\",\"quantity\":1,\"description\":\"example\"}'" } ] } }, "/v1/job-group-decorations/{decorationId}": { "patch": { "summary": "Update a job-group decoration.", "operationId": "patch_v1_job_group_decorations_decorationId", "tags": [ "job-group-decorations" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decorationItemId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_JobDecorationMethod" }, "position": { "type": "string" }, "quantity": { "type": "integer" }, "description": { "type": "string" }, "colours": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationColourInput" }, "description": "Replaces the whole list. At most one entry keeps `isBase` — see DecorationColour." }, "screenCount": { "type": "integer" }, "screenMeshGrade": { "type": "string" }, "colourCount": { "type": "integer" }, "setupCost": { "type": "number" }, "unitCost": { "type": "number" }, "baseUnitCost": { "type": "number" }, "baseSetupCost": { "type": "number" }, "includeSetupCost": { "type": "boolean" }, "widthCm": { "type": "number", "description": "Centimetres — see JobGroupDecoration.widthCm." }, "lengthCm": { "type": "number" }, "necklineDropCm": { "type": "number" }, "specialInstructions": { "type": "string" }, "artworkFileUrl": { "type": "string" }, "separationFileUrl": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "decorationItemId": "example", "method": "ScreenPrinting", "position": "example", "quantity": 1, "description": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobGroupDecoration" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/job-group-decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"decorationItemId\":\"example\",\"method\":\"ScreenPrinting\",\"position\":\"example\",\"quantity\":1,\"description\":\"example\"}'" } ] }, "delete": { "summary": "Remove a decoration from a job group.", "operationId": "delete_v1_job_group_decorations_decorationId", "tags": [ "job-group-decorations" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/job-group-decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/bulk/update": { "post": { "summary": "Patch every job matching a target.", "operationId": "post_v1_jobs_bulk_update", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "input": { "$ref": "#/components/schemas/Input_BulkJobPatchInput" } }, "required": [ "input", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "input": { "status": "example", "priority": "example", "salesRepEmail": "example", "customFieldValues": {} } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/bulk/update' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"input\":{\"status\":\"example\",\"priority\":\"example\",\"salesRepEmail\":\"example\",\"customFieldValues\":{}}}'" } ] } }, "/v1/jobs/bulk/delete": { "post": { "summary": "Delete every job matching a target.", "operationId": "post_v1_jobs_bulk_delete", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/bulk/delete' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/jobs/bulk/duplicate": { "post": { "summary": "Duplicate every job matching a target.", "operationId": "post_v1_jobs_bulk_duplicate", "tags": [ "jobs" ], "description": "Requires the scope jobs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/bulk/duplicate' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/customers": { "get": { "summary": "List customers.", "operationId": "get_v1_customers", "tags": [ "customers" ], "description": "Requires the scope customers.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Optional includeArchived filter." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortDirection filter." }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortField filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_CustomerPage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/customers' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a customer.", "operationId": "post_v1_customers", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_CustomerKind" }, "businessName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "abn": { "type": "string" }, "tier": { "type": "string" }, "notes": { "type": "string" }, "portalToken": { "type": "string" } }, "required": [ "kind" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "kind": "Business", "businessName": "example", "firstName": "example", "lastName": "example", "email": "example", "phone": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Customer" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"kind\":\"Business\",\"businessName\":\"example\",\"firstName\":\"example\",\"lastName\":\"example\",\"email\":\"example\",\"phone\":\"example\"}'" } ] } }, "/v1/customers/{customerId}": { "get": { "summary": "One customer with contacts and addresses.", "operationId": "get_v1_customers_customerId", "tags": [ "customers" ], "description": "Requires the scope customers.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.read" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Customer" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a customer.", "operationId": "patch_v1_customers_customerId", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_CustomerKind" }, "businessName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "abn": { "type": "string" }, "tier": { "type": "string" }, "notes": { "type": "string" }, "defaultBillingAddressId": { "type": "string" }, "defaultShippingAddressId": { "type": "string" }, "primaryContactId": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "kind": "Business", "businessName": "example", "firstName": "example", "lastName": "example", "email": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Customer" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"kind\":\"Business\",\"businessName\":\"example\",\"firstName\":\"example\",\"lastName\":\"example\",\"email\":\"example\"}'" } ] } }, "/v1/customers/{customerId}/archive": { "post": { "summary": "Archive a customer.", "operationId": "post_v1_customers_customerId_archive", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Customer" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555/archive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/customers/{customerId}/unarchive": { "post": { "summary": "Restore an archived customer.", "operationId": "post_v1_customers_customerId_unarchive", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Customer" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555/unarchive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/customers/{customerId}/contacts": { "post": { "summary": "Add a contact to a customer.", "operationId": "post_v1_customers_customerId_contacts", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fullName": { "type": "string" }, "isPrimary": { "type": "boolean" }, "roleTitle": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": "string" }, "includeInAccountingEmails": { "type": "boolean" } }, "required": [ "fullName" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "fullName": "example", "isPrimary": true, "roleTitle": "example", "email": "example", "phone": "example", "notes": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Contact" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555/contacts' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"fullName\":\"example\",\"isPrimary\":true,\"roleTitle\":\"example\",\"email\":\"example\",\"phone\":\"example\",\"notes\":\"example\"}'" } ] } }, "/v1/contacts/{contactId}": { "patch": { "summary": "Update a contact.", "operationId": "patch_v1_contacts_contactId", "tags": [ "contacts" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fullName": { "type": "string" }, "isPrimary": { "type": "boolean" }, "roleTitle": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": "string" }, "includeInAccountingEmails": { "type": "boolean" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "fullName": "example", "isPrimary": true, "roleTitle": "example", "email": "example", "phone": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Contact" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/contacts/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"fullName\":\"example\",\"isPrimary\":true,\"roleTitle\":\"example\",\"email\":\"example\",\"phone\":\"example\"}'" } ] }, "delete": { "summary": "Delete a contact.", "operationId": "delete_v1_contacts_contactId", "tags": [ "contacts" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/contacts/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/customers/{customerId}/addresses": { "post": { "summary": "Add an address to a customer.", "operationId": "post_v1_customers_customerId_addresses", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_AddressKind" }, "fullAddress": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "suburb": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "kind": "Billing", "fullAddress": "example", "line1": "example", "line2": "example", "suburb": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_CustomerAddress" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555/addresses' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"kind\":\"Billing\",\"fullAddress\":\"example\",\"line1\":\"example\",\"line2\":\"example\",\"suburb\":\"example\"}'" } ] } }, "/v1/addresses/{addressId}": { "patch": { "summary": "Update an address.", "operationId": "patch_v1_addresses_addressId", "tags": [ "addresses" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Enum_AddressKind" }, "fullAddress": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "suburb": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "kind": "Billing", "fullAddress": "example", "line1": "example", "line2": "example", "suburb": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_CustomerAddress" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/addresses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"kind\":\"Billing\",\"fullAddress\":\"example\",\"line1\":\"example\",\"line2\":\"example\",\"suburb\":\"example\"}'" } ] }, "delete": { "summary": "Delete an address.", "operationId": "delete_v1_addresses_addressId", "tags": [ "addresses" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/addresses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/customers/bulk/create": { "post": { "summary": "Create many customers in one call.", "operationId": "post_v1_customers_bulk_create", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Input_BulkCreateCustomerInput" } } }, "required": [ "input" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Input_BulkCreateCustomerInput" } } }, "required": [ "items" ] } ], "description": "Provide one array field. input is preferred; items remains accepted for compatibility. The live bulk row limit applies." }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "input": [ { "customer": { "kind": "Business", "businessName": "example", "firstName": "example", "lastName": "example", "email": "example", "phone": "example" }, "contacts": [ { "fullName": "example", "isPrimary": true, "roleTitle": "example", "email": "example", "phone": "example", "notes": "example" } ] } ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Customer" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/bulk/create' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"input\":[{\"customer\":{\"kind\":\"Business\",\"businessName\":\"example\",\"firstName\":\"example\",\"lastName\":\"example\",\"email\":\"example\",\"phone\":\"example\"},\"contacts\":[{\"fullName\":\"example\",\"isPrimary\":true,\"roleTitle\":\"example\",\"email\":\"example\",\"phone\":\"example\",\"notes\":\"example\"}]}]}'" } ] } }, "/v1/customers/bulk/archive": { "post": { "summary": "Archive or restore every customer matching a target.", "operationId": "post_v1_customers_bulk_archive", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "archived": { "type": "boolean" } }, "required": [ "archived", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "archived": true } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/bulk/archive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"archived\":true}'" } ] } }, "/v1/customers/bulk/tier": { "post": { "summary": "Set the tier of every customer matching a target.", "operationId": "post_v1_customers_bulk_tier", "tags": [ "customers" ], "description": "Requires the scope customers.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "tier": { "type": "string" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "tier": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/customers/bulk/tier' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"tier\":\"example\"}'" } ] } }, "/v1/garments": { "get": { "summary": "List garments — the shop’s own items and the supplier catalogue.", "operationId": "get_v1_garments", "tags": [ "garments" ], "description": "Requires the scope garments.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "description": "Optional status filter." }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional vendorId filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentPage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/garments' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a garment.", "operationId": "post_v1_garments", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "styleCode": { "type": "string" }, "styleName": { "type": "string" }, "supplier": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "composition": { "type": "string" }, "fabric": { "type": "string" }, "boxQty": { "type": "integer" }, "unitPrice": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "vendorId": { "type": "string" }, "vendorName": { "type": "string", "description": "Vendor by NAME, honoured by `bulkUpsertGarments` ONLY — `createGarment` and `bulkCreateGarments` share this input type but reject it, rather than accepting a vendor they would not link. Resolved case-insensitively, created as type Supplier if unknown, inside this call's transaction. Distinct from `supplier`, which stays free text." } }, "required": [ "styleCode", "styleName" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "styleCode": "example", "styleName": "example", "supplier": "example", "brand": "example", "category": "example", "description": "example", "composition": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garments' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"styleCode\":\"example\",\"styleName\":\"example\",\"supplier\":\"example\",\"brand\":\"example\",\"category\":\"example\",\"description\":\"example\",\"composition\":\"example\"}'" } ] } }, "/v1/garments/facets": { "get": { "summary": "Filter facets for the garment list.", "operationId": "get_v1_garments_facets", "tags": [ "garments" ], "description": "Requires the scope garments.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentFacets" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/garments/facets' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/garments/assets": { "get": { "summary": "Garment assets.", "operationId": "get_v1_garments_assets", "tags": [ "garments" ], "description": "Requires the scope garments.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentAsset" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/garments/assets' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/garments/{garmentId}": { "get": { "summary": "One garment.", "operationId": "get_v1_garments_garmentId", "tags": [ "garments" ], "description": "Requires the scope garments.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.read" ], "parameters": [ { "name": "garmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/garments/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a garment.", "operationId": "patch_v1_garments_garmentId", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "garmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "styleCode": { "type": "string" }, "styleName": { "type": "string" }, "supplier": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "composition": { "type": "string" }, "fabric": { "type": "string" }, "boxQty": { "type": "integer" }, "unitPrice": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_GarmentStatus" }, "vendorId": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "styleCode": "example", "styleName": "example", "supplier": "example", "brand": "example", "category": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/garments/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"styleCode\":\"example\",\"styleName\":\"example\",\"supplier\":\"example\",\"brand\":\"example\",\"category\":\"example\"}'" } ] }, "delete": { "summary": "Delete a garment.", "operationId": "delete_v1_garments_garmentId", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "garmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/garments/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/garment-variants/{styleCode}": { "get": { "summary": "Every variant of one style code.", "operationId": "get_v1_garment_variants_styleCode", "tags": [ "garment-variants" ], "description": "Requires the scope garments.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.read" ], "parameters": [ { "name": "styleCode", "in": "path", "required": true, "schema": { "type": "string", "example": "AS4001" } }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentVariant" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/garment-variants/AS4001' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/garment-variants": { "post": { "summary": "Create a garment variant.", "operationId": "post_v1_garment_variants", "tags": [ "garment-variants" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "stockCode": { "type": "string" }, "color": { "type": "string" }, "colorHex": { "type": "string" }, "size": { "type": "string" }, "countryOfManufacture": { "type": "string" }, "stockOnHand": { "type": "integer" }, "stockReserved": { "type": "integer" }, "supplierStock": { "type": "integer" }, "unitPrice": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "styleCode", "color", "size" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "garmentCatalogueItemId": "example", "styleCode": "example", "stockCode": "example", "color": "example", "colorHex": "example", "size": "example", "countryOfManufacture": "example", "stockOnHand": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentVariant" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garment-variants' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"garmentCatalogueItemId\":\"example\",\"styleCode\":\"example\",\"stockCode\":\"example\",\"color\":\"example\",\"colorHex\":\"example\",\"size\":\"example\",\"countryOfManufacture\":\"example\",\"stockOnHand\":1}'" } ] } }, "/v1/garment-variants/id/{variantId}": { "patch": { "summary": "Update a garment variant.", "operationId": "patch_v1_garment_variants_id_variantId", "tags": [ "garment-variants" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stockCode": { "type": "string" }, "color": { "type": "string" }, "colorHex": { "type": "string" }, "size": { "type": "string" }, "countryOfManufacture": { "type": "string" }, "stockOnHand": { "type": "integer" }, "stockReserved": { "type": "integer" }, "supplierStock": { "type": "integer" }, "unitPrice": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "stockCode": "example", "color": "example", "colorHex": "example", "size": "example", "countryOfManufacture": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentVariant" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/garment-variants/id/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"stockCode\":\"example\",\"color\":\"example\",\"colorHex\":\"example\",\"size\":\"example\",\"countryOfManufacture\":\"example\"}'" } ] }, "delete": { "summary": "Delete a garment variant.", "operationId": "delete_v1_garment_variants_id_variantId", "tags": [ "garment-variants" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/garment-variants/id/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/garment-assets": { "post": { "summary": "Create a garment asset.", "operationId": "post_v1_garment_assets", "tags": [ "garment-assets" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "side": { "$ref": "#/components/schemas/Enum_GarmentAssetSide" }, "sizeLabel": { "type": "string" }, "image": { "type": "string" }, "safeArea": { "$ref": "#/components/schemas/Input_GarmentAssetSafeAreaInput" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "styleCode", "name", "color", "image" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "garmentCatalogueItemId": "example", "styleCode": "example", "name": "example", "color": "example", "side": "front", "sizeLabel": "example", "image": "example", "safeArea": { "x": 1.5, "y": 1.5, "w": 1.5, "h": 1.5 }, "notes": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentAsset" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garment-assets' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"garmentCatalogueItemId\":\"example\",\"styleCode\":\"example\",\"name\":\"example\",\"color\":\"example\",\"side\":\"front\",\"sizeLabel\":\"example\",\"image\":\"example\",\"safeArea\":{\"x\":1.5,\"y\":1.5,\"w\":1.5,\"h\":1.5},\"notes\":\"example\"}'" } ] } }, "/v1/garment-assets/{assetId}": { "patch": { "summary": "Update a garment asset.", "operationId": "patch_v1_garment_assets_assetId", "tags": [ "garment-assets" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "garmentCatalogueItemId": { "type": "string" }, "styleCode": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "side": { "$ref": "#/components/schemas/Enum_GarmentAssetSide" }, "sizeLabel": { "type": "string" }, "image": { "type": "string" }, "safeArea": { "$ref": "#/components/schemas/Input_GarmentAssetSafeAreaInput" }, "notes": { "type": "string" }, "isActive": { "type": "boolean" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "garmentCatalogueItemId": "example", "styleCode": "example", "name": "example", "color": "example", "side": "front" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_GarmentAsset" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/garment-assets/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"garmentCatalogueItemId\":\"example\",\"styleCode\":\"example\",\"name\":\"example\",\"color\":\"example\",\"side\":\"front\"}'" } ] }, "delete": { "summary": "Delete a garment asset.", "operationId": "delete_v1_garment_assets_assetId", "tags": [ "garment-assets" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/garment-assets/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/garments/bulk/create": { "post": { "summary": "Create many garments in one call.", "operationId": "post_v1_garments_bulk_create", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentInput" } } }, "required": [ "input" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentInput" } } }, "required": [ "items" ] } ], "description": "Provide one array field. input is preferred; items remains accepted for compatibility. The live bulk row limit applies." }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "input": [ { "styleCode": "example", "styleName": "example", "supplier": "example", "brand": "example", "category": "example", "description": "example", "composition": "example" } ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garments/bulk/create' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"input\":[{\"styleCode\":\"example\",\"styleName\":\"example\",\"supplier\":\"example\",\"brand\":\"example\",\"category\":\"example\",\"description\":\"example\",\"composition\":\"example\"}]}'" } ] } }, "/v1/garments/bulk/upsert": { "post": { "summary": "Upsert a catalogue of garments in one set-based call.", "operationId": "post_v1_garments_bulk_upsert", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentInput" } }, "mode": { "$ref": "#/components/schemas/Enum_BulkImportMode" }, "allowDuplicateStyleCodes": { "type": "boolean" }, "importBatchId": { "type": "string" } }, "required": [ "input", "mode" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentInput" } }, "mode": { "$ref": "#/components/schemas/Enum_BulkImportMode" }, "allowDuplicateStyleCodes": { "type": "boolean" }, "importBatchId": { "type": "string" } }, "required": [ "items", "mode" ] } ], "description": "Provide one array field. input is preferred; items remains accepted for compatibility. The live bulk row limit applies." }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "input": [ { "styleCode": "example", "styleName": "example", "supplier": "example", "brand": "example", "category": "example", "description": "example", "composition": "example" } ], "mode": "CreateOnly", "allowDuplicateStyleCodes": true, "importBatchId": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkGarmentImportResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garments/bulk/upsert' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"input\":[{\"styleCode\":\"example\",\"styleName\":\"example\",\"supplier\":\"example\",\"brand\":\"example\",\"category\":\"example\",\"description\":\"example\",\"composition\":\"example\"}],\"mode\":\"CreateOnly\",\"allowDuplicateStyleCodes\":true,\"importBatchId\":\"example\"}'" } ] } }, "/v1/garments/bulk/update": { "post": { "summary": "Patch every garment matching a target.", "operationId": "post_v1_garments_bulk_update", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "input": { "$ref": "#/components/schemas/Input_BulkGarmentPatchInput" } }, "required": [ "input", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "input": { "status": "on_hand", "stockOnHand": 1, "vendorId": "11111111-2222-3333-4444-555555555555", "markupGroupId": "11111111-2222-3333-4444-555555555555" } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garments/bulk/update' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"input\":{\"status\":\"on_hand\",\"stockOnHand\":1,\"vendorId\":\"11111111-2222-3333-4444-555555555555\",\"markupGroupId\":\"11111111-2222-3333-4444-555555555555\"}}'" } ] } }, "/v1/garments/bulk/delete": { "post": { "summary": "Delete every garment matching a target.", "operationId": "post_v1_garments_bulk_delete", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garments/bulk/delete' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/garment-variants/bulk/create": { "post": { "summary": "Create many garment variants in one call.", "operationId": "post_v1_garment_variants_bulk_create", "tags": [ "garment-variants" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentVariantInput" } } }, "required": [ "input" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentVariantInput" } } }, "required": [ "items" ] } ], "description": "Provide one array field. input is preferred; items remains accepted for compatibility. The live bulk row limit applies." }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "input": [ { "garmentCatalogueItemId": "11111111-2222-3333-4444-555555555555", "styleCode": "example", "stockCode": "example", "color": "example", "colorHex": "example", "size": "example", "countryOfManufacture": "example", "stockOnHand": 1 } ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentVariant" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garment-variants/bulk/create' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"input\":[{\"garmentCatalogueItemId\":\"11111111-2222-3333-4444-555555555555\",\"styleCode\":\"example\",\"stockCode\":\"example\",\"color\":\"example\",\"colorHex\":\"example\",\"size\":\"example\",\"countryOfManufacture\":\"example\",\"stockOnHand\":1}]}'" } ] } }, "/v1/garment-variants/bulk/upsert": { "post": { "summary": "Upsert garment variants in one set-based call.", "operationId": "post_v1_garment_variants_bulk_upsert", "tags": [ "garment-variants" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentVariantInput" } }, "mode": { "$ref": "#/components/schemas/Enum_BulkImportMode" }, "importBatchId": { "type": "string" } }, "required": [ "input", "mode" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateGarmentVariantInput" } }, "mode": { "$ref": "#/components/schemas/Enum_BulkImportMode" }, "importBatchId": { "type": "string" } }, "required": [ "items", "mode" ] } ], "description": "Provide one array field. input is preferred; items remains accepted for compatibility. The live bulk row limit applies." }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "input": [ { "garmentCatalogueItemId": "11111111-2222-3333-4444-555555555555", "styleCode": "example", "stockCode": "example", "color": "example", "colorHex": "example", "size": "example", "countryOfManufacture": "example", "stockOnHand": 1 } ], "mode": "CreateOnly", "importBatchId": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkVariantImportResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garment-variants/bulk/upsert' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"input\":[{\"garmentCatalogueItemId\":\"11111111-2222-3333-4444-555555555555\",\"styleCode\":\"example\",\"stockCode\":\"example\",\"color\":\"example\",\"colorHex\":\"example\",\"size\":\"example\",\"countryOfManufacture\":\"example\",\"stockOnHand\":1}],\"mode\":\"CreateOnly\",\"importBatchId\":\"example\"}'" } ] } }, "/v1/garments/bulk/status-and-stock": { "post": { "summary": "Set status and stock across an import batch.", "operationId": "post_v1_garments_bulk_status_and_stock", "tags": [ "garments" ], "description": "Requires the scope garments.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "importBatchId": { "type": "string" }, "status": { "type": "string" }, "stockOnHand": { "type": "integer" } }, "required": [ "importBatchId" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "importBatchId": "example", "status": "example", "stockOnHand": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkSetGarmentStockResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/garments/bulk/status-and-stock' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"importBatchId\":\"example\",\"status\":\"example\",\"stockOnHand\":1}'" } ] } }, "/v1/decorations": { "get": { "summary": "List decorations.", "operationId": "get_v1_decorations", "tags": [ "decorations" ], "description": "Requires the scope decorations.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional vendorId filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_DecorationPage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/decorations' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a decoration.", "operationId": "post_v1_decorations", "tags": [ "decorations" ], "description": "Requires the scope decorations.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_DecorationMethod" }, "description": { "type": "string" }, "setupCost": { "type": "number" }, "screenCount": { "type": "integer" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationPriceBreakInput" } }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "vendorId": { "type": "string" } }, "required": [ "name", "method" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "method": "screen_printing", "description": "example", "setupCost": 1.5, "screenCount": 1, "priceBreaks": [ { "quantityRange": "example", "price": 1.5 } ], "notes": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_DecorationCatalogueItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/decorations' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"method\":\"screen_printing\",\"description\":\"example\",\"setupCost\":1.5,\"screenCount\":1,\"priceBreaks\":[{\"quantityRange\":\"example\",\"price\":1.5}],\"notes\":\"example\"}'" } ] } }, "/v1/decorations/facets": { "get": { "summary": "Filter facets for the decoration list.", "operationId": "get_v1_decorations_facets", "tags": [ "decorations" ], "description": "Requires the scope decorations.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_DecorationFacets" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/decorations/facets' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/decorations/{decorationId}": { "get": { "summary": "One decoration.", "operationId": "get_v1_decorations_decorationId", "tags": [ "decorations" ], "description": "Requires the scope decorations.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.read" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_DecorationCatalogueItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a decoration.", "operationId": "patch_v1_decorations_decorationId", "tags": [ "decorations" ], "description": "Requires the scope decorations.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.write" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "method": { "$ref": "#/components/schemas/Enum_DecorationMethod" }, "description": { "type": "string" }, "setupCost": { "type": "number" }, "screenCount": { "type": "integer" }, "priceBreaks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_DecorationPriceBreakInput" } }, "notes": { "type": "string" }, "isActive": { "type": "boolean" }, "vendorId": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "method": "screen_printing", "description": "example", "setupCost": 1.5, "screenCount": 1 } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_DecorationCatalogueItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"method\":\"screen_printing\",\"description\":\"example\",\"setupCost\":1.5,\"screenCount\":1}'" } ] }, "delete": { "summary": "Delete a decoration.", "operationId": "delete_v1_decorations_decorationId", "tags": [ "decorations" ], "description": "Requires the scope decorations.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.write" ], "parameters": [ { "name": "decorationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/decorations/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/decorations/bulk/create": { "post": { "summary": "Create many decorations in one call.", "operationId": "post_v1_decorations_bulk_create", "tags": [ "decorations" ], "description": "Requires the scope decorations.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateDecorationInput" } } }, "required": [ "input" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Input_CreateDecorationInput" } } }, "required": [ "items" ] } ], "description": "Provide one array field. input is preferred; items remains accepted for compatibility. The live bulk row limit applies." }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "input": [ { "name": "example", "method": "screen_printing", "description": "example", "setupCost": 1.5, "screenCount": 1, "priceBreaks": [ { "quantityRange": "example", "price": 1.5 } ], "notes": "example" } ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_DecorationCatalogueItem" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/decorations/bulk/create' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"input\":[{\"name\":\"example\",\"method\":\"screen_printing\",\"description\":\"example\",\"setupCost\":1.5,\"screenCount\":1,\"priceBreaks\":[{\"quantityRange\":\"example\",\"price\":1.5}],\"notes\":\"example\"}]}'" } ] } }, "/v1/decorations/bulk/update": { "post": { "summary": "Patch every decoration matching a target.", "operationId": "post_v1_decorations_bulk_update", "tags": [ "decorations" ], "description": "Requires the scope decorations.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "input": { "$ref": "#/components/schemas/Input_BulkDecorationPatchInput" } }, "required": [ "input", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "input": { "vendorId": "11111111-2222-3333-4444-555555555555", "isActive": true } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/decorations/bulk/update' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"input\":{\"vendorId\":\"11111111-2222-3333-4444-555555555555\",\"isActive\":true}}'" } ] } }, "/v1/decorations/bulk/delete": { "post": { "summary": "Delete every decoration matching a target.", "operationId": "post_v1_decorations_bulk_delete", "tags": [ "decorations" ], "description": "Requires the scope decorations.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "decorations.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/decorations/bulk/delete' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/prebuilt-items": { "get": { "summary": "List pre-built items.", "operationId": "get_v1_prebuilt_items", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PreBuiltItem" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/prebuilt-items' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a pre-built item (server-assigned id).", "operationId": "post_v1_prebuilt_items", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/Enum_PreBuiltItemStatus" }, "notes": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "computedUnitPriceExGst": { "type": "number" }, "computedTotalQuantity": { "type": "integer" }, "totalQuantity": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemLineInput" } }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemDecorationInput" } } }, "required": [ "name" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "description": "example", "status": "draft", "notes": "example", "thumbnailUrl": "example", "tags": [ "example" ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PreBuiltItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/prebuilt-items' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"description\":\"example\",\"status\":\"draft\",\"notes\":\"example\",\"thumbnailUrl\":\"example\",\"tags\":[\"example\"]}'" } ] } }, "/v1/prebuilt-items/{itemId}": { "get": { "summary": "One pre-built item.", "operationId": "get_v1_prebuilt_items_itemId", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.read" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PreBuiltItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/prebuilt-items/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "put": { "summary": "Create or replace a pre-built item.", "operationId": "put_v1_prebuilt_items_itemId", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.write" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/Enum_PreBuiltItemStatus" }, "notes": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "computedUnitPriceExGst": { "type": "number" }, "computedTotalQuantity": { "type": "integer" }, "totalQuantity": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemLineInput" } }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SavePreBuiltItemDecorationInput" } } }, "required": [ "name" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "description": "example", "status": "draft", "notes": "example", "thumbnailUrl": "example", "tags": [ "example" ] } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PreBuiltItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PUT 'https://api.printools.io/v1/prebuilt-items/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"description\":\"example\",\"status\":\"draft\",\"notes\":\"example\",\"thumbnailUrl\":\"example\",\"tags\":[\"example\"]}'" } ] }, "delete": { "summary": "Delete a pre-built item.", "operationId": "delete_v1_prebuilt_items_itemId", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.write" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/prebuilt-items/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/prebuilt-items/bulk/delete": { "post": { "summary": "Delete every pre-built item matching a target.", "operationId": "post_v1_prebuilt_items_bulk_delete", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/prebuilt-items/bulk/delete' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/prebuilt-items/bulk/status": { "post": { "summary": "Set the status of every pre-built item matching a target.", "operationId": "post_v1_prebuilt_items_bulk_status", "tags": [ "prebuilt-items" ], "description": "Requires the scope prebuiltitems.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "prebuiltitems.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "status": { "$ref": "#/components/schemas/Enum_PreBuiltItemStatus" } }, "required": [ "status", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "status": "draft" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/prebuilt-items/bulk/status' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"status\":\"draft\"}'" } ] } }, "/v1/purchase-orders": { "get": { "summary": "List purchase orders.", "operationId": "get_v1_purchase_orders", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "includeInactive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Optional includeInactive filter." }, { "name": "jobId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional jobId filter." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "sentStatus", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Enum_POSentStatus" }, "description": "Optional sentStatus filter." }, { "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortDirection filter." }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional sortField filter." }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Enum_POStatus" }, "description": "Optional status filter." }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional vendorId filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrderPage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/purchase-orders' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a purchase order.", "operationId": "post_v1_purchase_orders", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "referenceNumber": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "deadline": { "type": "string", "format": "date" }, "taxRatePct": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_POStatus" }, "sentStatus": { "$ref": "#/components/schemas/Enum_POSentStatus" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "title": "example", "referenceNumber": "example", "jobId": "example", "quoteId": "example", "deadline": "2026-09-07" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"title\":\"example\",\"referenceNumber\":\"example\",\"jobId\":\"example\",\"quoteId\":\"example\",\"deadline\":\"2026-09-07\"}'" } ] } }, "/v1/purchase-orders/{purchaseOrderId}": { "get": { "summary": "One purchase order with its lines.", "operationId": "get_v1_purchase_orders_purchaseOrderId", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.read" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a purchase order.", "operationId": "patch_v1_purchase_orders_purchaseOrderId", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "referenceNumber": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "deadline": { "type": "string", "format": "date" }, "taxRatePct": { "type": "number" }, "status": { "$ref": "#/components/schemas/Enum_POStatus" }, "sentStatus": { "$ref": "#/components/schemas/Enum_POSentStatus" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "title": "example", "referenceNumber": "example", "jobId": "example", "quoteId": "example", "deadline": "2026-09-07" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"title\":\"example\",\"referenceNumber\":\"example\",\"jobId\":\"example\",\"quoteId\":\"example\",\"deadline\":\"2026-09-07\"}'" } ] } }, "/v1/jobs/{jobId}/purchase-orders": { "get": { "summary": "Every purchase order raised for a job.", "operationId": "get_v1_jobs_jobId_purchase_orders", "tags": [ "jobs" ], "description": "Requires ALL of the scopes purchaseorders.read, jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.read", "jobs.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/purchase-orders' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Raise purchase orders for a job, one per vendor.", "operationId": "post_v1_jobs_jobId_purchase_orders", "tags": [ "jobs" ], "description": "Requires ALL of the scopes purchaseorders.write, jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write", "jobs.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorIds": { "type": "array", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "vendorIds": [ "example" ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/purchase-orders' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"vendorIds\":[\"example\"]}'" } ] } }, "/v1/vendors/{vendorId}/purchase-orders": { "get": { "summary": "Every purchase order raised on a vendor.", "operationId": "get_v1_vendors_vendorId_purchase_orders", "tags": [ "vendors" ], "description": "Requires ALL of the scopes purchaseorders.read, vendors.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.read", "vendors.read" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555/purchase-orders' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/purchase-orders/{purchaseOrderId}/archive": { "post": { "summary": "Archive a purchase order.", "operationId": "post_v1_purchase_orders_purchaseOrderId_archive", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555/archive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/purchase-orders/{purchaseOrderId}/unarchive": { "post": { "summary": "Restore an archived purchase order.", "operationId": "post_v1_purchase_orders_purchaseOrderId_unarchive", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555/unarchive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/purchase-orders/{purchaseOrderId}/lines": { "post": { "summary": "Add a line to a purchase order.", "operationId": "post_v1_purchase_orders_purchaseOrderId_lines", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemType": { "$ref": "#/components/schemas/Enum_POLineItemType" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "colour": { "type": "string" }, "size": { "type": "string" }, "quantity": { "type": "integer" }, "rate": { "type": "number" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "itemType": "Product", "code": "example", "name": "example", "description": "example", "colour": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555/lines' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"itemType\":\"Product\",\"code\":\"example\",\"name\":\"example\",\"description\":\"example\",\"colour\":\"example\"}'" } ] } }, "/v1/purchase-order-lines/{lineId}": { "patch": { "summary": "Update a purchase-order line.", "operationId": "patch_v1_purchase_order_lines_lineId", "tags": [ "purchase-order-lines" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemType": { "$ref": "#/components/schemas/Enum_POLineItemType" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "colour": { "type": "string" }, "size": { "type": "string" }, "quantity": { "type": "integer" }, "rate": { "type": "number" }, "ordered": { "type": "boolean" }, "quantityOrdered": { "type": "integer" }, "quantityOnBackorder": { "type": "integer" }, "backorderDate": { "type": "string", "format": "date" }, "received": { "type": "boolean" }, "notes": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "itemType": "Product", "code": "example", "name": "example", "description": "example", "colour": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/purchase-order-lines/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"itemType\":\"Product\",\"code\":\"example\",\"name\":\"example\",\"description\":\"example\",\"colour\":\"example\"}'" } ] }, "delete": { "summary": "Delete a purchase-order line.", "operationId": "delete_v1_purchase_order_lines_lineId", "tags": [ "purchase-order-lines" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/purchase-order-lines/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/purchase-order-lines/{lineId}/receive": { "post": { "summary": "Record a receipt against a purchase-order line.", "operationId": "post_v1_purchase_order_lines_lineId_receive", "tags": [ "purchase-order-lines" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "lineId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ordered": { "type": "boolean" }, "quantityOrdered": { "type": "integer" }, "received": { "type": "boolean" }, "quantityOnBackorder": { "type": "integer" }, "backorderDate": { "type": "string", "format": "date" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "ordered": true, "quantityOrdered": 1, "received": true, "quantityOnBackorder": 1, "backorderDate": "2026-09-07" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-order-lines/11111111-2222-3333-4444-555555555555/receive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"ordered\":true,\"quantityOrdered\":1,\"received\":true,\"quantityOnBackorder\":1,\"backorderDate\":\"2026-09-07\"}'" } ] } }, "/v1/purchase-orders/{purchaseOrderId}/vendors/{vendorId}": { "post": { "summary": "Attach a vendor to a purchase order.", "operationId": "post_v1_purchase_orders_purchaseOrderId_vendors_vendorId", "tags": [ "purchase-orders" ], "description": "Requires ALL of the scopes purchaseorders.write, vendors.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write", "vendors.read" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555/vendors/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "delete": { "summary": "Detach a vendor from a purchase order.", "operationId": "delete_v1_purchase_orders_purchaseOrderId_vendors_vendorId", "tags": [ "purchase-orders" ], "description": "Requires ALL of the scopes purchaseorders.write, vendors.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write", "vendors.read" ], "parameters": [ { "name": "purchaseOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/purchase-orders/11111111-2222-3333-4444-555555555555/vendors/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/purchase-orders/bulk/receive": { "post": { "summary": "Receive every purchase-order line matching a target.", "operationId": "post_v1_purchase_orders_bulk_receive", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "mode": { "$ref": "#/components/schemas/Enum_BulkReceiveMode" } }, "required": [ "mode", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "mode": "receive_all" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/bulk/receive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"mode\":\"receive_all\"}'" } ] } }, "/v1/purchase-orders/bulk/status": { "post": { "summary": "Set the status of every purchase order matching a target. Derived statuses are refused — see GET /v1/reference/statuses.", "operationId": "post_v1_purchase_orders_bulk_status", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "status": { "$ref": "#/components/schemas/Enum_POStatus" } }, "required": [ "status", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "status": "Draft" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/bulk/status' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"status\":\"Draft\"}'" } ] } }, "/v1/purchase-orders/bulk/archive": { "post": { "summary": "Archive or restore every purchase order matching a target.", "operationId": "post_v1_purchase_orders_bulk_archive", "tags": [ "purchase-orders" ], "description": "Requires the scope purchaseorders.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "purchaseorders.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "archived": { "type": "boolean" } }, "required": [ "archived", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "archived": true } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/purchase-orders/bulk/archive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"archived\":true}'" } ] } }, "/v1/vendors": { "get": { "summary": "List vendors.", "operationId": "get_v1_vendors", "tags": [ "vendors" ], "description": "Requires the scope vendors.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "includeInactive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Optional includeInactive filter." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_VendorPage" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/vendors' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a vendor.", "operationId": "post_v1_vendors", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_VendorKind" }, "serviceTypes": { "type": "array", "items": { "$ref": "#/components/schemas/Enum_VendorServiceType" } }, "logoUrl": { "type": "string" }, "ordersWebsite": { "type": "string" }, "accountNumber": { "type": "string" }, "defaultLeadTimeDays": { "type": "integer" }, "minimumOrder": { "type": "number" }, "proximityNotes": { "type": "string" }, "notes": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "kind": "InventorySupplier", "serviceTypes": [ "ScreenPrint" ], "logoUrl": "example", "ordersWebsite": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Vendor" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/vendors' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"kind\":\"InventorySupplier\",\"serviceTypes\":[\"ScreenPrint\"],\"logoUrl\":\"example\",\"ordersWebsite\":\"example\"}'" } ] } }, "/v1/vendors/{vendorId}": { "get": { "summary": "One vendor with addresses and contacts.", "operationId": "get_v1_vendors_vendorId", "tags": [ "vendors" ], "description": "Requires the scope vendors.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.read" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Vendor" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a vendor.", "operationId": "patch_v1_vendors_vendorId", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Enum_VendorKind" }, "serviceTypes": { "type": "array", "items": { "$ref": "#/components/schemas/Enum_VendorServiceType" } }, "logoUrl": { "type": "string" }, "ordersWebsite": { "type": "string" }, "accountNumber": { "type": "string" }, "defaultLeadTimeDays": { "type": "integer" }, "minimumOrder": { "type": "number" }, "proximityNotes": { "type": "string" }, "notes": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "kind": "InventorySupplier", "serviceTypes": [ "ScreenPrint" ], "logoUrl": "example", "ordersWebsite": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Vendor" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"kind\":\"InventorySupplier\",\"serviceTypes\":[\"ScreenPrint\"],\"logoUrl\":\"example\",\"ordersWebsite\":\"example\"}'" } ] } }, "/v1/vendors/{vendorId}/archive": { "post": { "summary": "Archive a vendor.", "operationId": "post_v1_vendors_vendorId_archive", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Vendor" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555/archive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/vendors/{vendorId}/unarchive": { "post": { "summary": "Restore an archived vendor.", "operationId": "post_v1_vendors_vendorId_unarchive", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Vendor" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555/unarchive' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/vendors/{vendorId}/addresses": { "post": { "summary": "Add an address to a vendor.", "operationId": "post_v1_vendors_vendorId_addresses", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "label": "example", "street": "example", "city": "example", "state": "example", "postcode": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_VendorAddress" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555/addresses' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"label\":\"example\",\"street\":\"example\",\"city\":\"example\",\"state\":\"example\",\"postcode\":\"example\"}'" } ] } }, "/v1/vendor-addresses/{addressId}": { "patch": { "summary": "Update a vendor address.", "operationId": "patch_v1_vendor_addresses_addressId", "tags": [ "vendor-addresses" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "label": "example", "street": "example", "city": "example", "state": "example", "postcode": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_VendorAddress" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/vendor-addresses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"label\":\"example\",\"street\":\"example\",\"city\":\"example\",\"state\":\"example\",\"postcode\":\"example\"}'" } ] }, "delete": { "summary": "Delete a vendor address.", "operationId": "delete_v1_vendor_addresses_addressId", "tags": [ "vendor-addresses" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "addressId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/vendor-addresses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/vendors/{vendorId}/contacts": { "post": { "summary": "Add a contact to a vendor.", "operationId": "post_v1_vendors_vendorId_contacts", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "firstName": "example", "lastName": "example", "email": "example", "phone": "example", "role": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_VendorContact" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/vendors/11111111-2222-3333-4444-555555555555/contacts' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"firstName\":\"example\",\"lastName\":\"example\",\"email\":\"example\",\"phone\":\"example\",\"role\":\"example\"}'" } ] } }, "/v1/vendor-contacts/{contactId}": { "patch": { "summary": "Update a vendor contact.", "operationId": "patch_v1_vendor_contacts_contactId", "tags": [ "vendor-contacts" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "firstName": "example", "lastName": "example", "email": "example", "phone": "example", "role": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_VendorContact" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/vendor-contacts/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"firstName\":\"example\",\"lastName\":\"example\",\"email\":\"example\",\"phone\":\"example\",\"role\":\"example\"}'" } ] }, "delete": { "summary": "Delete a vendor contact.", "operationId": "delete_v1_vendor_contacts_contactId", "tags": [ "vendor-contacts" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/vendor-contacts/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/vendors/bulk/active": { "post": { "summary": "Activate or deactivate every vendor matching a target.", "operationId": "post_v1_vendors_bulk_active", "tags": [ "vendors" ], "description": "Requires the scope vendors.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "vendors.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "active": { "type": "boolean" } }, "required": [ "active", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "active": true } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/vendors/bulk/active' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"active\":true}'" } ] } }, "/v1/mocks": { "get": { "summary": "List mocks, filtered by job, quote or quote group. Not paginated.", "operationId": "get_v1_mocks", "tags": [ "mocks" ], "description": "Requires the scope proofs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.read" ], "parameters": [ { "name": "jobId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional jobId filter." }, { "name": "quoteGroupId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional quoteGroupId filter." }, { "name": "quoteId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional quoteId filter." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional status filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Mock" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/mocks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a mock.", "operationId": "post_v1_mocks", "tags": [ "mocks" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "quoteGroupId": { "type": "string" }, "quoteLineId": { "type": "string" }, "garmentAssetId": { "type": "string" }, "baseImageUrl": { "type": "string" }, "status": { "type": "string" }, "parentMockId": { "type": "string" }, "previewUrl": { "type": "string" }, "layers": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "jobId": "example", "quoteId": "example", "quoteGroupId": "example", "quoteLineId": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Mock" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/mocks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"jobId\":\"example\",\"quoteId\":\"example\",\"quoteGroupId\":\"example\",\"quoteLineId\":\"example\"}'" } ] } }, "/v1/mocks/{mockId}": { "get": { "summary": "One mock by id.", "operationId": "get_v1_mocks_mockId", "tags": [ "mocks" ], "description": "Requires the scope proofs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.read" ], "parameters": [ { "name": "mockId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Mock" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/mocks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a mock.", "operationId": "patch_v1_mocks_mockId", "tags": [ "mocks" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "mockId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "jobId": { "type": "string" }, "quoteId": { "type": "string" }, "quoteGroupId": { "type": "string" }, "quoteLineId": { "type": "string" }, "garmentAssetId": { "type": "string" }, "baseImageUrl": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "parentMockId": { "type": "string" }, "rejectionReason": { "type": "string" }, "previewUrl": { "type": "string" }, "layers": { "description": "Arbitrary JSON. Its structure is application-defined and is intentionally not presented as a closed object." } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "example", "jobId": "example", "quoteId": "example", "quoteGroupId": "example", "quoteLineId": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Mock" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/mocks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"example\",\"jobId\":\"example\",\"quoteId\":\"example\",\"quoteGroupId\":\"example\",\"quoteLineId\":\"example\"}'" } ] }, "delete": { "summary": "Delete a mock.", "operationId": "delete_v1_mocks_mockId", "tags": [ "mocks" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "mockId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/mocks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}/proofs": { "get": { "summary": "Every proof on a job.", "operationId": "get_v1_jobs_jobId_proofs", "tags": [ "jobs" ], "description": "Requires ALL of the scopes proofs.read, jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.read", "jobs.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Proof" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/proofs' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/proofs/{proofId}/history": { "get": { "summary": "One proof with its full revision history.", "operationId": "get_v1_proofs_proofId_history", "tags": [ "proofs" ], "description": "Requires the scope proofs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.read" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Proof" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555/history' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/proofs": { "post": { "summary": "Create a proof.", "operationId": "post_v1_proofs", "tags": [ "proofs" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobGroupId": { "type": "string" }, "jobGroupDecorationId": { "type": "string" }, "mockId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "optionLabel": { "type": "string" }, "imageUrl": { "type": "string" }, "imageFileName": { "type": "string" }, "sortOrder": { "type": "integer" }, "placementSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofPlacementSpecInput" } }, "itemLinks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofItemLinkInput" } } }, "required": [ "jobId", "title" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "jobId": "example", "jobGroupId": "example", "jobGroupDecorationId": "example", "mockId": "example", "title": "example", "description": "example", "optionLabel": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Proof" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proofs' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"jobId\":\"example\",\"jobGroupId\":\"example\",\"jobGroupDecorationId\":\"example\",\"mockId\":\"example\",\"title\":\"example\",\"description\":\"example\",\"optionLabel\":\"example\"}'" } ] } }, "/v1/proofs/{proofId}": { "patch": { "summary": "Update a proof.", "operationId": "patch_v1_proofs_proofId", "tags": [ "proofs" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "optionLabel": { "type": "string" }, "imageUrl": { "type": "string" }, "imageFileName": { "type": "string" }, "sortOrder": { "type": "integer" }, "placementSpecs": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofPlacementSpecInput" }, "description": "Replace-on-write when provided; omitted = untouched." }, "itemLinks": { "type": "array", "items": { "$ref": "#/components/schemas/Input_ProofItemLinkInput" }, "description": "Replace-on-write when provided (splits reset to unconfirmed); omitted = untouched." } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "title": "example", "description": "example", "optionLabel": "example", "imageUrl": "example", "imageFileName": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Proof" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"title\":\"example\",\"description\":\"example\",\"optionLabel\":\"example\",\"imageUrl\":\"example\",\"imageFileName\":\"example\"}'" } ] }, "delete": { "summary": "Delete a proof.", "operationId": "delete_v1_proofs_proofId", "tags": [ "proofs" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/proofs/{proofId}/send": { "post": { "summary": "Email a proof to the customer.", "operationId": "post_v1_proofs_proofId_send", "tags": [ "proofs" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toEmail": { "type": "string" } }, "required": [ "toEmail" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "toEmail": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Proof" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555/send' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"toEmail\":\"example\"}'" } ] } }, "/v1/proofs/send": { "post": { "summary": "Email several proofs in one message.", "operationId": "post_v1_proofs_send", "tags": [ "proofs" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "toEmail": { "type": "string" } }, "required": [ "ids", "toEmail" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "ids": [ "example" ], "toEmail": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Proof" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proofs/send' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"ids\":[\"example\"],\"toEmail\":\"example\"}'" } ] } }, "/v1/proofs/{proofId}/revise": { "post": { "summary": "Open a new revision of a proof.", "operationId": "post_v1_proofs_proofId_revise", "tags": [ "proofs" ], "description": "Requires the scope proofs.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.write" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Proof" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555/revise' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/proofs/{proofId}/status": { "post": { "summary": "Set a proof status directly, including approved.", "operationId": "post_v1_proofs_proofId_status", "tags": [ "proofs" ], "description": "Requires the scope proofs.approve.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.approve" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Enum_ProofStatus" }, "approvedByName": { "type": "string" }, "rejectionReason": { "type": "string" } }, "required": [ "status" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "status": "Draft", "approvedByName": "example", "rejectionReason": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Proof" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555/status' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"status\":\"Draft\",\"approvedByName\":\"example\",\"rejectionReason\":\"example\"}'" } ] } }, "/v1/proofs/{proofId}/client-decision": { "post": { "summary": "Record the client’s decision on a proof.", "operationId": "post_v1_proofs_proofId_client_decision", "tags": [ "proofs" ], "description": "Requires the scope proofs.approve.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.approve" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "$ref": "#/components/schemas/Enum_ProofClientDecision" }, "byName": { "type": "string" }, "clientNotes": { "type": "string" } }, "required": [ "decision" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "decision": "Approved", "byName": "example", "clientNotes": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Proof" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proofs/11111111-2222-3333-4444-555555555555/client-decision' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"decision\":\"Approved\",\"byName\":\"example\",\"clientNotes\":\"example\"}'" } ] } }, "/v1/proof-item-links/{proofItemLinkId}/size-split": { "post": { "summary": "Confirm the size split on a proof item.", "operationId": "post_v1_proof_item_links_proofItemLinkId_size_split", "tags": [ "proof-item-links" ], "description": "Requires the scope proofs.approve.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "proofs.approve" ], "parameters": [ { "name": "proofItemLinkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sizeSplit": { "type": "array", "items": { "$ref": "#/components/schemas/Input_SizeQtyInput" } } }, "required": [ "sizeSplit" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "sizeSplit": [ { "size": "example", "qty": 1 } ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_ProofItemLink" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/proof-item-links/11111111-2222-3333-4444-555555555555/size-split' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"sizeSplit\":[{\"size\":\"example\",\"qty\":1}]}'" } ] } }, "/v1/jobs/{jobId}/tasks": { "get": { "summary": "Every production task on a job.", "operationId": "get_v1_jobs_jobId_tasks", "tags": [ "jobs" ], "description": "Requires ALL of the scopes tasks.read, jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.read", "jobs.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_ProductionTask" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/tasks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/tasks/by-assignee": { "get": { "summary": "Production tasks assigned to one person.", "operationId": "get_v1_tasks_by_assignee", "tags": [ "tasks" ], "description": "Requires the scope tasks.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based row offset." }, { "name": "assigneeEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional assigneeEmail filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_MyProductionTask" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/tasks/by-assignee' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/tasks/{taskId}/extras": { "get": { "summary": "A task’s comments, checklist and attachments.", "operationId": "get_v1_tasks_taskId_extras", "tags": [ "tasks" ], "description": "Requires the scope tasks.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.read" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_TaskExtras" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/tasks/11111111-2222-3333-4444-555555555555/extras' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/tasks": { "post": { "summary": "Create a production task.", "operationId": "post_v1_tasks", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "$ref": "#/components/schemas/Enum_TaskCategory" }, "decorationMethod": { "type": "string" }, "assignedToEmail": { "type": "string" }, "assignedToName": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "jobGroupDecorationId": { "type": "string" }, "decorationItemId": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "jobId", "title" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "jobId": "example", "title": "example", "description": "example", "category": "Artwork", "decorationMethod": "example", "assignedToEmail": "example", "assignedToName": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_ProductionTask" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/tasks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"jobId\":\"example\",\"title\":\"example\",\"description\":\"example\",\"category\":\"Artwork\",\"decorationMethod\":\"example\",\"assignedToEmail\":\"example\",\"assignedToName\":\"example\"}'" } ] } }, "/v1/tasks/{taskId}": { "patch": { "summary": "Update a production task.", "operationId": "patch_v1_tasks_taskId", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "category": { "$ref": "#/components/schemas/Enum_TaskCategory" }, "decorationMethod": { "type": "string" }, "status": { "type": "string" }, "assignedToEmail": { "type": "string" }, "assignedToName": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "attachmentUrl": { "type": "string" }, "attachmentFileName": { "type": "string" }, "sortOrder": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "title": "example", "description": "example", "category": "Artwork", "decorationMethod": "example", "status": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_ProductionTask" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/tasks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"title\":\"example\",\"description\":\"example\",\"category\":\"Artwork\",\"decorationMethod\":\"example\",\"status\":\"example\"}'" } ] }, "delete": { "summary": "Delete a production task.", "operationId": "delete_v1_tasks_taskId", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/tasks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/tasks/bulk/update": { "post": { "summary": "Patch every production task matching a target.", "operationId": "post_v1_tasks_bulk_update", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" }, "input": { "$ref": "#/components/schemas/Input_BulkTaskPatchInput" } }, "required": [ "input", "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] }, "input": { "status": "example", "assignedToEmail": "example", "assignedToName": "example", "dueDate": "2026-09-07" } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/tasks/bulk/update' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]},\"input\":{\"status\":\"example\",\"assignedToEmail\":\"example\",\"assignedToName\":\"example\",\"dueDate\":\"2026-09-07\"}}'" } ] } }, "/v1/tasks/bulk/delete": { "post": { "summary": "Delete every production task matching a target.", "operationId": "post_v1_tasks_bulk_delete", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Input_BulkTargetInput" } }, "required": [ "target" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "target": { "ids": [ "11111111-2222-3333-4444-555555555555" ], "filters": [ { "field": "example", "op": "example", "value": "example", "values": [ "example" ], "from": "example", "to": "example" } ], "search": "example", "excludeIds": [ "11111111-2222-3333-4444-555555555555" ] } } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_BulkResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/tasks/bulk/delete' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"target\":{\"ids\":[\"11111111-2222-3333-4444-555555555555\"],\"filters\":[{\"field\":\"example\",\"op\":\"example\",\"value\":\"example\",\"values\":[\"example\"],\"from\":\"example\",\"to\":\"example\"}],\"search\":\"example\",\"excludeIds\":[\"11111111-2222-3333-4444-555555555555\"]}}'" } ] } }, "/v1/tasks/{taskId}/comments": { "post": { "summary": "Comment on a production task.", "operationId": "post_v1_tasks_taskId_comments", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "body": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobTaskComment" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/tasks/11111111-2222-3333-4444-555555555555/comments' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"body\":\"example\"}'" } ] } }, "/v1/task-comments/{commentId}": { "patch": { "summary": "Edit a task comment.", "operationId": "patch_v1_task_comments_commentId", "tags": [ "task-comments" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "body": "example" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobTaskComment" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/task-comments/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"body\":\"example\"}'" } ] }, "delete": { "summary": "Delete a task comment.", "operationId": "delete_v1_task_comments_commentId", "tags": [ "task-comments" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/task-comments/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/tasks/{taskId}/checklist": { "post": { "summary": "Add a checklist item to a task.", "operationId": "post_v1_tasks_taskId_checklist", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "position": { "type": "integer" } }, "required": [ "text" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "text": "example", "position": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobTaskChecklistItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/tasks/11111111-2222-3333-4444-555555555555/checklist' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"text\":\"example\",\"position\":1}'" } ] } }, "/v1/task-checklist-items/{itemId}": { "patch": { "summary": "Update a checklist item.", "operationId": "patch_v1_task_checklist_items_itemId", "tags": [ "task-checklist-items" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "completed": { "type": "boolean" }, "position": { "type": "integer" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "text": "example", "completed": true, "position": 1 } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobTaskChecklistItem" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/task-checklist-items/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"text\":\"example\",\"completed\":true,\"position\":1}'" } ] }, "delete": { "summary": "Delete a checklist item.", "operationId": "delete_v1_task_checklist_items_itemId", "tags": [ "task-checklist-items" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/task-checklist-items/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/tasks/{taskId}/attachments": { "post": { "summary": "Attach a file to a task.", "operationId": "post_v1_tasks_taskId_attachments", "tags": [ "tasks" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileUrl": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" } }, "required": [ "fileUrl", "filename" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "fileUrl": "example", "filename": "example", "mimeType": "example", "sizeBytes": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_JobTaskAttachment" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/tasks/11111111-2222-3333-4444-555555555555/attachments' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"fileUrl\":\"example\",\"filename\":\"example\",\"mimeType\":\"example\",\"sizeBytes\":1}'" } ] } }, "/v1/task-attachments/{attachmentId}": { "delete": { "summary": "Remove a task attachment.", "operationId": "delete_v1_task_attachments_attachmentId", "tags": [ "task-attachments" ], "description": "Requires the scope tasks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "tasks.write" ], "parameters": [ { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/task-attachments/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}/pdf": { "get": { "summary": "A presigned link to the quote PDF. Expires in 900 seconds.", "operationId": "get_v1_quotes_quoteId_pdf", "tags": [ "quotes" ], "description": "Requires ALL of the scopes documents.read, quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "documents.read", "quotes.read" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PdfExport" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/pdf' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/invoices/{invoiceId}/pdf": { "get": { "summary": "A presigned link to the invoice PDF. Expires in 900 seconds.", "operationId": "get_v1_invoices_invoiceId_pdf", "tags": [ "invoices" ], "description": "Requires ALL of the scopes documents.read, invoices.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "documents.read", "invoices.read" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_PdfExport" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/pdf' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/media/upload-url": { "post": { "summary": "Mint a presigned PUT for an upload. Expires in 900 seconds.", "operationId": "post_v1_media_upload_url", "tags": [ "media" ], "description": "Requires the scope media.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "media.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "contentType": { "type": "string" }, "contentLength": { "type": "integer", "description": "Size of the file in bytes. Optional for now — omitting it keeps the old\nbehaviour, where nothing bounds how much the presigned PUT may carry. When\nsupplied it is checked against the per-type cap (25 MB image / 100 MB pdf)\nAND pinned into the signature, so the upload is rejected by S3 unless its\nContent-Length matches exactly. Send it whenever the size is known." } }, "required": [ "kind", "contentType" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "kind": "example", "contentType": "example", "contentLength": 1 } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_MediaUploadTarget" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/media/upload-url' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"kind\":\"example\",\"contentType\":\"example\",\"contentLength\":1}'" } ] } }, "/v1/invoices/{invoiceId}": { "get": { "summary": "One invoice.", "operationId": "get_v1_invoices_invoiceId", "tags": [ "invoices" ], "description": "Requires the scope invoices.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.read" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}/invoices": { "get": { "summary": "Every invoice raised against a quote.", "operationId": "get_v1_quotes_quoteId_invoices", "tags": [ "quotes" ], "description": "Requires ALL of the scopes invoices.read, quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.read", "quotes.read" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Invoice" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/invoices' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}/invoice": { "post": { "summary": "Generate an invoice from a quote.", "operationId": "post_v1_quotes_quoteId_invoice", "tags": [ "quotes" ], "description": "Requires ALL of the scopes invoices.write, quotes.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.write", "quotes.read" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/invoice' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/invoices/{invoiceId}/send": { "post": { "summary": "Email an invoice to the customer.", "operationId": "post_v1_invoices_invoiceId_send", "tags": [ "invoices" ], "description": "Requires the scope invoices.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.write" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Parity with SendQuoteInput (F-29). Send Invoice is now the Send Quote flow — a\nReview step then a Compose & Send step with `{{tokens}}` and a live preview — so\nthe operator composes a subject and can copy themselves, exactly as on a quote.\nThe field names differ from the quote's (`toEmail` vs `emailTo`) only because\nthis input shipped first; renaming it would break every deployed client.", "properties": { "toEmail": { "type": "string" }, "emailSubject": { "type": "string", "description": "Operator-composed subject. Omitted or blank → the server default,\n`Invoice {ref}`, which is what every send used before F-29." }, "emailBodyMarkdown": { "type": "string", "description": "The WHOLE email body as Markdown, with `{{tokens}}` already resolved by the\nclient — the same contract as `SendQuoteInput.emailBodyMarkdown`. When set,\nthe server composes nothing: no invoice summary block is prepended." }, "ccSelfEmail": { "type": "string", "description": "Copy the sending rep, as on a quote." }, "message": { "type": "string", "description": "A note PREPENDED to a server-composed summary (ref, amount due, due date, pay\nlink). Kept working for clients that predate F-29." } }, "required": [ "toEmail" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "toEmail": "example", "emailSubject": "example", "emailBodyMarkdown": "example", "ccSelfEmail": "example", "message": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/send' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"toEmail\":\"example\",\"emailSubject\":\"example\",\"emailBodyMarkdown\":\"example\",\"ccSelfEmail\":\"example\",\"message\":\"example\"}'" } ] } }, "/v1/invoices/{invoiceId}/mark-paid": { "post": { "summary": "Record an invoice as paid.", "operationId": "post_v1_invoices_invoiceId_mark_paid", "tags": [ "invoices" ], "description": "Requires the scope invoices.settle.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.settle" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "description": "bank_transfer | cash | card | other (pinch payments record themselves)." }, "reference": { "type": "string", "description": "Bank/receipt reference for the audit trail." }, "paidAt": { "type": "string", "format": "date-time", "description": "When the payment landed; defaults to now." } }, "required": [ "method" ] }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "method": "example", "reference": "example", "paidAt": "2026-09-07T12:00:00.000Z" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/mark-paid' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"method\":\"example\",\"reference\":\"example\",\"paidAt\":\"2026-09-07T12:00:00.000Z\"}'" } ] } }, "/v1/invoices/{invoiceId}/unmark-paid": { "post": { "summary": "Undo a paid marking.", "operationId": "post_v1_invoices_invoiceId_unmark_paid", "tags": [ "invoices" ], "description": "Requires the scope invoices.settle.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.settle" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "reason": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/unmark-paid' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"reason\":\"example\"}'" } ] } }, "/v1/invoices/{invoiceId}/void": { "post": { "summary": "Void an invoice.", "operationId": "post_v1_invoices_invoiceId_void", "tags": [ "invoices" ], "description": "Requires the scope invoices.settle.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.settle" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why it was voided — surfaced on the invoice and in the audit trail." } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "reason": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/void' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"reason\":\"example\"}'" } ] } }, "/v1/invoices/{invoiceId}/refund": { "post": { "summary": "Refund an invoice.", "operationId": "post_v1_invoices_invoiceId_refund", "tags": [ "invoices" ], "description": "Requires the scope invoices.settle.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.settle" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "integer", "description": "Cents; omit for a full refund. Must not exceed the invoice total." }, "reason": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "amountCents": 1, "reason": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/refund' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"amountCents\":1,\"reason\":\"example\"}'" } ] } }, "/v1/invoices/{invoiceId}/dismiss-claim": { "post": { "summary": "Dismiss a customer’s payment claim.", "operationId": "post_v1_invoices_invoiceId_dismiss_claim", "tags": [ "invoices" ], "description": "Requires the scope invoices.settle.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.settle" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "reason": "example" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_Invoice" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/dismiss-claim' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"reason\":\"example\"}'" } ] } }, "/v1/invoices/{invoiceId}/push/xero": { "post": { "summary": "Push an invoice into the shop’s Xero connection.", "operationId": "post_v1_invoices_invoiceId_push_xero", "tags": [ "invoices" ], "description": "Requires the scope invoices.sync.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.sync" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_XeroInvoicePushResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/push/xero' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/invoices/{invoiceId}/push/quickbooks": { "post": { "summary": "Push an invoice into the shop’s QuickBooks connection.", "operationId": "post_v1_invoices_invoiceId_push_quickbooks", "tags": [ "invoices" ], "description": "Requires the scope invoices.sync.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "invoices.sync" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "201": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Output_QuickBooksInvoicePushResult" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/invoices/11111111-2222-3333-4444-555555555555/push/quickbooks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/custom-fields": { "get": { "summary": "List custom field definitions.", "operationId": "get_v1_custom_fields", "tags": [ "custom-fields" ], "description": "Requires the scope customfields.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customfields.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Local_CustomField" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/custom-fields' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a custom field definition.", "operationId": "post_v1_custom_fields", "tags": [ "custom-fields" ], "description": "Requires the scope customfields.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customfields.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Local_CreateCustomField" }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "Artwork approval", "type": "select", "options": [ "Pending", "Approved" ] } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_CustomField" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/custom-fields' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"Artwork approval\",\"type\":\"select\",\"options\":[\"Pending\",\"Approved\"]}'" } ] } }, "/v1/custom-fields/{fieldId}": { "get": { "summary": "One custom field definition.", "operationId": "get_v1_custom_fields_fieldId", "tags": [ "custom-fields" ], "description": "Requires the scope customfields.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customfields.read" ], "parameters": [ { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_CustomField" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/custom-fields/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a custom field definition.", "operationId": "patch_v1_custom_fields_fieldId", "tags": [ "custom-fields" ], "description": "Requires the scope customfields.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customfields.write" ], "parameters": [ { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Local_UpdateCustomField" }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "name": "Artwork approval" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_CustomField" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/custom-fields/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"name\":\"Artwork approval\"}'" } ] }, "delete": { "summary": "Delete a custom field definition.", "operationId": "delete_v1_custom_fields_fieldId", "tags": [ "custom-fields" ], "description": "Requires the scope customfields.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customfields.write" ], "parameters": [ { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_DeletedResource" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/custom-fields/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/custom-statuses": { "get": { "summary": "List custom status definitions.", "operationId": "get_v1_custom_statuses", "tags": [ "custom-statuses" ], "description": "Requires the scope customstatuses.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customstatuses.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Local_CustomStatus" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/custom-statuses' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Create a custom status definition.", "operationId": "post_v1_custom_statuses", "tags": [ "custom-statuses" ], "description": "Requires the scope customstatuses.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customstatuses.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Local_CreateCustomStatus" }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "kind": "job", "value": "In production", "palette": "active" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_CustomStatus" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/custom-statuses' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"kind\":\"job\",\"value\":\"In production\",\"palette\":\"active\"}'" } ] } }, "/v1/custom-statuses/{statusId}": { "get": { "summary": "One custom status definition.", "operationId": "get_v1_custom_statuses_statusId", "tags": [ "custom-statuses" ], "description": "Requires the scope customstatuses.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customstatuses.read" ], "parameters": [ { "name": "statusId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_CustomStatus" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/custom-statuses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "patch": { "summary": "Update a custom status definition.", "operationId": "patch_v1_custom_statuses_statusId", "tags": [ "custom-statuses" ], "description": "Requires the scope customstatuses.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customstatuses.write" ], "parameters": [ { "name": "statusId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Local_UpdateCustomStatus" }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "value": "In production" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_CustomStatus" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request PATCH 'https://api.printools.io/v1/custom-statuses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"value\":\"In production\"}'" } ] }, "delete": { "summary": "Delete a custom status definition. Refuses with 409 when an automation rule targets it.", "operationId": "delete_v1_custom_statuses_statusId", "tags": [ "custom-statuses" ], "description": "Requires the scope customstatuses.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customstatuses.write" ], "parameters": [ { "name": "statusId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_DeletedResource" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/custom-statuses/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/webhooks": { "get": { "summary": "List this credential’s webhook subscriptions.", "operationId": "get_v1_webhooks", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.read" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Local_WebhookSubscription" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/webhooks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "post": { "summary": "Subscribe to an event. Returns the signing secret ONCE. Re-subscribing the same event and URL is idempotent.", "operationId": "post_v1_webhooks", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.write" ], "parameters": [ { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Local_CreateWebhook" }, "examples": { "example": { "summary": "Replace example values with a request for your shop.", "value": { "event": "quote.sent", "targetUrl": "https://example.com/hooks/printools" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_WebhookCreated" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/webhooks' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\"event\":\"quote.sent\",\"targetUrl\":\"https://example.com/hooks/printools\"}'" } ] } }, "/v1/webhooks/{webhookId}": { "get": { "summary": "One webhook subscription.", "operationId": "get_v1_webhooks_webhookId", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.read" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_WebhookSubscription" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/webhooks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] }, "delete": { "summary": "Unsubscribe. Idempotent — deleting an unknown subscription still succeeds.", "operationId": "delete_v1_webhooks_webhookId", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.write" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_DeletedResource" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request DELETE 'https://api.printools.io/v1/webhooks/11111111-2222-3333-4444-555555555555' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/webhooks/{webhookId}/rotate-secret": { "post": { "summary": "Rotate the signing secret. The old one keeps verifying for 48 hours so you can deploy without dropping payloads.", "operationId": "post_v1_webhooks_webhookId_rotate_secret", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.write" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_WebhookSecretRotation" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/webhooks/11111111-2222-3333-4444-555555555555/rotate-secret' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/webhooks/{webhookId}/deliveries": { "get": { "summary": "Delivery history for a subscription, with a failure reason you can act on. Never a response body.", "operationId": "get_v1_webhooks_webhookId_deliveries", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.read" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Local_WebhookDelivery" } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/webhooks/11111111-2222-3333-4444-555555555555/deliveries' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/webhooks/{webhookId}/deliveries/{deliveryId}/retry": { "post": { "summary": "Replay a failed delivery. Without this, an hour of downtime means those events are gone for good.", "operationId": "post_v1_webhooks_webhookId_deliveries_deliveryId_retry", "tags": [ "webhooks" ], "description": "Requires the scope webhooks.write.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "webhooks.write" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional client-generated key for write retries. Reusing it with a different request returns 409; a replay includes Idempotency-Replayed: true." } ], "responses": { "200": { "description": "Successful response.", "headers": { "Idempotency-Replayed": { "description": "Present and true when this response was replayed from a prior Idempotency-Key request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Local_WebhookRetry" } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request POST 'https://api.printools.io/v1/webhooks/11111111-2222-3333-4444-555555555555/deliveries/11111111-2222-3333-4444-555555555555/retry' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/catalogue": { "get": { "summary": "The shop’s whole catalogue in one call — their own items and the supplier catalogue, variants inline. Cursor-paged; ?source=manual|ascolour.", "operationId": "get_v1_catalogue", "tags": [ "catalogue" ], "description": "Requires ALL of the scopes garments.read, decorations.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "garments.read", "decorations.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Requested page size. The service applies its current maximum (200); read GET /v1/reference/limits rather than hard-code it." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional cursor filter." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "manual", "ascolour" ] }, "description": "Optional source filter." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "items", "totalCount", "source" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentCatalogueItem" } }, { "type": "object", "required": [ "variants" ], "properties": { "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Output_GarmentVariant" } } } } ] } }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "nextCursor": { "type": "string" }, "source": { "type": "string", "enum": [ "all", "manual", "ascolour" ] } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/catalogue' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/quotes/{quoteId}/data": { "get": { "summary": "One quote and everything hanging off it, in one call.", "operationId": "get_v1_quotes_quoteId_data", "tags": [ "quotes" ], "description": "Requires ALL of the scopes quotes.read, customers.read, garments.read, decorations.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "quotes.read", "customers.read", "garments.read", "decorations.read" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "quote", "customer", "mocks", "invoices" ], "properties": { "quote": { "$ref": "#/components/schemas/Output_Quote" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/Output_Customer" }, { "type": "null" } ] }, "mocks": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Mock" } }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Invoice" } } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/quotes/11111111-2222-3333-4444-555555555555/data' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/jobs/{jobId}/data": { "get": { "summary": "One job and everything hanging off it, in one call.", "operationId": "get_v1_jobs_jobId_data", "tags": [ "jobs" ], "description": "Requires ALL of the scopes jobs.read, customers.read, garments.read, decorations.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "jobs.read", "customers.read", "garments.read", "decorations.read" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "job", "customer", "tasks", "proofs", "purchaseOrders" ], "properties": { "job": { "$ref": "#/components/schemas/Output_Job" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/Output_Customer" }, { "type": "null" } ] }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Output_ProductionTask" } }, "proofs": { "type": "array", "items": { "$ref": "#/components/schemas/Output_Proof" } }, "purchaseOrders": { "type": "array", "items": { "$ref": "#/components/schemas/Output_PurchaseOrder" } } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/jobs/11111111-2222-3333-4444-555555555555/data' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } }, "/v1/customers/{customerId}/data": { "get": { "summary": "One customer with their quotes and jobs, in one call.", "operationId": "get_v1_customers_customerId_data", "tags": [ "customers" ], "description": "Requires ALL of the scopes customers.read, quotes.read, jobs.read.", "security": [ { "tenantApiKey": [] }, { "partnerApiKey": [], "partnerApiSecret": [], "partnerBearer": [] } ], "x-printools-required-scopes": [ "customers.read", "quotes.read", "jobs.read" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "description": "UUID." }, { "name": "X-PrintTools-Organization-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Tenant credential: optional and, when sent, must equal the shop bound to the key. Partner credential: required; it selects an organisation the user previously authorised." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "customer", "quotes", "jobs", "note" ], "properties": { "customer": { "$ref": "#/components/schemas/Output_Customer" }, "quotes": { "$ref": "#/components/schemas/Output_QuotePage" }, "jobs": { "$ref": "#/components/schemas/Output_JobPage" }, "note": { "type": "string" } } } } } ] } } } }, "400": { "description": "Validation or request-shape error. Correct the request before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string", "example": "ApiKey" } } } }, "403": { "description": "The credential lacks a required scope, or its actor lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource or endpoint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, including idempotency-key reuse or an in-flight idempotent request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the published size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Retry after the returned delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds to wait.", "schema": { "type": "integer", "minimum": 0 } } } }, "500": { "description": "An unexpected server error. A retry can be appropriate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Tenant credential", "source": "curl --request GET 'https://api.printools.io/v1/customers/11111111-2222-3333-4444-555555555555/data' \\\n --header 'X-API-Key: $PRINTOOLS_API_KEY'" } ] } } } }