{ "openapi": "3.1.0", "info": { "title": "Hoplix Print-on-Demand API", "version": "1.1.0", "summary": "Catalog, campaigns and orders of the Hoplix print-on-demand platform.", "description": "REST API of Hoplix, an Italian print-on-demand and dropshipping platform: read the catalog of 230+ blank products, create campaigns with your designs, place orders that Hoplix prints and ships worldwide, and track them.\n\n**Authentication**: every request is a `POST` with a JSON body that contains your `api` key and `secret` key (Account > Settings > Api Key on hoplix.com). There is no header-based authentication.\n\n**Responses**: the HTTP status is 200; the JSON field `status` is `200` on success and `201` on error, with a `message`.\n\n**Test mode** (v1.1): add `\"test\": true` to the order endpoints to try your integration without creating, paying or shipping a real order.\n\nAn official MCP server for AI assistants is also available at https://api.hoplix.com/mcp (see https://hoplix.com/en/mcp-integration).", "contact": { "name": "Hoplix SRL", "url": "https://hoplix.com/en/contacts", "email": "info@hoplix.com" }, "termsOfService": "https://hoplix.com/en/terms-and-conditions", "x-logo": { "url": "https://raw.githubusercontent.com/hoplix/hoplix-print-on-demand-mcp/main/assets/logo-400.png" } }, "externalDocs": { "description": "Human-readable documentation with PHP examples", "url": "https://hoplix.com/api/v1/documentation" }, "servers": [ { "url": "https://api.hoplix.com", "description": "Production" } ], "tags": [ { "name": "Products", "description": "Blank products of the Hoplix catalog" }, { "name": "Campaigns", "description": "Your designs applied to one or more products" }, { "name": "Orders", "description": "Orders printed and shipped by Hoplix" } ], "paths": { "/v1/product-list": { "post": { "tags": [ "Products" ], "operationId": "listProducts", "summary": "List all products", "description": "All blank products available on Hoplix with colors, sizes, base cost (front print and front+back print) and production days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "product-list": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/product-info/{product-code}": { "post": { "tags": [ "Products" ], "operationId": "getProduct", "summary": "Get a product", "description": "One product plus the additional products that can be added to a campaign built on it.", "parameters": [ { "name": "product-code", "in": "path", "required": true, "description": "Catalog product code", "schema": { "type": "string" }, "example": "maglietta-unisex" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "product-info": { "$ref": "#/components/schemas/Product" }, "additional-product": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "requested": { "type": "string" } } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/create-campaign": { "post": { "tags": [ "Campaigns" ], "operationId": "createCampaign", "summary": "Create a campaign", "description": "Creates a campaign from design image URLs on a main product, optionally with additional products. Selling prices must be greater than the base cost.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/CampaignInput" } }, "required": [ "campaign" ] } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY", "campaign": { "name": "My first campaign", "description": "Summer collection", "url": "my-first-campaign", "private": "n", "campaign-duration": "0", "front": "https://example.com/design.png", "currency": "EUR", "product-code": "maglietta-unisex", "product-color": "white,black", "product-price": "24.90" } } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "campaign_id": { "type": "string" }, "link": { "type": "string", "description": "Public page, only for non-private campaigns" } } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/info-campaign/{campaign-id}": { "post": { "tags": [ "Campaigns" ], "operationId": "getCampaign", "summary": "Get a campaign", "description": "Campaign details with its products, selling prices, colors, sizes and preview images. The product-id values are used to create orders.", "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "description": "Campaign id", "schema": { "type": "string" }, "example": "00608240" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "campaign": { "$ref": "#/components/schemas/Campaign" } } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/list-campaign": { "post": { "tags": [ "Campaigns" ], "operationId": "listCampaigns", "summary": "List your campaigns", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CampaignSummary" } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/create-order": { "post": { "tags": [ "Orders" ], "operationId": "createOrder", "summary": "Create an order", "description": "Orders products of your campaigns. Without `payment-method` the order uses credit card and can be paid from your Hoplix account. Supports test mode.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "test": { "type": "boolean", "description": "Test mode: the request is fully validated but nothing is produced, charged or shipped. Test order ids look like TEST-A1B2C3D4E5 and are kept for 30 days." }, "order": { "$ref": "#/components/schemas/OrderInput" } }, "required": [ "order" ] } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY", "test": true, "order": { "products": [ { "campaign-id": "00608240", "product-id": "1333789", "product-color": "white", "product-size": "M", "quantity": 1 } ], "shipping-mode": "economy", "order_reference": "MY-ORDER-1", "shipping-info": { "name": "Mario", "surname": "Rossi", "address": "Via Roma 1", "address-more": "", "zip-code": "20121", "city": "Milano", "province": "MI", "country-code": "IT" } } } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderCreated" }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "status": 200, "order-id": "TEST-A1B2C3D4E5", "total": "29.27", "shipping-cost": "6.48", "paymentStatus": "test", "test": true } } } } } } }, "/v1/create-campaign-order": { "post": { "tags": [ "Orders" ], "operationId": "createCampaignOrder", "summary": "Create a campaign and an order in one call", "description": "Creates the campaign from the design URLs given for each product, then the order. In test mode the request is validated but no campaign is created, so total and shipping-cost are null.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "test": { "type": "boolean", "description": "Test mode: the request is fully validated but nothing is produced, charged or shipped. Test order ids look like TEST-A1B2C3D4E5 and are kept for 30 days." }, "order": { "allOf": [ { "$ref": "#/components/schemas/OrderInput" }, { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/DesignOrderItem" } } } } ] } }, "required": [ "order" ] } ] } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderCreated" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/status-order/{order-id}": { "post": { "tags": [ "Orders" ], "operationId": "getOrderStatus", "summary": "Get order status and tracking", "parameters": [ { "name": "order-id", "in": "path", "required": true, "description": "Hoplix order id, or a TEST-... id", "schema": { "type": "string" }, "example": "TEST-A1B2C3D4E5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderStatus" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/status-order-reference": { "post": { "tags": [ "Orders" ], "operationId": "getOrderStatusByReference", "summary": "Get order status by your reference", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "order-ref": { "type": "string", "description": "Your own order reference (order_reference given at creation)" }, "test": { "type": "boolean", "description": "Test mode: the request is fully validated but nothing is produced, charged or shipped. Test order ids look like TEST-A1B2C3D4E5 and are kept for 30 days." } }, "required": [ "order-ref" ] } ] } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderStatus" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/list-orders": { "post": { "tags": [ "Orders" ], "operationId": "listOrders", "summary": "List your orders", "description": "Your real orders; with `\"test\": true` your test orders.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "test": { "type": "boolean", "description": "Test mode: the request is fully validated but nothing is produced, charged or shipped. Test order ids look like TEST-A1B2C3D4E5 and are kept for 30 days." } } } ] } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "order-list": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatus" } } } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/order-info/{order-id}": { "post": { "tags": [ "Orders" ], "operationId": "getOrder", "summary": "Get order details", "parameters": [ { "name": "order-id", "in": "path", "required": true, "description": "Hoplix order id, or a TEST-... id", "schema": { "type": "string" }, "example": "TEST-A1B2C3D4E5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "order-info": { "type": "array", "items": { "$ref": "#/components/schemas/OrderInfo" } } } }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/v1/status-order-list": { "post": { "tags": [ "Orders" ], "operationId": "listOrderStatuses", "summary": "List the possible order statuses", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "an", "ri", "pe", "pro", "ok", "co", "sm" ] }, "meaning": { "type": "string" } } } }, { "$ref": "#/components/schemas/Error" } ] }, "example": [ { "status": "pe", "meaning": "pending" }, { "status": "ok", "meaning": "shipped" } ] } } } } } }, "/v1/cancel-order/{order-id}": { "post": { "tags": [ "Orders" ], "operationId": "cancelOrder", "summary": "Cancel an order", "description": "Cancels an order that has not been paid yet, or was paid with wallet less than 2 hours ago. Works with test orders.", "parameters": [ { "name": "order-id", "in": "path", "required": true, "description": "Hoplix order id, or a TEST-... id", "schema": { "type": "string" }, "example": "TEST-A1B2C3D4E5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Credentials" } ] }, "example": { "api": "YOUR API KEY", "secret": "YOUR SECRET KEY" } } } }, "responses": { "200": { "description": "Request processed. Check the `status` field: 200 = success, 201 = error with `message`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "const": 200 }, "message": { "type": "string" }, "test": { "type": "boolean" } } }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "status": 200, "message": "Order Successfully Canceled" } } } } } } } }, "components": { "schemas": { "Credentials": { "type": "object", "required": [ "api", "secret" ], "description": "Sent in every request body.", "properties": { "api": { "type": "string", "description": "Your API Key" }, "secret": { "type": "string", "description": "Your Secret Key", "format": "password" } } }, "Error": { "type": "object", "properties": { "status": { "const": 201 }, "message": { "type": "string", "examples": [ "Authentication required" ] } } }, "Product": { "type": "object", "properties": { "product-code": { "type": "string", "examples": [ "maglietta-unisex" ] }, "name": { "type": "string" }, "colors": { "type": "string", "description": "Comma-separated color codes" }, "description": { "type": "string" }, "sizes": { "type": "string", "description": "Comma-separated sizes" }, "base-cost": { "type": "string", "description": "Base cost in EUR, front print" }, "base-cost-back": { "type": "string", "description": "Base cost in EUR, front and back print" }, "production days": { "type": "string" }, "printable-area": { "type": "string" }, "orientation": { "type": "string", "description": "2 = front and back printable" }, "weight": { "type": "string", "description": "Grams" } } }, "CampaignInput": { "type": "object", "required": [ "name", "product-code", "product-color", "product-price" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "Slug of the public page; letters, digits and hyphens, must be unused" }, "private": { "type": "string", "description": "y = private campaign, n = public", "enum": [ "y", "n" ] }, "oneshot": { "type": "string", "description": "on = deleted 90 days after creation" }, "campaign-duration": { "type": "string", "description": "End date yyyy-mm-dd hh:ii:ss, or 0 for no end" }, "front": { "type": "string", "description": "URL of the front design (PNG or JPG)" }, "back": { "type": "string", "description": "URL of the back design" }, "insidelabel": { "type": "string", "description": "URL of the inside label design" }, "currency": { "type": "string", "enum": [ "EUR" ] }, "product-code": { "type": "string", "description": "Main product" }, "product-color": { "type": "string", "description": "Comma-separated colors of the main product" }, "product-price": { "type": "string", "description": "Selling price, greater than the base cost" }, "additional-product": { "type": "array", "items": { "type": "object", "properties": { "product-code": { "type": "string" }, "product-color": { "type": "string" }, "product-price": { "type": "string" } } } } } }, "Campaign": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "private": { "type": "string" }, "campaign-duration": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product-id": { "type": "string", "description": "Use it in create-order" }, "product-name": { "type": "string" }, "product-code": { "type": "string" }, "product-price": { "type": "string" }, "product-color": { "type": "string" }, "product-size": { "type": "string" }, "preview": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "CampaignSummary": { "type": "object", "properties": { "id_campaign": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "Creation Date": { "type": "string" }, "Initial Date": { "type": "string" }, "End Date": { "type": "string" }, "status": { "type": "string" }, "view": { "type": "string" }, "campaign products": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" }, "colors": { "type": "string" } } } } } }, "ShippingInfo": { "type": "object", "required": [ "name", "surname", "address", "zip-code", "city", "country-code" ], "properties": { "name": { "type": "string" }, "surname": { "type": "string" }, "address": { "type": "string" }, "address-more": { "type": "string" }, "zip-code": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string", "description": "Province code, required for Italy (e.g. MI)" }, "country-code": { "type": "string", "description": "ISO 3166-1 alpha-2", "examples": [ "IT" ] } } }, "OrderItem": { "type": "object", "required": [ "campaign-id", "product-id", "product-color", "product-size", "quantity" ], "properties": { "campaign-id": { "type": "string" }, "product-id": { "type": "string", "description": "From info-campaign" }, "product-color": { "type": "string" }, "product-size": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } } }, "DesignOrderItem": { "type": "object", "required": [ "product-code", "product-color", "product-size", "quantity" ], "properties": { "product-code": { "type": "string" }, "front": { "type": "string", "description": "Front design URL" }, "back": { "type": "string", "description": "Back design URL" }, "insidelabel": { "type": "string" }, "product-color": { "type": "string" }, "product-size": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } } }, "OrderInput": { "type": "object", "required": [ "products", "shipping-mode", "shipping-info" ], "properties": { "products": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/OrderItem" } }, "shipping-mode": { "type": "string", "description": "fob = collection by your own courier", "enum": [ "economy", "tracked", "express", "fob" ] }, "order_reference": { "type": "string", "description": "Your own order reference; duplicates are refused" }, "payment-method": { "type": "string", "description": "Default credit-card", "enum": [ "credit-card", "wallet" ] }, "client-email": { "type": "string", "description": "Address that receives the tracking e-mail" }, "shipping-info": { "$ref": "#/components/schemas/ShippingInfo" } } }, "OrderCreated": { "type": "object", "properties": { "status": { "const": 200 }, "order-id": { "type": "string" }, "total": { "type": "string" }, "shipping-cost": { "type": "string" }, "paymentStatus": { "type": "string" }, "test": { "type": "boolean" } } }, "OrderStatus": { "type": "object", "properties": { "status": { "const": 200 }, "order-id": { "type": "string" }, "order-status": { "type": "string" }, "shipping-code": { "type": "string" }, "tracking-url": { "type": "string" }, "test": { "type": "boolean" } } }, "OrderInfo": { "type": "object", "properties": { "order-id": { "type": "string" }, "your-order-number": { "type": "string" }, "order-date": { "type": "string" }, "type": { "type": "string" }, "order-status": { "type": "string" }, "shipping-cost": { "type": "string" }, "shipping-code": { "type": "string" }, "tracking-url": { "type": "string" }, "product-order": { "type": "array", "items": { "type": "object", "properties": { "campaign-id": { "type": "string" }, "product-code": { "type": "string" }, "product-name": { "type": "string" }, "size": { "type": "string" }, "color": { "type": "string" }, "quantity": { "type": "string" }, "unit-price": { "type": "string" }, "total-price": { "type": "string" } } } } } } } } }