Every API here is available over the APIs.io API and to AI agents over MCP.
{
"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)"
},
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://artifacts.apis.io/hoplix-com/openapi/_original/hoplix-com-v1-openapi.json