{ "openapi": "3.0.0", "info": { "title": "Dodgeprint Public API", "description": "RESTful API for seamless e-commerce platform integration. Enables automated product deployment, inventory management, and order fulfillment across major marketplaces including Etsy, Amazon, TikTok Shop, and Shopify. Supports versioned endpoints (v1, v2) for backward compatibility and progressive feature adoption.", "contact": { "name": "Dodgeprint Support", "email": "support@dodgeprint.com" }, "license": { "name": "Proprietary", "url": "https://dodgeprint.com/terms" }, "version": "2.0.0" }, "servers": [ { "url": "https://api.dodgeprint.com/api", "description": "Production API Server" } ], "paths": { "/api/v1/ledgers/{site_id}/transactions": { "get": { "tags": [ "Ledger Transactions" ], "summary": "List ledger transactions for a site", "description": "Retrieves paginated ledger transactions (Etsy or Shopify) for the specified site, with filtering and sorting support.", "operationId": "d26be27d17448be95eb4aa7a8ea0ad4a", "parameters": [ { "name": "site_id", "in": "path", "description": "Site ID", "required": true, "schema": { "type": "integer", "example": 6361 } }, { "name": "X-Workspace-ID", "in": "header", "description": "Workspace ID", "required": true, "schema": { "type": "integer", "example": 359 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "example": 10 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "q", "in": "query", "description": "Search by description or ledger type", "required": false, "schema": { "type": "string" } }, { "name": "ledger_type", "in": "query", "description": "Filter by ledger type code", "required": false, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "Date range (comma-separated, e.g. 01/01/2025,31/01/2025)", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "example": "sequence_number" } }, { "name": "sort_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "site_id": { "type": "integer" }, "entry_id": { "type": "integer" }, "ledger_id": { "type": "integer" }, "amount": { "type": "number", "format": "float" }, "balance": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "create_date": { "type": "string" }, "description": { "type": "string" }, "ledger_type": { "type": "string" }, "reference_id": { "type": "string" }, "reference_type": { "type": "string" }, "sequence_number": { "type": "integer" }, "receipt_id": { "type": "string", "nullable": true }, "group_ledger_type": { "type": "string" }, "listing_id": { "type": "string", "nullable": true }, "etsy_ledger_type": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "group_type": { "type": "string" }, "group_type_name": { "type": "string" }, "etsy_type": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing token" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/ledgers/types": { "get": { "tags": [ "Ledger Transactions" ], "summary": "List all Etsy ledger types", "description": "Retrieves a list of all available Etsy ledger types with their group and classification details.", "operationId": "7cf24ced7021a67c2cfe1546bd75f287", "parameters": [ { "name": "X-Workspace-ID", "in": "header", "description": "Workspace ID", "required": true, "schema": { "type": "integer", "example": 359 } } ], "responses": { "200": { "description": "Ledger types retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "code": { "type": "string", "example": "prolist" }, "name": { "type": "string", "example": "Etsy Ads" }, "description": { "type": "string", "example": "Etsy Ads" }, "group_type": { "type": "string", "example": "etsy_ads_fees" }, "group_type_name": { "type": "string", "example": "Etsy Ads Fees" }, "etsy_type": { "type": "string", "example": "Marketing" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing token" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/categories/deployable": { "get": { "tags": [ "Categories" ], "summary": "Get deployable categories for product deployment", "description": "Returns a flat list of **leaf categories only** (categories without children) that can be used for deploying products to marketplace platforms.\n *\n * **Use Case:** Use this endpoint to find the correct category_id when deploying products via `/v2/deploy-products`.\n *\n * **Key Features:**\n * - **Only returns leaf categories** - categories that can be used for product deployment\n * - Optimized for product deployment workflows\n * - Returns flat list with pagination (no nested tree structure)\n * - Includes full category path for context\n * - Fast performance with eager loading to avoid N+1 queries\n * - Supports search and filtering\n *\n * **Important Notes:**\n * - This API **always returns leaf categories only** (is_leaf=1) - you cannot change this behavior\n * - Parent categories (categories with children) cannot be used for product deployment\n * - Different platforms have different category structures\n * - The `is_leaf` field in response is calculated dynamically based on whether the category has children\n * - Use the `category_id` field when creating products via deploy API\n * - **platform_id is REQUIRED** - API will return 400 error if not provided", "operationId": "getDeployableCategories", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "platform_id", "in": "query", "description": "**Required**. Platform ID to filter categories", "required": true, "schema": { "description": "1=Etsy, 4=TikTok, 5=Amazon", "type": "integer", "enum": [ 1, 4, 5 ], "example": 1 } }, { "name": "search", "in": "query", "description": "Search categories by name (case-insensitive partial match)", "required": false, "schema": { "type": "string", "example": "T-Shirt" } }, { "name": "parent_id", "in": "query", "description": "Filter by parent category ID to get subcategories", "required": false, "schema": { "type": "integer", "example": 123 } }, { "name": "limit", "in": "query", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "default": 20, "example": 20 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "example": 1 } } ], "responses": { "200": { "description": "Deployable categories retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Array of deployable categories", "type": "array", "items": { "properties": { "id": { "description": "Category ID - Use this for deploy-products API", "type": "integer", "example": 2197 }, "name": { "description": "Category name", "type": "string", "example": "T-Shirts" }, "taxonomy_id": { "description": "Platform-specific taxonomy ID", "type": "string", "example": "1027" }, "platform_id": { "description": "Platform: 1=Etsy, 4=TikTok, 5=Amazon", "type": "integer", "example": 1 }, "origin_id": { "description": "Original platform category ID", "type": "string", "example": null, "nullable": true }, "parent_id": { "description": "Parent category ID", "type": "integer", "example": 123, "nullable": true }, "is_leaf": { "description": "1=Leaf category (deployable), 0=Parent category", "type": "integer", "example": 1 }, "category_path": { "description": "Full category hierarchy path", "type": "string", "example": "Clothing > Men's Clothing > T-Shirts" } }, "type": "object" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of categories", "type": "integer", "example": 2610 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 20 }, "per_page": { "description": "Results per page", "type": "integer", "example": 20 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 131 }, "links": { "description": "Pagination navigation links", "properties": { "next": { "description": "URL to next page (null if last page)", "type": "string", "example": "https://api.dodgeprint.com/api/v1/categories/deployable?page=2", "nullable": true } }, "type": "object" } }, "type": "object" }, "meta": { "description": "Additional metadata (currently empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - platform_id is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "platform_id is required" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contents": { "get": { "tags": [ "Content Templates" ], "summary": "List content templates", "description": "Get content templates with titles, descriptions, and images for product deployments. These templates are used in the 'content_id' parameter when deploying products via POST /deploy-product.", "operationId": "listContents", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "name", "in": "query", "description": "Filter by content name (partial match)", "required": false, "schema": { "type": "string", "example": "T-Shirt" } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer", "example": 1635986 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Contents retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Content ID - Use as 'content_id' in POST /deploy-product", "type": "integer", "example": 3968 }, "name": { "type": "string", "example": "Demo content template" }, "resource_share": { "description": "Workspace resource sharing information", "properties": { "resourceable_id": { "type": "integer", "example": 3968 }, "total_users": { "type": "integer", "example": 1 }, "top_users": { "description": "List of users with access", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "VN" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } } }, "type": "object" }, "created_by": { "description": "Creator information", "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "VN" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 3 }, "count": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 2 }, "links": { "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/contents?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Content Templates" ], "summary": "Create content template", "description": "Create a new content template with name and HTML content. This template can then be used when deploying products by referencing its ID in the 'content_id' parameter.", "operationId": "createContent", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Content template data", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "content" ], "properties": { "name": { "description": "Content template name (for your reference)", "type": "string", "example": "Premium Canvas Art Description" }, "content": { "description": "HTML content body for product description. Supports HTML tags for formatting.", "type": "string", "example": "

Premium Canvas Print

Transform your space with our high-quality canvas prints.

" } }, "type": "object" } } } }, "responses": { "200": { "description": "Content template created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Created successfully" }, "data": { "description": "Empty array", "type": "array", "items": {} } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "The name field is required." } }, "content": { "type": "array", "items": { "type": "string", "example": "The content field is required." } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/contents/{id}": { "get": { "tags": [ "Content Templates" ], "summary": "Get content template details", "description": "Get complete content template with name and HTML content body. The 'content' field contains the HTML description used for product listings.", "operationId": "getContentDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Content template ID", "required": true, "schema": { "type": "integer", "example": 2414 } } ], "responses": { "200": { "description": "Content template retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 2414 }, "name": { "type": "string", "example": "Dev Canvas Template" }, "content": { "description": "HTML content body for product description", "type": "string", "example": "

Beautiful canvas print with premium quality. Perfect for home decoration.

" }, "created_by": { "description": "Creator information", "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Content template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Content Templates" ], "summary": "Update content template", "description": "Update an existing content template's name and/or HTML content body.", "operationId": "updateContent", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Content template ID", "required": true, "schema": { "type": "integer", "example": 2414 } } ], "requestBody": { "description": "Content template update data", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "content" ], "properties": { "name": { "description": "Content template name", "type": "string", "example": "Updated Canvas Art Description" }, "content": { "description": "HTML content body for product description", "type": "string", "example": "

Premium Canvas Print - Updated

New description with enhanced details.

" } }, "type": "object" } } } }, "responses": { "200": { "description": "Content template updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string" } }, "content": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Content template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Content Templates" ], "summary": "Delete content template", "description": "Delete a content template. **Warning**: This action cannot be undone. Make sure the content template is not being used in any active product deployments before deleting.", "operationId": "deleteContent", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Content template ID to delete", "required": true, "schema": { "type": "integer", "example": 2414 } } ], "responses": { "200": { "description": "Content template deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Content template not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Content template not found" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to delete this content template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/personalizations": { "get": { "tags": [ "Personalizations" ], "summary": "List personalization templates", "description": "Get personalization templates for Etsy products (optional configuration). Allows customers to add custom text or requests.", "operationId": "listPersonalizations", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Personalizations retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Array of personalization templates", "type": "array", "items": { "properties": { "id": { "description": "Personalization ID - Use in Deploy API", "type": "integer", "example": 1824 }, "name": { "description": "Personalization template name", "type": "string", "example": "Custom Text Option" }, "personalization_instructions": { "description": "Instructions for customers", "type": "string", "example": "Please provide your custom text", "nullable": true }, "personalization_char_count_max": { "description": "Maximum character count allowed", "type": "integer", "example": 256 }, "personalization_is_required": { "description": "Whether personalization is required (1=yes, 0=no)", "type": "integer", "example": 1 }, "is_active": { "description": "Active status (1=active, 0=inactive)", "type": "integer", "example": 1 }, "created_by": { "description": "User who created this template", "properties": { "id": { "type": "integer", "example": 10062 }, "email": { "type": "string", "example": "user@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" }, "resource_share": { "description": "Workspace resource sharing information", "properties": { "resourceable_id": { "type": "integer", "example": 1824 }, "total_users": { "type": "integer", "example": 1 }, "top_users": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10062 }, "email": { "type": "string", "example": "user@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of personalizations", "type": "integer", "example": 1 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 1 }, "per_page": { "description": "Results per page", "type": "integer", "example": 10 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 1 }, "links": { "description": "Pagination navigation links (empty array if no additional pages)", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "meta": { "description": "Additional metadata (currently empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Personalizations" ], "summary": "Create personalization template", "description": "Create a new personalization template for Etsy products. Allows customers to add custom text or special requests.", "operationId": "createPersonalization", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Personalization template configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Personalization template name (required, must be unique)", "type": "string", "example": "Custom Name Option" }, "personalization_instructions": { "description": "Instructions for customers (optional)", "type": "string", "example": "Please provide your custom text here", "nullable": true }, "personalization_char_count_max": { "description": "Maximum character count allowed (optional, default: 256)", "type": "integer", "example": 256 }, "personalization_is_required": { "description": "Whether personalization is mandatory for purchase (optional, default: true)", "type": "boolean", "example": true }, "is_active": { "description": "Active status (optional, default: true)", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Personalization created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Created successfully" }, "data": { "description": "Empty array on successful creation", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - name already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "[Custom Name Option] is already existed." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/personalizations/{id}": { "get": { "tags": [ "Personalizations" ], "summary": "Get personalization template details", "description": "Get complete personalization template configuration including instructions and requirements.", "operationId": "getPersonalizationDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Personalization ID", "required": true, "schema": { "type": "integer", "example": 1824 } } ], "responses": { "200": { "description": "Personalization retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Personalization template details", "properties": { "id": { "description": "Personalization ID", "type": "integer", "example": 1824 }, "name": { "description": "Template name", "type": "string", "example": "Custom Text Option" }, "personalization_instructions": { "description": "Instructions for customers", "type": "string", "example": "Please provide your custom text", "nullable": true }, "personalization_char_count_max": { "description": "Maximum character count allowed", "type": "integer", "example": 256 }, "personalization_is_required": { "description": "Whether personalization is required (1=yes, 0=no)", "type": "integer", "example": 1 }, "is_active": { "description": "Active status (1=active, 0=inactive)", "type": "integer", "example": 1 }, "created_by": { "description": "User who created this template", "properties": { "id": { "type": "integer", "example": 10062 }, "email": { "type": "string", "example": "user@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Personalization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Personalizations" ], "summary": "Update personalization template", "description": "Update an existing personalization template's configuration. All fields are optional.", "operationId": "updatePersonalization", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Personalization ID", "required": true, "schema": { "type": "integer", "example": 1824 } } ], "requestBody": { "description": "Personalization update data", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Template name (optional, must be unique)", "type": "string", "example": "Updated Template Name" }, "personalization_instructions": { "description": "Instructions for customers (optional)", "type": "string", "example": "Updated instructions for customers", "nullable": true }, "personalization_char_count_max": { "description": "Maximum character count allowed (optional, default: 256)", "type": "integer", "example": 100 }, "personalization_is_required": { "description": "Whether personalization is mandatory (optional, default: true)", "type": "boolean", "example": true }, "is_active": { "description": "Active status (optional, default: true)", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Personalization updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "description": "Empty array on successful update", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - name already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "[Updated Template Name] is already existed." } }, "type": "object" } } } }, "404": { "description": "Personalization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Personalizations" ], "summary": "Delete personalization template", "description": "Delete a personalization template. This will not affect products already deployed with this template.", "operationId": "deletePersonalization", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Personalization ID", "required": true, "schema": { "type": "integer", "example": 1824 } } ], "responses": { "200": { "description": "Personalization deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "description": "Empty array on successful deletion", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Personalization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/processing-profiles": { "get": { "tags": [ "Processing Profiles" ], "summary": "List processing profiles", "description": "Get all processing time profiles for an Etsy shop. Returns profiles from database if available, otherwise fetches from Etsy API. The 'source' field indicates data origin (database or api).", "operationId": "listProcessingProfiles", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "site_id", "in": "query", "description": "Etsy site ID", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "responses": { "200": { "description": "Processing profiles retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "source": { "description": "Data source: database (cached) or api (fresh from Etsy)", "type": "string", "enum": [ "database", "api" ], "example": "database" }, "processing_profiles": { "type": "array", "items": { "properties": { "readiness_state_id": { "description": "Etsy readiness state ID", "type": "string", "example": "1742858595" }, "readiness_state": { "type": "string", "example": "made_to_order" }, "min_processing_days": { "type": "integer", "example": 1 }, "max_processing_days": { "type": "integer", "example": 3 }, "processing_time_unit": { "type": "string", "example": "days" }, "is_default": { "description": "Whether this is the default profile", "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Site ID is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Site ID is required" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Processing Profiles" ], "summary": "Create processing profile", "description": "Create a new processing time profile for Etsy shop. Defines how long products take to make (ready_to_ship or made_to_order with 1-10 days/weeks). Only one profile can be set as default. After creation, system automatically syncs with Etsy API to ensure database consistency.", "operationId": "createProcessingProfile", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "site_id", "readiness_state", "min_processing_time", "max_processing_time" ], "properties": { "site_id": { "description": "Etsy site ID (must be active Etsy site)", "type": "integer", "example": 6529 }, "readiness_state": { "description": "Product readiness type: ready_to_ship (no processing) or made_to_order (requires processing time)", "type": "string", "enum": [ "ready_to_ship", "made_to_order" ], "example": "made_to_order" }, "min_processing_time": { "description": "Minimum processing time (1-10)", "type": "integer", "maximum": 10, "minimum": 1, "example": 1 }, "max_processing_time": { "description": "Maximum processing time (1-10)", "type": "integer", "maximum": 10, "minimum": 1, "example": 3 }, "processing_time_unit": { "description": "Time unit (optional, default: days)", "type": "string", "enum": [ "days", "weeks" ], "example": "days" }, "is_default": { "description": "Set as default profile (optional, default: false). Only one profile can be default.", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Processing profile created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "message": { "type": "string", "example": "Processing profile created successfully" }, "processing_profile": { "properties": { "readiness_state_id": { "description": "Etsy readiness state ID", "type": "string", "example": "1742858595" }, "readiness_state": { "type": "string", "example": "made_to_order" }, "min_processing_days": { "description": "Note: response uses 'days' instead of 'time'", "type": "integer", "example": 1 }, "max_processing_days": { "type": "integer", "example": 3 }, "processing_time_unit": { "type": "string", "example": "days" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or site not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Site ID is required" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/processing-profiles/{id}": { "get": { "tags": [ "Processing Profiles" ], "summary": "Get processing profile detail", "description": "Get details of a specific processing profile by readiness_state_id", "operationId": "getProcessingProfileDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Readiness state ID (from Etsy)", "required": true, "schema": { "type": "string", "example": "1742858595" } }, { "name": "site_id", "in": "query", "description": "Etsy site ID", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "responses": { "200": { "description": "Processing profile details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "processing_profile": { "properties": { "readiness_state_id": { "type": "string", "example": "1742858595" }, "readiness_state": { "type": "string", "example": "made_to_order" }, "min_processing_days": { "type": "integer", "example": 1 }, "max_processing_days": { "type": "integer", "example": 3 }, "processing_time_unit": { "type": "string", "example": "days" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Processing profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Processing profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Processing Profiles" ], "summary": "Update processing profile", "description": "Update an existing processing profile. Send only fields you want to update. Smart update: if only is_default changes, skips Etsy API call and updates database only. Otherwise updates both Etsy and database.", "operationId": "updateProcessingProfile", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Readiness state ID (from Etsy)", "required": true, "schema": { "type": "string", "example": "1742858595" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "site_id" ], "properties": { "site_id": { "description": "Etsy site ID", "type": "integer", "example": 6529 }, "readiness_state": { "description": "Product readiness type (optional)", "type": "string", "enum": [ "ready_to_ship", "made_to_order" ], "example": "made_to_order" }, "min_processing_time": { "description": "Minimum processing time (optional)", "type": "integer", "maximum": 10, "minimum": 1, "example": 2 }, "max_processing_time": { "description": "Maximum processing time (optional)", "type": "integer", "maximum": 10, "minimum": 1, "example": 5 }, "processing_time_unit": { "description": "Time unit (optional)", "type": "string", "enum": [ "days", "weeks" ], "example": "days" }, "is_default": { "description": "Set as default profile (optional). Unsets other defaults.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Processing profile updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "message": { "type": "string", "example": "Processing profile updated successfully" }, "processing_profile": { "properties": { "readiness_state_id": { "type": "string", "example": "1742858595" }, "readiness_state": { "type": "string", "example": "made_to_order" }, "min_processing_days": { "type": "integer", "example": 2 }, "max_processing_days": { "type": "integer", "example": 5 }, "processing_time_unit": { "type": "string", "example": "days" }, "is_default": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Processing profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Processing profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Processing Profiles" ], "summary": "Delete processing profile", "description": "Delete a processing profile from Etsy shop. Removes from both Etsy API and local database.", "operationId": "deleteProcessingProfile", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Readiness state ID (from Etsy)", "required": true, "schema": { "type": "string", "example": "1742858595" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "site_id" ], "properties": { "site_id": { "description": "Etsy site ID", "type": "integer", "example": 6529 } }, "type": "object" } } } }, "responses": { "200": { "description": "Processing profile deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "message": { "type": "string", "example": "Processing profile deleted successfully" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Processing profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Processing profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/processing-profiles/sync": { "post": { "tags": [ "Processing Profiles" ], "summary": "Manually sync processing profiles from Etsy", "description": "Manually trigger a sync of processing time profiles from Etsy API to the local database. This ensures you have the latest processing profiles from your Etsy shop.", "operationId": "syncProcessingProfiles", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "site_id" ], "properties": { "site_id": { "description": "Etsy site ID to sync processing profiles for", "type": "integer", "example": 6529 } }, "type": "object" } } } }, "responses": { "200": { "description": "Processing profiles synced successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "message": { "type": "string", "example": "Processing profiles synced successfully" }, "synced_count": { "description": "Number of profiles synced", "type": "integer", "example": 3 }, "processing_profiles": { "type": "array", "items": { "properties": { "readiness_state_id": { "description": "Etsy readiness state ID", "type": "string", "example": "1742858595" }, "readiness_state": { "type": "string", "example": "made_to_order" }, "min_processing_days": { "type": "integer", "example": 1 }, "max_processing_days": { "type": "integer", "example": 3 }, "processing_days_display_label": { "type": "string", "example": "1-3 business days" }, "is_default": { "description": "Whether this is the default profile", "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Site not found or no profiles found after sync", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Active Etsy site not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 422 }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "site_id": { "type": "array", "items": { "type": "string", "example": "The site id field is required." } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Failed to sync processing profiles", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "Failed to sync processing profiles from Etsy" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/product-type/{id}": { "get": { "tags": [ "Product Types" ], "summary": "Get product type details", "description": "Get detailed information about a specific product type, including required attributes and Amazon specifications. Product type details are essential for proper product deployment on Amazon.", "operationId": "getProductTypeDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Product type ID", "required": true, "schema": { "type": "integer", "example": 123 } } ], "responses": { "200": { "description": "Product type retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "description": "Product type ID", "type": "integer", "example": 123 }, "name": { "type": "string", "example": "T-Shirts" }, "code": { "description": "Amazon product type code", "type": "string", "example": "SHIRT" }, "platform_id": { "description": "Platform: 3=Amazon", "type": "integer", "example": 3 }, "description": { "type": "string", "example": "T-Shirts and Tank Tops", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "attributes": { "description": "Required and optional attributes for this product type", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 201 }, "name": { "type": "string", "example": "Brand Name" }, "code": { "type": "string", "example": "brand" }, "required": { "type": "boolean", "example": true }, "data_type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "Brand of the product", "nullable": true } }, "type": "object" } }, "created_at": { "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-01-20 14:20:30" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product type not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/product-type": { "get": { "tags": [ "Product Types" ], "summary": "List product types", "description": "Get product types primarily used for Amazon deployments. Product types define required attributes and specifications for different product categories on Amazon. Optional for POST /group-variants (product_type_id).", "operationId": "listProductTypes", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "platform_id", "in": "query", "description": "Filter by platform (5=Amazon)", "required": false, "schema": { "type": "integer", "example": 5 } }, { "name": "search", "in": "query", "description": "Search by product type name or code", "required": false, "schema": { "type": "string", "example": "T-Shirt" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Product types retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Product type ID - Use in POST /group-variants (product_type_id) for Amazon products", "type": "integer", "example": 1 }, "platform_id": { "description": "Platform: 5=Amazon", "type": "integer", "example": 5 }, "name": { "type": "string", "example": "SHIRT" }, "code": { "description": "Amazon product type code", "type": "string", "example": "SHIRT" } }, "type": "object" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of product types", "type": "integer", "example": 2 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 2 }, "per_page": { "description": "Results per page (default: 15)", "type": "integer", "example": 15 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 1 }, "links": { "description": "Pagination links (empty array if single page)", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sites/{site_id}/products": { "post": { "tags": [ "Products" ], "summary": "Create product", "description": "Create a new product in your source site with support for both JSON and file uploads. The product is created immediately (not queued). Supports duplicate detection and automatic restoration of soft-deleted products. **Important:** Only source sites (is_destination=0) can create products - use GET /sites?is_destination=0 to find your source sites.\n *\n * **Large File Upload Workflow:**\n * For files larger than 10MB or to prevent timeout issues with large files, use this two-step process:\n * 1. Upload files: `POST /upload-temporary-file` (with `files[]` in multipart form-data, `group=manual-create-product`)\n * 2. Create product: `POST /sites/{site_id}/products` (use returned file paths in `image_file_paths[]`, `video_file_path`, `digital_file_paths[]`)\n *\n * This approach prevents timeout issues and allows for better error handling. Files are uploaded to temporary storage first, then moved to permanent storage when the product is created.", "operationId": "createProduct", "parameters": [ { "name": "site_id", "in": "path", "description": "Source site ID - Must be a source site (not destination). Use GET /sites?is_destination=0 to get list of source sites.", "required": true, "schema": { "type": "integer", "example": 5018 } }, { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Product data - supports both JSON and multipart/form-data", "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Product name/title", "type": "string", "maxLength": 255, "example": "Premium Cotton T-Shirt" }, "images": { "description": "Product image URLs (HTTPS only). At least one image required (via images or image_files). First image will be main image.", "type": "array", "items": { "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/products/tshirt-front.jpg" } }, "digital_files": { "description": "Digital file URLs for downloadable products (HTTPS only)", "type": "array", "items": { "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/files/digital-product.pdf" }, "nullable": true }, "videos": { "description": "Product video URLs (HTTPS only)", "type": "array", "items": { "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/videos/product-demo.mp4" }, "nullable": true }, "sku_origin": { "description": "Product SKU for duplicate detection. If a product with same sku_origin and site_id exists: throws error if active, restores if soft-deleted.", "type": "string", "maxLength": 255, "example": "TSHIRT-001", "nullable": true }, "category": { "description": "Product category name", "type": "string", "maxLength": 100, "example": "Clothing", "nullable": true }, "tags": { "description": "Product tags for searchability", "type": "array", "items": { "type": "string", "maxLength": 50, "example": "cotton" }, "nullable": true }, "description": { "description": "Product description", "type": "string", "maxLength": 2000, "example": "Premium quality cotton t-shirt with comfortable fit", "nullable": true }, "price": { "description": "Product price", "type": "number", "format": "float", "minimum": 0, "example": 29.99, "nullable": true }, "materials": { "description": "Product materials", "type": "string", "maxLength": 500, "example": "100% Cotton", "nullable": true }, "image_file_paths": { "description": "File paths from upload-temporary-file API (alternative to direct upload or URLs). For large files (>10MB), upload via POST /upload-temporary-file first, then use returned paths here. This prevents timeout issues.", "type": "array", "items": { "type": "string", "example": "concordart/tmp/manual-create-product/359/223/image-uuid.jpg" }, "nullable": true }, "video_file_path": { "description": "Video file path from upload-temporary-file API (alternative to video URL)", "type": "string", "example": "concordart/tmp/manual-create-product/359/223/video-uuid.mp4", "nullable": true }, "digital_file_paths": { "description": "Digital file paths from upload-temporary-file API (alternative to digital_files URLs)", "type": "array", "items": { "type": "string", "example": "concordart/tmp/manual-create-product/359/223/digital-uuid.pdf" }, "nullable": true }, "design_file_path": { "description": "Main design file path from upload-temporary-file API (required if design_position_file_paths or design_position_urls provided)", "type": "string", "example": "concordart/tmp/manual-create-product/359/223/design-main-uuid.png", "nullable": true }, "design_url": { "description": "Main design file URL (alternative to design_file_path, HTTPS only)", "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/designs/main-design.png", "nullable": true }, "design_position_file_paths": { "description": "Position/mockup file paths from upload-temporary-file API (max 10). Requires main design file.", "type": "array", "items": { "type": "string", "example": "concordart/tmp/manual-create-product/359/223/position-1-uuid.png" }, "nullable": true }, "design_position_urls": { "description": "Position/mockup file URLs (max 10, HTTPS only). Requires main design file.", "type": "array", "items": { "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/designs/position-1.png" }, "nullable": true }, "design_name": { "description": "Design name (defaults to product name if not provided)", "type": "string", "maxLength": 255, "example": "Custom T-Shirt Design", "nullable": true }, "design_tags": { "description": "Design tags for organization (max 20 tags)", "type": "array", "items": { "type": "string", "maxLength": 50, "example": "custom" }, "nullable": true } }, "type": "object", "example": { "name": "Premium Cotton T-Shirt", "sku_origin": "TSHIRT-001", "images": [ "https://example.com/products/tshirt-front.jpg", "https://example.com/products/tshirt-back.jpg" ], "category": "Clothing", "tags": [ "cotton", "premium", "t-shirt" ], "description": "Premium quality cotton t-shirt", "price": 29.99, "materials": "100% Cotton" } } }, "multipart/form-data": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Product name/title", "type": "string", "maxLength": 255, "example": "Premium Cotton T-Shirt" }, "image_files[]": { "description": "Upload image files (max 10 files, 10MB each). Supports jpeg, jpg, png, gif, webp. At least one image required (via images or image_files).", "type": "array", "items": { "type": "string", "format": "binary" } }, "video_files[]": { "description": "Upload video files (max 1 file, 100MB). Supports mp4, avi, quicktime.", "type": "array", "items": { "type": "string", "format": "binary" } }, "digital_files_upload[]": { "description": "Upload digital files (max 10 files, 50MB each)", "type": "array", "items": { "type": "string", "format": "binary" } }, "images": { "description": "Product image URLs (can mix with image_files). HTTPS only.", "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/products/tshirt.jpg" } }, "digital_files": { "description": "Digital file URLs (can mix with digital_files_upload). HTTPS only.", "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/files/digital.pdf" } }, "videos": { "description": "Video URLs (can mix with video_files). HTTPS only.", "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/videos/demo.mp4" } }, "sku_origin": { "description": "Product SKU for duplicate detection", "type": "string", "maxLength": 255, "example": "TSHIRT-001" }, "category": { "description": "Product category name", "type": "string", "maxLength": 100, "example": "Clothing" }, "tags": { "description": "Product tags (can be array or comma-separated string)", "type": "array", "items": { "type": "string", "maxLength": 50, "example": "cotton" } }, "description": { "description": "Product description", "type": "string", "maxLength": 2000, "example": "Premium quality cotton t-shirt" }, "price": { "description": "Product price", "type": "number", "format": "float", "minimum": 0, "example": 29.99 }, "materials": { "description": "Product materials", "type": "string", "maxLength": 500, "example": "100% Cotton" }, "image_file_paths": { "description": "Image file paths from upload-temporary-file API (max 10)", "type": "array", "items": { "type": "string", "example": "concordart/tmp/manual-create-product/359/223/image-uuid.jpg" } }, "video_file_path": { "description": "Video file path from upload-temporary-file API", "type": "string", "example": "concordart/tmp/manual-create-product/359/223/video-uuid.mp4" }, "digital_file_paths": { "description": "Digital file paths from upload-temporary-file API (max 10)", "type": "array", "items": { "type": "string", "example": "concordart/tmp/manual-create-product/359/223/digital-uuid.pdf" } }, "design_file_path": { "description": "Main design file path from upload-temporary-file API", "type": "string", "example": "concordart/tmp/manual-create-product/359/223/design-main-uuid.png" }, "design_url": { "description": "Main design file URL (alternative to design_file_path, HTTPS only)", "type": "string", "format": "url", "example": "https://example.com/designs/main-design.png" }, "design_position_file_paths": { "description": "Position/mockup file paths from upload-temporary-file API (max 10)", "type": "array", "items": { "type": "string", "example": "concordart/tmp/manual-create-product/359/223/position-1-uuid.png" } }, "design_position_urls": { "description": "Position/mockup file URLs (max 10, HTTPS only)", "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/designs/position-1.png" } }, "design_name": { "description": "Design name (defaults to product name if not provided)", "type": "string", "maxLength": 255, "example": "Custom T-Shirt Design" }, "design_tags": { "description": "Design tags for organization (max 20 tags)", "type": "array", "items": { "type": "string", "maxLength": 50, "example": "custom" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Product created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "product_id": { "description": "Created product ID", "type": "integer", "example": 12345 }, "sku": { "description": "Generated product SKU", "type": "string", "example": "5000000012345" }, "title": { "description": "Product title", "type": "string", "example": "Premium Cotton T-Shirt" }, "is_restored": { "description": "True if product was restored from soft-deleted state", "type": "boolean", "example": false }, "design_created": { "description": "True if design was created and attached to product", "type": "boolean", "example": true }, "design_id": { "description": "Created design ID (null if design not created)", "type": "integer", "example": 456, "nullable": true }, "message": { "description": "Creation status message", "type": "string", "example": "Product created successfully" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or site is not source site", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Site is not source site" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Site not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Site not found" } }, "type": "object" } } } }, "409": { "description": "Product already exists (duplicate SKU)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 409 }, "message": { "type": "string", "example": "Product with SKU 'TSHIRT-001' already exists on this site (Product ID: 12345)" } }, "type": "object" } } } }, "422": { "description": "Validation error - missing required fields or invalid file format", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 422 }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "images": { "type": "array", "items": { "type": "string", "example": "At least one image is required. Provide images URLs or upload image files." } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/products": { "get": { "tags": [ "Products" ], "summary": "List products", "description": "Get product catalog list with details. Use this endpoint to get product IDs for the 'selected' parameter in POST /deploy-product.", "operationId": "listProducts", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "title", "in": "query", "description": "Filter by product title (partial match)", "required": false, "schema": { "type": "string", "example": "T-Shirt" } }, { "name": "sku", "in": "query", "description": "Filter by product SKU", "required": false, "schema": { "type": "string", "example": "500001525179" } }, { "name": "category_id", "in": "query", "description": "Filter by category ID", "required": false, "schema": { "type": "integer", "example": 8406 } } ], "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Product ID - Use this in 'selected' array for deploy-product", "type": "integer", "example": 1624344 }, "product_origin_id": { "type": "integer", "example": 500000052260 }, "sku": { "type": "string", "example": "500001624344" }, "sku_origin": { "type": "string", "example": "TT123" }, "title": { "type": "string", "example": "Premium Cotton T-Shirt" }, "thumbnail": { "type": "string", "example": "https://example.com/image.png" }, "reported": { "type": "integer", "example": 0 }, "has_digital": { "type": "boolean", "example": false }, "can_download": { "type": "boolean", "example": false }, "category": { "properties": { "id": { "type": "integer", "example": 8406 }, "name": { "type": "string", "example": "Ornaments" } }, "type": "object" }, "tags": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 25226 }, "product_id": { "type": "integer", "example": 1525179 }, "name": { "type": "string", "example": "liberal shirt" } }, "type": "object" } }, "sites": { "properties": { "origin_site": { "properties": { "id": { "type": "integer", "example": 5018 }, "platform_id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Default site" } }, "type": "object" }, "mapping_sites": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "report": { "properties": { "summary": { "properties": { "views": { "type": "string", "example": "0" }, "favorers": { "type": "string", "example": "0" }, "sales": { "type": "string", "example": "0" }, "conversion_rate": { "type": "string", "example": "0.00" } }, "type": "object" } }, "type": "object" }, "videos": { "type": "array", "items": { "type": "object" } }, "digitals": { "type": "array", "items": { "type": "object" } }, "resource_quota": { "properties": { "is_using_slot": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 25 }, "count": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 13 }, "links": { "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/products?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Update products (bulk)", "description": "Update one or multiple products at once. You can update product title, images, tags, videos, and digital files. Each product is identified by its product_id from GET /products.", "operationId": "updateProducts", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Array of products to update. Each product must have product_id", "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "product_id" ], "properties": { "product_id": { "description": "Product ID from GET /products", "type": "integer", "example": 1624344 }, "title": { "description": "Updated product title. Invalid characters will be rejected.", "type": "string", "maxLength": 255, "example": "Updated Premium Cotton T-Shirt" }, "images": { "description": "Product images. Can contain existing images (with id) or new images (with url). Images not in this array will be deleted.", "type": "array", "items": { "properties": { "id": { "description": "Existing image ID (from GET /products response). Use this to keep existing images.", "type": "integer", "example": 12345, "nullable": true }, "url": { "description": "Image URL. Required for new images (when id is null). Must be HTTPS.", "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/new-image.jpg" }, "position": { "description": "Display order/rank of the image", "type": "integer", "example": 1 } }, "type": "object" } }, "images_delete": { "description": "Array of image IDs to delete", "type": "array", "items": { "type": "integer", "example": 12346 } }, "tags": { "description": "Product tags. Will replace existing tags.", "type": "array", "items": { "type": "string", "maxLength": 50, "example": "cotton" } }, "videos": { "description": "Product videos (must be HTTPS URLs)", "type": "array", "items": { "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/video.mp4" } }, "digitals": { "description": "Digital files for downloadable products (must be HTTPS URLs)", "type": "array", "items": { "type": "string", "format": "url", "pattern": "^https://", "example": "https://example.com/file.pdf" } } }, "type": "object" } }, "example": [ { "product_id": 1624344, "title": "Updated Premium Cotton T-Shirt - Black", "images": [ { "id": 12345, "position": 1 }, { "id": null, "url": "https://example.com/new-image.jpg", "position": 2 } ], "tags": [ "cotton", "premium", "black", "t-shirt" ] }, { "product_id": 1624345, "title": "Another Updated Product" } ] } } }, "responses": { "200": { "description": "Products updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Products updated successfully" }, "data": { "type": "object", "example": [] } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Product [#1624344 - SKU123]: Invalid character [%]" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Product [#1624344]: Not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/return-policies": { "get": { "tags": [ "Return Policies" ], "summary": "List return policies", "description": "Get return policies for product deployments. Required for Etsy physical products. Each policy includes site and creator information.", "operationId": "listReturnPolicies", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "site_id", "in": "query", "description": "**Required**. Site ID to get return policies from", "required": true, "schema": { "type": "integer", "example": 6529 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Return policies retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Array of return policies", "type": "array", "items": { "properties": { "id": { "description": "Internal return policy ID - Use in Deploy API", "type": "integer", "example": 5662 }, "name": { "description": "Policy name", "type": "string", "example": "Standard Return Policy", "nullable": true }, "return_policy_id": { "description": "Platform return policy ID", "type": "integer", "example": 1385544452196 }, "shop_id": { "description": "Platform shop ID", "type": "integer", "example": 58282706 }, "accepts_returns": { "description": "Whether returns are accepted (1=yes, 0=no)", "type": "integer", "example": 1 }, "accepts_exchanges": { "description": "Whether exchanges are accepted (1=yes, 0=no)", "type": "integer", "example": 1 }, "return_deadline": { "description": "Return deadline in days", "type": "integer", "example": 30, "nullable": true }, "site": { "description": "Associated site information", "properties": { "id": { "type": "integer", "example": 6529 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Shop" }, "is_destination": { "type": "integer", "example": 1 }, "is_active": { "type": "integer", "example": 1 }, "site_is_death": { "type": "integer", "example": 0 }, "is_limit": { "type": "integer", "example": 0 }, "is_crawl": { "type": "integer", "example": 1 }, "is_sync_admin": { "type": "integer", "example": 0 }, "is_display": { "type": "integer", "example": 1 }, "is_add_watermark": { "type": "integer", "example": 0 }, "reported": { "type": "string", "example": null, "nullable": true }, "last_sync_reported": { "type": "string", "example": null, "nullable": true }, "receipt_new": { "type": "integer", "example": 0 }, "receipt_completed": { "type": "integer", "example": 0 }, "last_sync_receipts": { "type": "string", "example": null, "nullable": true }, "before_sync": { "type": "integer", "example": 0 }, "after_sync": { "type": "integer", "example": 0 }, "last_modified_timestamp": { "type": "string", "example": null, "nullable": true }, "finished_sync_at": { "type": "string", "example": "2025-01-15 10:30:45" }, "last_sync_interacts": { "type": "string", "example": null, "nullable": true }, "last_sync_receipt_transactions": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "created_by": { "description": "User who created this policy", "properties": { "id": { "type": "integer", "example": 10062 }, "email": { "type": "string", "example": "user@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } }, "type": "object" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of return policies", "type": "integer", "example": 5 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 5 }, "per_page": { "description": "Results per page", "type": "integer", "example": 10 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 1 }, "links": { "description": "Pagination navigation links", "properties": { "next": { "description": "URL to next page (null if last page)", "type": "string", "example": "https://api.dodgeprint.com/api/v1/return-policies?site_id=6529&page=2", "nullable": true } }, "type": "object" } }, "type": "object" }, "meta": { "description": "Additional metadata (currently empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - site_id is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The site id field is required." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Return Policies" ], "summary": "Create return policy", "description": "Create a new return policy for a site. Required for Etsy physical products.", "operationId": "createReturnPolicy", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Return policy configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "site_id" ], "properties": { "site_id": { "description": "Site ID where this policy will be created (required)", "type": "integer", "example": 6529 }, "name": { "description": "Return policy name (optional)", "type": "string", "example": "14 Day Return Policy" }, "accepts_returns": { "description": "Whether returns are accepted (optional, default: false)", "type": "boolean", "example": true }, "accepts_exchanges": { "description": "Whether exchanges are accepted (optional, default: false)", "type": "boolean", "example": false }, "return_deadline": { "description": "Return deadline in days (optional)", "type": "integer", "example": 14 } }, "type": "object" } } } }, "responses": { "200": { "description": "Return policy created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created successfully" }, "data": { "properties": { "id": { "description": "New return policy ID", "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The site_id field is required." } }, "type": "object" } } } }, "409": { "description": "Policy already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Accepts returns = Yes - Accepts exchanges = No - Return deadline = 14" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/return-policies/{id}": { "get": { "tags": [ "Return Policies" ], "summary": "Get return policy details", "description": "Get complete return policy configuration including return/exchange acceptance and deadline. Includes site and creator information.", "operationId": "getReturnPolicyDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Return policy ID", "required": true, "schema": { "type": "integer", "example": 6847 } }, { "name": "site_id", "in": "query", "description": "**Required**. Site ID for workspace resource sharing", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "responses": { "200": { "description": "Return policy retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Return policy details", "properties": { "id": { "description": "Internal return policy ID", "type": "integer", "example": 6847 }, "name": { "description": "Policy name", "type": "string", "example": "Standard Return Policy", "nullable": true }, "return_policy_id": { "description": "Platform return policy ID", "type": "integer", "example": 1425823125379 }, "shop_id": { "description": "Platform shop ID", "type": "integer", "example": 58282706 }, "accepts_returns": { "description": "Whether returns are accepted (1=yes, 0=no)", "type": "integer", "example": 1 }, "accepts_exchanges": { "description": "Whether exchanges are accepted (1=yes, 0=no)", "type": "integer", "example": 1 }, "return_deadline": { "description": "Return deadline in days", "type": "integer", "example": 21, "nullable": true }, "site": { "description": "Associated site information", "properties": { "id": { "type": "integer", "example": 6529 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Shop" }, "site_is_death": { "type": "integer", "example": 0 }, "is_crawl": { "type": "integer", "example": 1 }, "is_add_watermark": { "type": "integer", "example": 0 }, "is_insufficient_scope": { "type": "integer", "example": 0 }, "reported": { "type": "string", "example": null, "nullable": true }, "last_sync_reported": { "type": "string", "example": null, "nullable": true }, "receipt_new": { "type": "integer", "example": 0 }, "receipt_completed": { "type": "integer", "example": 0 }, "last_sync_receipts": { "type": "string", "example": null, "nullable": true }, "before_sync": { "type": "integer", "example": 0 }, "after_sync": { "type": "integer", "example": 0 }, "last_modified_timestamp": { "type": "string", "example": null, "nullable": true }, "finished_sync_at": { "type": "string", "example": "2025-01-15 10:30:45" }, "last_sync_interacts": { "type": "string", "example": null, "nullable": true }, "last_sync_receipt_transactions": { "type": "string", "example": null, "nullable": true }, "site_url": { "type": "string", "example": "https://www.etsy.com/shop/MyShop" } }, "type": "object" }, "created_by": { "description": "User who created this policy", "properties": { "id": { "type": "integer", "example": 10062 }, "email": { "type": "string", "example": "user@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error - site_id is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The site id field is required." } }, "type": "object" } } } }, "404": { "description": "Return policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Return Policies" ], "summary": "Update return policy", "description": "Update an existing return policy's configuration.", "operationId": "updateReturnPolicy", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Return policy ID", "required": true, "schema": { "type": "integer", "example": 6847 } }, { "name": "site_id", "in": "query", "description": "**Required**. Site ID for workspace resource sharing", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "requestBody": { "description": "Return policy update data", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Return policy name", "type": "string", "example": "Updated Return Policy" } }, "type": "object" } } } }, "responses": { "200": { "description": "Return policy updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "description": "Empty array on successful update", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - site_id is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The site id field is required." } }, "type": "object" } } } }, "404": { "description": "Return policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Return Policies" ], "summary": "Delete return policy", "description": "Delete a return policy. Note: Cannot delete policies that are currently in use by active listings.", "operationId": "deleteReturnPolicy", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Return policy ID", "required": true, "schema": { "type": "integer", "example": 6847 } }, { "name": "site_id", "in": "query", "description": "**Required**. Site ID for workspace resource sharing", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "responses": { "200": { "description": "Return policy deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "description": "Empty array on successful deletion", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - site_id is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The site id field is required." } }, "type": "object" } } } }, "404": { "description": "Return policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sections": { "get": { "tags": [ "Sections" ], "summary": "List Etsy shop sections", "description": "Get Etsy shop sections for organizing products. Sections help organize listings within an Etsy shop. (Etsy platform only)", "operationId": "listSections", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "site_id", "in": "query", "description": "**Required**. Etsy site ID to get sections from", "required": true, "schema": { "type": "integer", "example": 6529 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Sections retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Array of shop sections", "type": "array", "items": { "properties": { "id": { "description": "Section ID - Use in Deploy API", "type": "integer", "example": 2837 }, "title": { "description": "Section title/name", "type": "string", "example": "Summer Collection" }, "shop_section_id": { "description": "Etsy platform section ID", "type": "integer", "example": 56331845 }, "rank": { "description": "Display order/rank", "type": "integer", "example": 1 }, "active_listing_count": { "description": "Number of active listings in this section", "type": "integer", "example": 25 }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" }, "updated_at": { "description": "Last update timestamp", "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" } }, "type": "object" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of sections", "type": "integer", "example": 15 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 10 }, "per_page": { "description": "Results per page", "type": "integer", "example": 10 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 2 }, "links": { "description": "Pagination navigation links", "properties": { "next": { "description": "URL to next page (null if last page)", "type": "string", "example": "https://api.dodgeprint.com/api/v1/sections?site_id=6529&page=2", "nullable": true } }, "type": "object" } }, "type": "object" }, "meta": { "description": "Additional metadata (currently empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - site_id is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The site id field is required." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Sections" ], "summary": "Create Etsy shop section", "description": "Create a new shop section to organize products in your Etsy store. Sections help customers browse products by category.", "operationId": "createSection", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Section configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "title", "site_id" ], "properties": { "title": { "description": "Section name (required)", "type": "string", "example": "New Arrivals" }, "site_id": { "description": "Etsy site ID (required)", "type": "integer", "example": 6529 } }, "type": "object" } } } }, "responses": { "200": { "description": "Section created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created successfully" }, "data": { "properties": { "id": { "description": "New section ID", "type": "integer", "example": 28745002 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The title field is required." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sections/{id}": { "get": { "tags": [ "Sections" ], "summary": "Get Etsy shop section details", "description": "Get complete shop section information including title, rank, and active listing count.", "operationId": "getSectionDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Section ID", "required": true, "schema": { "type": "integer", "example": 2837 } } ], "responses": { "200": { "description": "Section retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Section details", "properties": { "id": { "description": "Section ID", "type": "integer", "example": 2837 }, "title": { "description": "Section title/name", "type": "string", "example": "Featured Products" }, "shop_section_id": { "description": "Etsy platform section ID", "type": "integer", "example": 56331845 }, "rank": { "description": "Display order in shop", "type": "integer", "example": 1 }, "active_listing_count": { "description": "Number of active listings in this section", "type": "integer", "example": 25 }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" }, "updated_at": { "description": "Last update timestamp", "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Section not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Sections" ], "summary": "Update Etsy shop section", "description": "Update an existing shop section's title. Changes will be synced to Etsy.", "operationId": "updateSection", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Section ID", "required": true, "schema": { "type": "integer", "example": 28745001 } }, { "name": "site_id", "in": "query", "description": "**Required**. Etsy site ID for workspace resource sharing", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "requestBody": { "description": "Section update data", "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "description": "Section title (required)", "type": "string", "example": "Updated Section Name" } }, "type": "object" } } } }, "responses": { "200": { "description": "Section updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "description": "Empty array on successful update", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error - site_id or title is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The site id field is required." } }, "type": "object" } } } }, "404": { "description": "Section not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/shipping-profiles": { "get": { "tags": [ "Shipping Profiles" ], "summary": "List shipping profiles", "description": "Get shipping profiles for your e-commerce sites. Required for Etsy and TikTok deployments.", "operationId": "listShippingProfiles", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "site_id", "in": "query", "description": "Filter by site ID - Strongly recommended to avoid performance issues", "required": false, "schema": { "type": "integer", "example": 6529 } }, { "name": "platform_id", "in": "query", "description": "Filter by platform ID (alternative to site_id)", "required": false, "schema": { "type": "integer", "example": 1 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Shipping profiles retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Shipping profile ID - Use in Deploy API", "type": "integer", "example": 6937 }, "shipping_profile_id": { "type": "integer", "example": 288818719081 }, "site": { "properties": { "id": { "type": "integer", "example": 6529 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "InkspireC" }, "finished_sync_at": { "type": "string", "format": "datetime", "example": "2025-10-22 03:05:31" } }, "type": "object" }, "title": { "type": "string", "example": "Check normal" }, "origin_country": { "properties": { "origin_country_iso": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" }, "origin_postal_code": { "type": "string", "example": "93504" } }, "type": "object" }, "processing_days": { "properties": { "min": { "type": "integer", "example": 1 }, "max": { "type": "integer", "example": 10 }, "unit": { "type": "string", "example": "business_days" }, "label": { "type": "string", "example": "1 - 10 days" } }, "type": "object" }, "destinations": { "type": "array", "items": { "properties": { "shipping_profile_destination_id": { "type": "integer", "example": 58644231565 }, "shipping_carrier": { "properties": { "shipping_carrier_id": { "type": "integer", "example": 3 }, "carrier_name": { "type": "string", "example": "FedEx" }, "mail_class_key": { "type": "string", "example": "international_economy" }, "mail_class_name": { "type": "string", "example": "FedEx International Economy®" } }, "type": "object" }, "destination_country": { "type": "string", "example": null, "nullable": true }, "destination_region": { "type": "string", "example": null, "nullable": true }, "primary_cost": { "type": "string", "example": "0.00" }, "secondary_cost": { "type": "string", "example": "0.00" }, "delivery_days": { "type": "string", "example": null, "nullable": true }, "is_domestic": { "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 4 }, "count": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 2 }, "links": { "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/shipping-profiles?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Shipping Profiles" ], "summary": "Create shipping profile", "description": "Create a new shipping profile for a site. The profile will be created on the e-commerce platform (Etsy/TikTok) and synced to Dodgeprint. **IMPORTANT FOR ETSY**: Etsy sites have strict validation - shipping_carrier_id and mail_class must exist in the database (use GET /v1/countries/{country_iso}/shipping-carriers to get valid values). Other platforms have relaxed validation for backwards compatibility.", "operationId": "createShippingProfile", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Shipping profile configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "site_id", "origin_country_iso", "origin_postal_code", "min_processing_days", "max_processing_days", "destinations" ], "properties": { "site_id": { "description": "Site ID where this profile will be created (required)", "type": "integer", "example": 6529 }, "title": { "description": "Shipping profile name (optional)", "type": "string", "example": "Express Shipping" }, "origin_country_iso": { "description": "Origin country ISO code - applies to all destinations (required)", "type": "string", "example": "US" }, "origin_postal_code": { "description": "Origin postal/zip code (required)", "type": "string", "example": "12345" }, "min_processing_days": { "description": "Minimum processing days before shipping (required)", "type": "integer", "example": 1 }, "max_processing_days": { "description": "Maximum processing days before shipping (required)", "type": "integer", "example": 3 }, "processing_days_unit": { "description": "Unit for processing days (optional, defaults to 'business_days')", "type": "string", "enum": [ "business_days", "weeks" ], "example": "business_days" }, "destinations": { "description": "Shipping destinations and pricing. At least one domestic destination (is_domestic=true) is required. NOTE: mail_class and min/max_delivery_days are mutually exclusive - use one or the other, not both.", "type": "array", "items": { "required": [ "shipping_carrier_id", "origin_country_iso", "destination_country_iso", "primary_cost", "secondary_cost", "is_domestic" ], "properties": { "shipping_carrier_id": { "description": "Shipping carrier ID from GET /v1/countries/{country_iso}/shipping-carriers. For Etsy sites: MUST be a valid carrier_id from the database.", "type": "integer", "example": 1 }, "origin_country_iso": { "description": "Origin country ISO code for this destination (must match root-level origin_country_iso)", "type": "string", "example": "US" }, "destination_country_iso": { "description": "Destination country ISO code. For domestic, must match origin_country_iso", "type": "string", "example": "US" }, "primary_cost": { "description": "Base shipping cost for first item", "type": "number", "format": "float", "example": 5.99 }, "secondary_cost": { "description": "Additional shipping cost per extra item", "type": "number", "format": "float", "example": 1.99 }, "mail_class": { "description": "Mail class key from carrier data. CANNOT be used with min/max_delivery_days - choose one approach. For Etsy sites: MUST be a valid mail_class_key for the specified carrier_id and origin_country_iso.", "type": "string", "example": "priority" }, "min_delivery_days": { "description": "Minimum delivery days. CANNOT be used with mail_class - choose one approach", "type": "integer", "example": 3 }, "max_delivery_days": { "description": "Maximum delivery days. CANNOT be used with mail_class - choose one approach", "type": "integer", "example": 7 }, "is_domestic": { "description": "True if shipping within same country (origin_country_iso = destination_country_iso). At least one domestic destination required", "type": "boolean", "example": true } }, "type": "object" }, "example": [ { "shipping_carrier_id": 1, "origin_country_iso": "US", "destination_country_iso": "US", "primary_cost": 5.99, "secondary_cost": 1.99, "mail_class": "priority", "is_domestic": true }, { "shipping_carrier_id": 1, "origin_country_iso": "US", "destination_country_iso": "CA", "primary_cost": 12.99, "secondary_cost": 3.99, "mail_class": "priority_international", "is_domestic": false } ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Shipping profile created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or profile already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "description": "Error message - can be validation error, 'Entity already existed: {title}', 'Postal Code is required', 'You can't provide a carrier or mail class and min/max delivery days at the same time', or 'Missing input parameter: [field_name]'", "type": "string", "example": "The site_id field is required." } }, "type": "object" } } } }, "422": { "description": "Validation errors (Etsy sites have strict validation for carrier/mail_class, other platforms have relaxed validation). Common errors: missing required fields, invalid carrier_id/mail_class combination, mutual exclusivity violation (mail_class vs delivery_days)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The shipping carrier and mail class combination is not valid for the specified origin country." }, "errors": { "description": "Error messages for specific fields. Examples: site_id validation, Etsy carrier/mail_class validation, mutual exclusivity violations", "properties": { "destinations.0.mail_class": { "type": "array", "items": { "type": "string", "example": "The shipping carrier and mail class combination is not valid for the specified origin country." } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/shipping-profiles/{id}": { "get": { "tags": [ "Shipping Profiles" ], "summary": "Get shipping profile details", "description": "Get complete shipping profile configuration including destinations, carriers, and pricing rules.", "operationId": "getShippingProfileDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Shipping profile ID", "required": true, "schema": { "type": "integer", "example": 6617 } } ], "responses": { "200": { "description": "Shipping profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 6617 }, "title": { "type": "string", "example": "Standard Shipping" }, "site_id": { "type": "integer", "example": 6529 }, "platform_id": { "type": "integer", "example": 1 }, "shipping_profile_platform_id": { "type": "string", "example": "1234567890" }, "origin_country_iso": { "type": "string", "example": "US" }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Shipping profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Shipping Profiles" ], "summary": "Update shipping profile", "description": "Update an existing shipping profile's configuration. Changes will be synced to the e-commerce platform.", "operationId": "updateShippingProfile", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Shipping profile ID", "required": true, "schema": { "type": "integer", "example": 6617 } } ], "requestBody": { "description": "Shipping profile update data", "required": true, "content": { "application/json": { "schema": { "required": [ "site_id" ], "properties": { "site_id": { "description": "Site ID (required)", "type": "integer", "example": 6529 }, "title": { "description": "Shipping profile name", "type": "string", "example": "Updated Shipping Profile" }, "destinations": { "description": "Updated shipping destinations and pricing", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Shipping profile updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Validation error or business logic error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "description": "Error message - can be validation error, platform restriction, or duplicate title", "type": "string", "example": "The site_id field is required." } }, "type": "object" } } } }, "422": { "description": "Unprocessable entity - Missing required field", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The site_id field is required." }, "errors": { "properties": { "site_id": { "type": "array", "items": { "type": "string", "example": "The site_id field is required." } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Shipping profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Shipping Profiles" ], "summary": "Delete shipping profile", "description": "Delete a shipping profile. This will remove the profile from both Dodgeprint and the e-commerce platform.", "operationId": "deleteShippingProfile", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Shipping profile ID", "required": true, "schema": { "type": "integer", "example": 6617 } } ], "responses": { "200": { "description": "Shipping profile deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Shipping profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/countries/{country_iso}/shipping-carriers": { "get": { "tags": [ "Shipping Profiles" ], "summary": "Get shipping carriers by country", "description": "Get available shipping carriers and mail classes for a specific country. Used to get carrier IDs and mail class keys for creating shipping profiles.", "operationId": "getShippingCarriers", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "country_iso", "in": "path", "description": "Country ISO code (e.g., 'US', 'GB', 'CA')", "required": true, "schema": { "type": "string", "example": "US" } } ], "responses": { "200": { "description": "Shipping carriers retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "shipping_carrier_id": { "description": "Unique carrier ID - use in shipping profile destinations", "type": "integer", "example": 1 }, "name": { "description": "Carrier name", "type": "string", "example": "USPS" }, "domestic": { "description": "Available domestic mail classes", "type": "array", "items": { "properties": { "mail_class_key": { "description": "Mail class key - use in shipping profile destinations", "type": "string", "example": "standard" }, "mail_class_name": { "description": "Human-readable mail class name", "type": "string", "example": "USPS Standard" } }, "type": "object" }, "example": [ { "mail_class_key": "standard", "mail_class_name": "USPS Standard" }, { "mail_class_key": "express", "mail_class_name": "USPS Express" } ] }, "international": { "description": "Available international mail classes", "type": "array", "items": { "properties": { "mail_class_key": { "description": "Mail class key - use in shipping profile destinations", "type": "string", "example": "priority_international" }, "mail_class_name": { "description": "Human-readable mail class name", "type": "string", "example": "USPS Priority Mail International" } }, "type": "object" }, "example": [ { "mail_class_key": "priority_international", "mail_class_name": "USPS Priority Mail International" }, { "mail_class_key": "express_international", "mail_class_name": "USPS Express Mail International" } ] } }, "type": "object" }, "example": [ { "shipping_carrier_id": 1, "name": "USPS", "domestic": [ { "mail_class_key": "standard", "mail_class_name": "USPS Standard" }, { "mail_class_key": "express", "mail_class_name": "USPS Express" } ], "international": [ { "mail_class_key": "priority_international", "mail_class_name": "USPS Priority Mail International" } ] } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tag-templates": { "get": { "tags": [ "Tag Templates" ], "summary": "List tag templates", "description": "Get predefined tag templates for different product types. Templates contain pre-configured tag sets that can be reused across multiple deployments.", "operationId": "listTagTemplates", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Tag templates retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Tag template ID - Use in Deploy API", "type": "integer", "example": 1927 }, "name": { "type": "string", "example": "Canvas" }, "tags": { "description": "Array of tag names", "type": "array", "items": { "type": "string", "example": "Poster Canvas Art" } }, "is_active": { "type": "integer", "example": 1 }, "created_by": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "VN" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" }, "resource_share": { "properties": { "resourceable_id": { "type": "integer", "example": 1927 }, "total_users": { "type": "integer", "example": 1 }, "top_users": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 1 }, "count": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "links": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Tag Templates" ], "summary": "Create tag template", "description": "Create a new tag template with a predefined set of tags. Templates can be reused across multiple product deployments.", "operationId": "createTagTemplate", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Tag template configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "tags" ], "properties": { "name": { "description": "Template name (required)", "type": "string", "example": "Canvas Print Tags" }, "tags": { "description": "Array of tag names (required, max 13 for Etsy)", "type": "array", "items": { "type": "string" }, "example": [ "canvas", "wall-art", "home-decor", "custom-print" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Tag template created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created successfully" }, "data": { "properties": { "id": { "description": "New tag template ID", "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tag-templates/{id}": { "get": { "tags": [ "Tag Templates" ], "summary": "Get tag template details", "description": "Get complete tag template configuration including the predefined tag set.", "operationId": "getTagTemplateDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Tag template ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Tag template retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "T-Shirt Tags" }, "tags": { "description": "Array of tag names", "type": "array", "items": { "type": "string", "example": "t-shirt" } }, "created_at": { "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Tag template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Tag Templates" ], "summary": "Update tag template", "description": "Update an existing tag template's name and/or tag set.", "operationId": "updateTagTemplate", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Tag template ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "description": "Tag template update data", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Template name", "type": "string", "example": "Updated Tag Template" }, "tags": { "description": "Updated array of tag names", "type": "array", "items": { "type": "string" }, "example": [ "updated-tag1", "updated-tag2" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Tag template updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Tag template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Tag Templates" ], "summary": "Delete tag template", "description": "Delete a tag template. This will not affect products already deployed with this template's tags.", "operationId": "deleteTagTemplate", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Tag template ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Tag template deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Tag template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tags": { "get": { "tags": [ "Tags" ], "summary": "List product tags", "description": "Get product tags for deployments. Maximum 13 tags for Etsy listings. Tags help customers discover products through search.", "operationId": "listTags", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "search", "in": "query", "description": "Search tags by name", "required": false, "schema": { "type": "string", "example": "shirt" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Tags retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Array of tags", "type": "array", "items": { "properties": { "id": { "description": "Tag ID", "type": "integer", "example": 1 }, "name": { "description": "Tag name - Use in Deploy API", "type": "string", "example": "Summer Collection" }, "childs": { "description": "Child tags (currently always empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of tags", "type": "integer", "example": 391442 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 10 }, "per_page": { "description": "Results per page", "type": "integer", "example": 10 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 39145 }, "links": { "description": "Pagination navigation links", "properties": { "next": { "description": "URL to next page (null if last page)", "type": "string", "example": "https://api.dodgeprint.com/api/v1/tags?page=2", "nullable": true } }, "type": "object" } }, "type": "object" }, "meta": { "description": "Additional metadata (currently empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User does not have the right permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Tags" ], "summary": "Create tag", "description": "Create a new product tag. Tags help with product discoverability and search optimization.", "operationId": "createTag", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Tag data", "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Tag name (required, lowercase recommended)", "type": "string", "example": "custom-design" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tag created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created successfully" }, "data": { "properties": { "id": { "description": "New tag ID", "type": "integer", "example": 2 }, "name": { "type": "string", "example": "custom-design" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tags/{id}": { "get": { "tags": [ "Tags" ], "summary": "Get tag details", "description": "Get tag information by ID. Returns tag name and child tags structure.", "operationId": "getTagDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Tag retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Tag details", "properties": { "id": { "description": "Tag ID", "type": "integer", "example": 1 }, "name": { "description": "Tag name", "type": "string", "example": "Summer Collection" }, "childs": { "description": "Child tags (currently always empty)", "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - User does not have the right permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Tags" ], "summary": "Update tag", "description": "Update an existing tag's name.", "operationId": "updateTag", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "description": "Tag update data", "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "New tag name (required)", "type": "string", "example": "updated-tag-name" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tag updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." } }, "type": "object" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Tags" ], "summary": "Delete tag", "description": "Delete a tag. This will remove the tag from all products using it.", "operationId": "deleteTag", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Tag deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/variants/attributes": { "get": { "tags": [ "Variant Attributes" ], "summary": "Get variant attributes by platform", "description": "Get available variant dimension attributes for a specific platform. These attributes define what types of variant dimensions can be used (Size, Color, Type, etc.). Use these attribute names when creating dimension_labels in POST /group-variants.", "operationId": "getVariantAttributes", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "platform_id", "in": "query", "description": "Filter by platform: 1=Etsy, 3=Amazon, 4=TikTok", "required": false, "schema": { "type": "integer", "enum": [ 1, 3, 4 ], "example": 1 } } ], "responses": { "200": { "description": "Variant attributes retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "List of variant dimension attributes", "type": "array", "items": { "properties": { "id": { "description": "Attribute ID", "type": "integer", "example": 5 }, "platform_id": { "description": "Platform: 1=Etsy, 3=Amazon, 4=TikTok", "type": "integer", "example": 1 }, "code": { "description": "Attribute code - Use this in dimension_labels", "type": "string", "example": "Size" }, "name": { "description": "Display name", "type": "string", "example": "Size" }, "value": { "description": "Predefined values if any", "type": "string", "example": null, "nullable": true }, "description": { "type": "string", "example": null, "nullable": true }, "is_customizable": { "description": "1=Can use custom values, 0=Must use predefined values", "type": "integer", "example": 1 }, "deleted_at": { "type": "string", "example": null, "nullable": true }, "created_at": { "description": "ISO 8601 format", "type": "string", "format": "date-time", "example": "2025-03-06T09:09:39.000000Z" }, "updated_at": { "description": "ISO 8601 format", "type": "string", "format": "date-time", "example": "2025-03-06T09:09:39.000000Z" } }, "type": "object" } } }, "type": "object" }, "example": { "success": true, "code": 200, "data": [ { "id": 5, "platform_id": 1, "code": "Size", "name": "Size", "value": null, "description": null, "is_customizable": 1, "deleted_at": null, "created_at": "2025-03-06T09:09:39.000000Z", "updated_at": "2025-03-06T09:09:39.000000Z" }, { "id": 6, "platform_id": 1, "code": "Color", "name": "Color", "value": null, "description": null, "is_customizable": 1, "deleted_at": null, "created_at": "2025-03-06T09:09:39.000000Z", "updated_at": "2025-03-06T09:09:39.000000Z" }, { "id": 7, "platform_id": 1, "code": "Type", "name": "Type", "value": null, "description": null, "is_customizable": 1, "deleted_at": null, "created_at": "2025-03-06T09:09:39.000000Z", "updated_at": "2025-03-06T09:09:39.000000Z" }, { "id": 8, "platform_id": 1, "code": "Type-Size", "name": "Type-Size", "value": null, "description": null, "is_customizable": 1, "deleted_at": null, "created_at": "2025-03-06T09:09:39.000000Z", "updated_at": "2025-03-06T09:09:39.000000Z" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/group-variants": { "get": { "tags": [ "Variant Groups" ], "summary": "List variant groups", "description": "Browse available variant group configurations (size/color combinations). Use this to find variant groups, then get full details with GET /group-variants/{id}.", "operationId": "listVariantGroups", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "name", "in": "query", "description": "Filter by variant group name (partial match)", "required": false, "schema": { "type": "string", "example": "T-Shirt" } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean", "example": true } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Variant groups retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Variant group ID - Use in GET /group-variants/{id} or Deploy API", "type": "integer", "example": 6793 }, "name": { "type": "string", "example": "Demo variants" }, "is_active": { "description": "Whether this variant group is active", "type": "integer", "example": 1 }, "headers": { "description": "Variant option definitions including id, variant fields, price, and quantity", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "id" }, "name": { "type": "string", "example": "Id" } }, "type": "object" } }, "variant_values": { "description": "Available values for each variant dimension", "properties": { "variant0": { "type": "string", "example": "Size" }, "variant1": { "type": "string", "example": "Color" }, "variant2": { "type": "string", "example": "Material" } }, "type": "object" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-11-05 07:10:19" }, "category": { "description": "Associated category", "properties": { "id": { "type": "integer", "example": 2197 }, "platform_id": { "type": "integer", "example": 1 }, "taxonomy_id": { "type": "string", "example": "1027" }, "name": { "type": "string", "example": "Wall Decor" }, "origin_id": { "type": "integer", "example": null, "nullable": true } }, "type": "object" }, "created_by": { "description": "Creator information", "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "VN" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" }, "product_type": { "description": "Associated product type", "type": "object", "example": null, "nullable": true }, "resource_share": { "description": "Workspace resource sharing information", "properties": { "resourceable_id": { "type": "integer", "example": 6793 }, "total_users": { "type": "integer", "example": 1 }, "top_users": { "description": "List of users with access to this variant group", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 3 }, "count": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 2 }, "links": { "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/group-variants?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Variant Groups" ], "summary": "Create variant group", "description": "Create a new variant group with dimension labels and SKU combinations. Use dimension labels (variant0, variant1, variant2) to define product options like Size, Color, Material. Keys start from variant0 (0-indexed). Each variant combination must have unique values, price, and quantity. After creation, use GET /group-variants/{id} to retrieve full details for Deploy API.", "operationId": "createVariantGroup", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Variant group configuration with dimension labels and variants", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "category_id", "dimension_labels", "variants" ], "properties": { "name": { "description": "Unique variant group name per user", "type": "string", "maxLength": 255, "example": "T-Shirt Size & Color Variants" }, "category_id": { "description": "Category ID - Get from GET /categories?platform_id={platform_id}. Contains platform-specific taxonomy_id needed for deployment.", "type": "integer", "example": 2197 }, "product_type_id": { "description": "Product type ID (required for Amazon) - Get from GET /product-type?platform_id=3", "type": "integer", "example": 123, "nullable": true }, "dimension_labels": { "description": "Dimension labels define the variant attribute names. Keys: variant0 (required), variant1, variant2 (optional). Min 1, max 3 dimensions. Available attribute names can be found via GET /variants/attributes?platform_id={platform_id}", "required": [ "variant0" ], "properties": { "variant0": { "description": "First dimension label (required) - Use attribute names from GET /variants/attributes", "type": "string", "maxLength": 100, "example": "Size" }, "variant1": { "description": "Second dimension label (optional) - Use attribute names from GET /variants/attributes", "type": "string", "maxLength": 100, "example": "Color" }, "variant2": { "description": "Third dimension label (optional) - Use attribute names from GET /variants/attributes", "type": "string", "maxLength": 100, "example": "Material" } }, "type": "object" }, "variants": { "description": "Array of SKU combinations. Each variant must have matching dimension keys as dimension_labels, plus price and quantity.", "type": "array", "items": { "required": [ "variant0", "price", "quantity" ], "properties": { "variant0": { "description": "Value for variant0 dimension", "type": "string", "maxLength": 255, "example": "Small" }, "variant1": { "description": "Value for variant1 dimension (if defined in dimension_labels)", "type": "string", "maxLength": 255, "example": "Red" }, "variant2": { "description": "Value for variant2 dimension (if defined in dimension_labels)", "type": "string", "maxLength": 255, "example": "Cotton" }, "price": { "description": "SKU price (must be > 0.01)", "type": "number", "format": "float", "minimum": 0.01, "example": 19.99 }, "quantity": { "description": "SKU quantity (must be >= 0)", "type": "integer", "minimum": 0, "example": 100 } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Variant group created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created successfully" }, "data": { "properties": { "id": { "description": "New variant group ID - Use with GET /group-variants/{id} to get full details for Deploy API", "type": "integer", "example": 4029 }, "name": { "type": "string", "example": "T-Shirt Size & Color Variants" }, "variant_count": { "description": "Number of SKU combinations created", "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Business logic error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Entity already existed: T-Shirt Variants" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "The name field is required." } }, "dimension_labels": { "type": "array", "items": { "type": "string", "example": "Dimension label 'variant2' is defined but not used in variants." } }, "variants.0": { "type": "array", "items": { "type": "string", "example": "Duplicate variant combination found: Small - Red" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient workspace permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/group-variants/{id}": { "get": { "tags": [ "Variant Groups" ], "summary": "Get variant group details", "description": "Get complete variant group structure with SKUs, pricing, and inventory. **IMPORTANT**: You can copy the entire 'data' object from this response and use it as the 'variants' parameter in POST /deploy-product API.", "operationId": "getVariantDetails", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Variant group ID from GET /group-variants", "required": true, "schema": { "type": "integer", "example": 4028 } } ], "responses": { "200": { "description": "Variant details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Complete variant structure - Copy this entire object for Deploy API 'variants' parameter", "properties": { "id": { "description": "Variant group ID", "type": "integer", "example": 4028 }, "name": { "type": "string", "example": "Canvas Prints - Size & Frame Options" }, "is_active": { "type": "boolean", "example": true }, "headers": { "description": "Variant dimension definitions (e.g., Size, Color)", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "variant0" }, "name": { "type": "string", "example": "Type-Size" } }, "type": "object" } }, "variant_values": { "description": "Available values for each variant dimension. Structure: {dimension_name: {values: [...], is_customizable: boolean}}", "type": "object" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-01-15 10:30:45" }, "category": { "description": "Associated category", "properties": { "id": { "type": "integer", "example": 2197 }, "platform_id": { "type": "integer", "example": 1 }, "taxonomy_id": { "type": "string", "example": "1027" }, "name": { "type": "string", "example": "Wall Decor" }, "origin_id": { "type": "integer", "nullable": true } }, "type": "object" }, "product_type": { "description": "Associated product type", "type": "object", "nullable": true }, "childs": { "description": "SKU configurations", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 505660 }, "price": { "type": "number", "format": "float", "example": 15.99 }, "quantity": { "type": "integer", "example": 111 }, "variant0": { "type": "string", "example": "Canvas 24x36 inch" }, "variant1": { "type": "string", "example": "Black" }, "variant2": { "type": "string", "example": "Frame", "nullable": true } }, "type": "object" } }, "created_by": { "description": "Creator info", "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "US" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Variant group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Variant Groups" ], "summary": "Update variant group", "description": "Update variant group name and category. This updates the metadata of the variant group, not the SKU configurations (use PUT /group-variants/{id}/detail/{detail_id} to update individual SKUs).", "operationId": "updateVariantGroup", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Variant group ID", "required": true, "schema": { "type": "integer", "example": 4028 } } ], "requestBody": { "description": "Variant group update data", "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Variant group name (must be unique for your account)", "type": "string", "example": "Canvas Prints - Updated Name" }, "category_id": { "description": "Category ID to associate with this variant group (optional)", "type": "integer", "example": 2197, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Variant group updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Validation error - Name already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Entity already existed: Canvas Prints" } }, "type": "object" } } } }, "404": { "description": "Variant group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Variant Groups" ], "summary": "Delete variant group", "description": "Delete a variant group and all its SKU configurations. **Warning**: This action cannot be undone. Make sure the variant group is not being used in any active product deployments before deleting.", "operationId": "deleteVariantGroup", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Variant group ID to delete", "required": true, "schema": { "type": "integer", "example": 4028 } } ], "responses": { "200": { "description": "Variant group deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Deleted successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Variant group not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Variant group not found" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to delete this variant group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/group-variants/{id}/detail/{detail_id}": { "put": { "tags": [ "Variant Groups" ], "summary": "Update variant SKU detail", "description": "Update a single SKU configuration within a variant group. This allows you to change the variant values (e.g., size, color), price, and quantity for a specific SKU. **Note**: The variant field names (variant0, variant1, etc.) are dynamic based on the variant group's structure.", "operationId": "updateVariantDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Variant group ID", "required": true, "schema": { "type": "integer", "example": 4028 } }, { "name": "detail_id", "in": "path", "description": "Variant detail (SKU) ID from the 'childs' array in GET /group-variants/{id}", "required": true, "schema": { "type": "integer", "example": 505660 } } ], "requestBody": { "description": "SKU update data. The variant fields (variant0, variant1, etc.) depend on your variant group structure. Check GET /group-variants/{id} response to see which fields are required.", "required": true, "content": { "application/json": { "schema": { "required": [ "variant0" ], "properties": { "variant0": { "description": "First variant dimension value (e.g., Size). Field name varies by variant group.", "type": "string", "example": "Canvas 24x36 inch" }, "variant1": { "description": "Second variant dimension value (e.g., Color). Only if variant group has 2+ dimensions.", "type": "string", "example": "Black", "nullable": true }, "variant2": { "description": "Third variant dimension value. Only if variant group has 3+ dimensions.", "type": "string", "example": "Frame", "nullable": true }, "price": { "description": "SKU price (defaults to 0 if not provided)", "type": "number", "format": "float", "example": 19.99, "nullable": true }, "quantity": { "description": "SKU inventory quantity (defaults to 0 if not provided)", "type": "integer", "example": 150, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Variant detail updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated successfully" }, "data": { "type": "object", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Validation error - Missing required variant fields", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The Size(variant0) field is required." } }, "type": "object" } } } }, "404": { "description": "Variant group or detail not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/deploy-product": { "post": { "tags": [ "Product Deployment" ], "summary": "Deploy product to e-commerce platform", "description": "Creates or updates a product listing on connected e-commerce platforms. Supported platforms: Etsy, TikTok, Amazon. Deployment happens asynchronously (5-15 seconds). Track deployment: View all requests via GET /report-product-deploy or detailed progress via GET /deploy-requests/{request_id}/progress. For detailed guide, see [Complete Deployment Guide](https://developer.dodgeprint.com/docs/guides/deploy-product).", "operationId": "deployProduct", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Product deployment configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "site_id", "type", "selected", "variants" ], "properties": { "type": { "description": "Deployment type: insert (new listing), update (complete update), update_partial (price/inventory only), update_variant (variants only), update_image (images only), update_video (videos only), update_digital (digital files), delete (remove listing)", "type": "string", "enum": [ "insert", "update", "update_partial", "update_variant", "update_image", "update_video", "update_digital", "delete" ], "example": "insert" }, "site_id": { "description": "Target site ID - Get from GET /sites (Note: Only Etsy, TikTok, and Amazon sites are supported)", "type": "integer", "example": 6529 }, "content_id": { "description": "Content template ID (required if not saving draft) - Get from GET /contents", "type": "integer", "example": 2414 }, "selected": { "description": "Array of product IDs to deploy (required) - Cannot be empty", "type": "array", "items": { "type": "integer", "example": 1635986 } }, "is_save_draft": { "description": "If true, saves as draft without deploying (skips most validations)", "type": "boolean", "example": false }, "variants": { "description": "Complete variant structure from GET /group-variants/{id}. Copy entire response data object. To create variant groups: POST /group-variants (requires category_id from GET /categories and optional product_type_id from GET /product-type for Amazon).", "required": [ "id", "headers", "childs" ], "properties": { "id": { "description": "Variant group ID from GET /group-variants/{id}", "type": "integer", "example": 4028 }, "headers": { "description": "Variant option definitions (from GET /group-variants/{id})", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "variant0" }, "name": { "type": "string", "example": "Type-Size" } }, "type": "object" } }, "variant_values": { "description": "Available values (optional, can be empty array)", "type": "array", "items": { "type": "object" } }, "category": { "description": "Category info from variant group - Contains platform taxonomy_id for deployment. Category ID originally from GET /categories?platform_id={platform_id}", "properties": { "id": { "description": "Category ID from GET /categories", "type": "integer", "example": 2197 }, "taxonomy_id": { "description": "Platform-specific taxonomy ID (Etsy, Amazon, TikTok)", "type": "string", "example": "1027" }, "origin_id": { "type": "integer", "nullable": true } }, "type": "object" }, "childs": { "description": "SKU configurations from GET /group-variants/{id}", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 505660 }, "variant0": { "type": "string", "example": "Canvas 24x36 inch" }, "variant1": { "type": "string", "example": "Black" }, "variant2": { "type": "string", "example": "Frame" }, "price": { "type": "number", "format": "float", "example": 15.99 }, "quantity": { "type": "integer", "example": 111 } }, "type": "object" } } }, "type": "object" }, "shipping_profile_id": { "description": "Required for Etsy physical products - Get 'id' field from GET /shipping-profiles", "type": "integer", "example": 6811 }, "category": { "description": "Category ID (optional if provided in variants.category) - Get from variants or categories API", "type": "integer", "example": 2197 }, "return_policy_id": { "description": "Required for Etsy physical products - Get 'id' field from GET /return-policies?site_id={site_id}", "type": "integer", "example": 5 }, "tags": { "description": "Product tag names (max 13 for Etsy) - Get 'name' field from GET /tags", "type": "array", "items": { "type": "string", "example": "Bruce Watson" } }, "shop_section_id": { "description": "Etsy shop section ID (optional) - Get 'id' field from GET /sections?site_id={site_id}", "type": "integer", "example": 28745001 }, "personalization_id": { "description": "Personalization template ID for Etsy (optional) - Get from GET /personalizations", "type": "integer", "example": 1 }, "tag_id": { "description": "Tag template ID (optional) - Get from GET /tag-templates", "type": "integer", "example": 1 }, "tag_by_product": { "description": "Use product-specific tags instead of template", "type": "boolean", "example": false }, "listing_type": { "description": "Product listing type", "type": "string", "enum": [ "physical", "digital" ], "example": "physical" }, "price": { "description": "Default price (used if not in variants)", "type": "number", "format": "float", "example": 45.99 }, "quantity": { "description": "Default quantity (used if not in variants)", "type": "integer", "example": 999 }, "when_made": { "description": "Etsy: When was item made", "type": "string", "enum": [ "made_to_order", "2020_2025", "2010_2019", "before_2010" ], "example": "made_to_order" }, "who_made": { "description": "Etsy: Who made this item", "type": "string", "enum": [ "i_did", "collective", "someone_else" ], "example": "i_did" }, "is_supply": { "description": "Etsy: Is this a craft supply", "type": "boolean", "example": false }, "is_draft": { "description": "Create as draft listing (not published)", "type": "boolean", "example": false }, "is_shipping_by_product": { "description": "Use product-specific shipping profile", "type": "boolean", "example": false }, "warehouses": { "description": "Required for TikTok - Warehouse identifier", "type": "string", "example": "WAREHOUSE_US" }, "product_attributes": { "description": "Amazon: Product attributes", "type": "array", "items": { "type": "object" } }, "product_definitions": { "description": "Required for Amazon - Product definition type", "type": "string", "example": "SHIRT" }, "bullet_point": { "description": "Required for Amazon - Bullet point template identifier", "type": "string", "example": "bullet_template_1" }, "product_type": { "description": "Required for Amazon - Product type", "type": "string", "example": "SHIRT" }, "generic_keyword": { "description": "Amazon: Generic keywords for search", "type": "string", "example": "t-shirt casual wear" }, "shipping_package_template_id": { "description": "Amazon: Shipping package template ID", "type": "integer", "example": 1 }, "brands": { "description": "Amazon: Brand information", "type": "array", "items": { "properties": { "origin_id": { "type": "string", "example": "BRAND123" } }, "type": "object" } }, "processing_profile_id": { "description": "Processing time profile ID", "type": "integer", "example": 1 }, "url_s3": { "description": "S3 URL for product images", "type": "string", "example": "https://s3.amazonaws.com/bucket/product-images" }, "description_deploy": { "description": "Deployment description or notes", "type": "string", "example": "Additional deployment notes" } }, "type": "object" } } } }, "responses": { "200": { "description": "Product deployed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Product deployment initiated successfully" }, "data": { "properties": { "request_id": { "description": "Deploy request ID - Use with GET /report-product-deploy to list all requests or GET /deploy-requests/{request_id}/progress for detailed tracking", "type": "integer", "example": 136001 }, "product_on_site_id": { "description": "Dodgeprint's internal product listing ID", "type": "integer", "example": 123456 }, "status": { "description": "Deployment status", "type": "string", "example": "pending" }, "estimated_time": { "description": "Estimated completion time", "type": "string", "example": "5-15 seconds" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or unsupported platform", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Deploy to Shopify is not supported yet. Supported platforms: Etsy, TikTok, Amazon" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated - Invalid or missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invalid workspace or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/product-on-sites/bulk-duplicate": { "post": { "tags": [ "Products on Site" ], "summary": "Bulk duplicate products on site", "description": "Duplicate multiple products within the same site. Products are duplicated with 'editing' status. Maximum 100 products per request.", "operationId": "bulkDuplicateProductOnSite", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_on_site_ids" ], "properties": { "product_on_site_ids": { "description": "Array of product on site IDs to duplicate (min: 1, max: 100)", "type": "array", "items": { "type": "integer", "example": 870013 } }, "sku_mapping": { "description": "Optional mapping of source product ID to new SKU. Keys are source product_on_site_ids, values are the desired SKUs for duplicated products.", "type": "object", "example": { "870013": "NEW-SKU-001", "870014": "NEW-SKU-002" }, "nullable": true, "additionalProperties": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Products duplicated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "duplicated": { "description": "List of successfully duplicated products", "type": "array", "items": { "properties": { "id": { "description": "New product ID", "type": "integer", "example": 1256834 }, "source_id": { "description": "Source product ID", "type": "integer", "example": 870013 }, "sku_origin": { "description": "SKU of duplicated product", "type": "string", "example": "NEW-SKU-001" } }, "type": "object" } }, "failed": { "description": "List of failed duplications with error details", "type": "array", "items": { "properties": { "product_on_site_id": { "type": "integer", "example": 870015 }, "error": { "type": "string", "example": "Product not found" } }, "type": "object" } }, "total": { "description": "Total number of products requested", "type": "integer", "example": 5 }, "success_count": { "description": "Number of successfully duplicated products", "type": "integer", "example": 4 }, "failed_count": { "description": "Number of failed duplications", "type": "integer", "example": 1 } }, "type": "object" }, "meta": { "type": "array", "items": {}, "example": [] } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 422 }, "message": { "type": "string", "example": "The product_on_site_ids field is required." }, "errors": { "properties": { "product_on_site_ids": { "type": "array", "items": { "type": "string", "example": "The product_on_site_ids field is required." } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/product-on-sites/{id}": { "get": { "tags": [ "Products on Site" ], "summary": "Get product on site detail", "description": "Get comprehensive details of a specific product deployed on an e-commerce site, including images, variants, personalization, and platform-specific fields", "operationId": "getProductOnSiteDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-ID" }, { "name": "id", "in": "path", "description": "Product on site ID", "required": true, "schema": { "type": "integer", "example": 870013 } } ], "responses": { "200": { "description": "Product on site detail retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "id": { "type": "integer", "example": 870013 }, "product_origin_id": { "type": "string", "example": "4319305183" }, "taxonomy_id": { "type": "integer", "example": 1234, "nullable": true }, "category_id": { "type": "integer", "example": 2197, "nullable": true }, "platform_id": { "description": "Platform ID (1=Etsy, 4=TikTok, 5=Amazon)", "type": "integer", "example": 1 }, "shipping_profile_id": { "description": "Platform origin shipping profile ID (matches deploy request format)", "type": "integer", "example": 100, "nullable": true }, "return_policy_id": { "description": "Platform origin return policy ID (matches deploy request format)", "type": "integer", "example": 200, "nullable": true }, "group_variant_id": { "type": "integer", "example": 456, "nullable": true }, "shop_section_id": { "description": "Etsy shop section ID", "type": "integer", "example": 300, "nullable": true }, "content_id": { "description": "Etsy content/template ID", "type": "integer", "example": 150, "nullable": true }, "materials": { "description": "Product materials (currently not stored, returns empty array)", "type": "array", "items": { "type": "string" } }, "sku": { "type": "string", "example": "500000870013" }, "sku_origin": { "type": "string", "example": "300530455353" }, "custom_label_1": { "type": "string", "example": null, "nullable": true }, "custom_label_keyword": { "type": "string", "example": null, "nullable": true }, "title": { "type": "string", "example": "Beautiful Handmade Product" }, "reported": { "type": "integer", "example": 0 }, "is_unpublish": { "type": "integer", "example": 0 }, "is_on_site": { "type": "integer", "example": 1 }, "is_making_data": { "type": "integer", "example": 0 }, "type": { "type": "string", "enum": [ "physical", "digital", "both" ], "example": "physical" }, "status": { "type": "string", "enum": [ "active", "inactive", "draft" ], "example": "active" }, "total_variants": { "type": "integer", "example": 4 }, "price": { "type": "number", "example": 19.99, "nullable": true }, "quantity": { "type": "integer", "example": 100, "nullable": true }, "combined_with": { "type": "string", "example": null, "nullable": true }, "is_parent": { "type": "integer", "example": 0 }, "is_combine": { "type": "integer", "example": 0 }, "is_replace_digital": { "type": "boolean", "example": false, "nullable": true }, "promotion": { "type": "string", "example": null, "nullable": true }, "created_at": { "type": "string", "format": "datetime", "example": "2025-06-12 00:07:17" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-06-14 02:25:58" }, "images": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "position": { "type": "integer", "example": 0 }, "url": { "type": "string", "example": "https://s3.amazonaws.com/bucket/image.jpg" } }, "type": "object" } }, "videos": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Product Demo" }, "url": { "type": "string", "example": "https://s3.amazonaws.com/bucket/video.mp4" }, "status": { "type": "string", "example": "ready" }, "type": { "type": "string", "example": "video" }, "file_size": { "type": "integer", "example": 1024000 } }, "type": "object" } }, "digitals": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "file_name": { "type": "string", "example": "digital-product.pdf" }, "url": { "type": "string", "example": "https://s3.amazonaws.com/bucket/file.pdf" } }, "type": "object" } }, "description": { "properties": { "title": { "type": "string", "example": "Product Description Title" }, "content": { "type": "string", "example": "

Full HTML description of the product...

" } }, "type": "object" }, "personalization": { "properties": { "name": { "type": "string", "example": "Custom Text" }, "personalization_instructions": { "type": "string", "example": "Enter your text here" }, "personalization_char_count_max": { "type": "integer", "example": 50 }, "personalization_is_required": { "type": "boolean", "example": false } }, "type": "object" }, "variants": { "description": "Product variants in simplified format matching deploy V2 request. Only available when using inline variants (not group_variant_id)", "type": "array", "items": { "properties": { "price": { "description": "Variant price", "type": "number", "example": 19.99 }, "quantity": { "description": "Stock quantity", "type": "integer", "example": 100 }, "sku": { "description": "Variant SKU", "type": "string", "example": "VARIANT-SKU", "nullable": true }, "options": { "description": "Variant options (max 2 dimensions)", "type": "array", "items": { "properties": { "name": { "description": "Option name (e.g., Size, Color)", "type": "string", "example": "Size" }, "value": { "description": "Option value (e.g., Small, Red)", "type": "string", "example": "Small" } }, "type": "object" } } }, "type": "object" } }, "when_made": { "description": "Etsy: When the item was made", "type": "string", "example": "made_to_order", "nullable": true }, "who_made": { "description": "Etsy: Who made the item", "type": "string", "example": "i_did", "nullable": true }, "is_supply": { "description": "Etsy: Whether item is a craft supply", "type": "boolean", "example": false, "nullable": true }, "processing_profile_id": { "description": "Etsy: Processing/production profile ID", "type": "string", "example": "1742858595", "nullable": true }, "bullet_points": { "description": "Amazon: Product bullet points", "type": "array", "items": { "type": "string", "example": "Premium quality cotton" }, "nullable": true }, "shipping_package_template_id": { "description": "Amazon: Shipping package template", "type": "string", "example": "TEMPLATE123", "nullable": true }, "generic_keywords": { "description": "Amazon: Generic search keywords", "type": "string", "example": "keyword1 keyword2", "nullable": true }, "product_definitions": { "description": "Amazon: Product type definitions", "properties": { "key": { "type": "string", "example": "value" } }, "type": "object", "nullable": true }, "summary_report": { "properties": { "views": { "type": "string", "example": "1250" }, "favorers": { "type": "string", "example": "48" }, "sales": { "type": "string", "example": "12" }, "conversion_rate": { "type": "string", "example": "0.96" } }, "type": "object" }, "site": { "properties": { "id": { "type": "integer", "example": 5000 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Etsy Shop" }, "is_destination": { "type": "integer", "example": 1 }, "is_active": { "type": "integer", "example": 1 } }, "type": "object" }, "tags": { "description": "Product tags as simple string array (matches deploy request format)", "type": "array", "items": { "type": "string", "example": "handmade" } }, "resource_quota": { "properties": { "is_using_slot": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": {}, "example": [] } }, "type": "object" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Product not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Insufficient permissions" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/product-on-sites": { "get": { "tags": [ "Products on Site" ], "summary": "Get list of products on site", "operationId": "17855b0455f5d6667063e48fa687cb1e", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-ID" }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page (default: 15)", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "site_id", "in": "query", "description": "Filter by site ID", "required": false, "schema": { "type": "integer", "example": 6529 } }, { "name": "status", "in": "query", "description": "Filter by product status", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "draft" ], "example": "active" } } ], "responses": { "200": { "description": "Products on site retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 870013 }, "sku": { "type": "string", "example": "500000870013" }, "sku_origin": { "type": "string", "example": "300530455353" }, "custom_label_1": { "type": "string", "example": null, "nullable": true }, "custom_label_keyword": { "type": "string", "example": null, "nullable": true }, "title": { "type": "string", "example": "Dunkare Dunk Low Strawberry Waffle Unisex Tshirt, Hoodie, Sweater, Bomber, Snake Trust No One Drip Shirt In Sport To Match Sneaker" }, "reported": { "type": "integer", "example": 0 }, "is_unpublish": { "type": "integer", "example": 1 }, "is_on_site": { "type": "integer", "example": 1 }, "is_making_data": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "format": "datetime", "example": "2025-06-12 00:07:17" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-06-14 02:25:58" }, "thumbnail": { "type": "string", "example": "https://igbmerch-cdn.sgp1.cdn.digitaloceanspaces.com/concordart/5000/il-fullxfull6933433812-4lq8_1749730084.jpg" }, "summary_report": { "properties": { "views": { "type": "string", "example": "0" }, "favorers": { "type": "string", "example": "0" }, "sales": { "type": "string", "example": "0" }, "conversion_rate": { "type": "string", "example": "0.00" } }, "type": "object" }, "product_origin_id": { "type": "string", "example": "4319305183" }, "in_feed": { "type": "integer", "example": 0 }, "type": { "type": "string", "example": "physical" }, "promotion": { "type": "string", "example": null, "nullable": true }, "status": { "type": "string", "example": "draft" }, "price": { "type": "number", "example": null, "nullable": true }, "quantity": { "type": "integer", "example": null, "nullable": true }, "total_variants": { "type": "integer", "example": 0 }, "combined_with": { "type": "string", "example": null, "nullable": true }, "is_parent": { "type": "integer", "example": 0 }, "is_combine": { "type": "integer", "example": 0 }, "group_item": { "type": "string", "example": null, "nullable": true }, "group_variant_id": { "type": "string", "example": null, "nullable": true }, "site": { "properties": { "id": { "type": "integer", "example": 5000 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "TereiaClothes" }, "is_destination": { "type": "integer", "example": 1 }, "is_active": { "type": "integer", "example": 0 }, "site_is_death": { "type": "integer", "example": 0 }, "is_limit": { "type": "integer", "example": 0 }, "is_crawl": { "type": "integer", "example": 0 }, "is_sync_admin": { "type": "integer", "example": 1 }, "is_display": { "type": "integer", "example": 1 }, "is_add_watermark": { "type": "integer", "example": 0 }, "reported": { "type": "string", "example": null, "nullable": true }, "last_sync_reported": { "type": "string", "example": null, "nullable": true }, "receipt_new": { "type": "integer", "example": 0 }, "receipt_completed": { "type": "integer", "example": 6 }, "last_sync_receipts": { "type": "string", "format": "datetime", "example": "2025-05-21 07:22:12" }, "before_sync": { "type": "integer", "example": 0 }, "after_sync": { "type": "integer", "example": 0 }, "last_modified_timestamp": { "type": "string", "format": "datetime", "example": "2025-05-21 02:00:38" }, "finished_sync_at": { "type": "string", "format": "datetime", "example": "2025-06-12 21:35:59" }, "last_sync_interacts": { "type": "string", "example": null, "nullable": true }, "last_sync_receipt_transactions": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "tags": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 3374 }, "product_on_site_id": { "type": "integer", "example": 870013 }, "name": { "type": "string", "example": "unisex" } }, "type": "object" } } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 66 }, "count": { "type": "integer", "example": 10 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 7 }, "links": { "properties": { "next": { "type": "string", "example": "http://localhost:8080/api/v1/product-on-sites?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": {}, "example": [] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Insufficient permissions" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get order details", "description": "Get detailed information about a specific order including items, shipment, and status history", "operationId": "getOrderDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Order ID", "required": true, "schema": { "type": "integer", "example": 383364 } } ], "responses": { "200": { "description": "Order details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "description": "Complete order details with additional fields", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Order" }, { "properties": { "status_histories": { "description": "Order status change history (currently empty)", "type": "array", "items": { "type": "object" } }, "status": { "description": "Status details object", "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Completed" } }, "type": "object" }, "group_user": { "description": "Users assigned to this order", "type": "string", "example": "John Doe, Jane Smith" } }, "type": "object" } ] } }, "type": "object" } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/shipment-carriers": { "get": { "tags": [ "Orders" ], "summary": "List shipment carriers", "description": "Get list of available shipment carriers for order fulfillment", "operationId": "listShipmentCarriers", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "responses": { "200": { "description": "Carriers retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Carriers retrieved successfully." }, "data": { "description": "Array of shipment carriers", "type": "array", "items": { "properties": { "id": { "description": "Carrier ID", "type": "integer", "example": 1 }, "logo": { "description": "Carrier logo URL", "type": "string", "example": "https://cdn-images.canawan.com/shipresolve/carrier-logo/1.png", "nullable": true }, "name": { "description": "Carrier name", "type": "string", "example": "139Express" }, "country_iso": { "description": "Country ISO code", "type": "string", "example": "CN" }, "code": { "description": "Carrier code", "type": "string", "example": "190135" }, "url": { "description": "Carrier website URL", "type": "string", "example": "http://www.139express.com/" }, "telephone": { "description": "Contact phone number", "type": "string", "example": "+86 4000-666-139", "nullable": true }, "email": { "description": "Contact email", "type": "string", "example": "contact@carrier.com", "nullable": true }, "created_at": { "description": "Creation timestamp in ISO 8601 format", "type": "string", "format": "date-time", "example": "2023-06-12T07:15:56.000000Z" }, "updated_at": { "description": "Last update timestamp in ISO 8601 format", "type": "string", "format": "date-time", "example": "2025-05-19T06:04:35.000000Z" }, "deleted_at": { "description": "Deletion timestamp in ISO 8601 format", "type": "string", "format": "date-time", "example": null, "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "Get list of orders with filtering and pagination options", "operationId": "listOrders", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "site_id", "in": "query", "description": "**Required**. Site ID for workspace resource sharing", "required": true, "schema": { "type": "integer", "example": 7005 } }, { "$ref": "#/components/parameters/Page" }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "example": 15 } }, { "name": "status_id", "in": "query", "description": "Filter by order status ID. Available statuses: 1=Awaiting Payment, 2=Awaiting Fulfillment, 3=Awaiting Shipment, 4=Shipped, 5=Completed, 6=Canceled, 7=Refunded, 8=Awaiting Verification, 9=Partial Refunded", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "example": 5 } } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Orders retrieved successfully." }, "data": { "description": "Array of orders with complete details", "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "paging": { "description": "Pagination information", "properties": { "total": { "description": "Total number of orders", "type": "integer", "example": 9 }, "count": { "description": "Number of items in current page", "type": "integer", "example": 1 }, "per_page": { "description": "Results per page", "type": "integer", "example": 1 }, "current_page": { "description": "Current page number", "type": "integer", "example": 1 }, "total_pages": { "description": "Total number of pages", "type": "integer", "example": 9 }, "links": { "description": "Pagination navigation links", "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/orders?page=2", "nullable": true } }, "type": "object" } }, "type": "object" }, "meta": { "description": "Additional metadata", "properties": { "summary_count": { "description": "Order count summary by status", "type": "array", "items": { "properties": { "status_id": { "type": "integer", "example": 5 }, "total": { "type": "integer", "example": 9 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invalid workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/report-product-deploy/{id}": { "get": { "tags": [ "Product Deployment" ], "summary": "Get deployment request detail", "description": "Get detailed information about a specific deployment request by ID, including all status, progress, and related information.", "operationId": "getDeployReportDetail", "parameters": [ { "name": "id", "in": "path", "description": "Request deploy ID", "required": true, "schema": { "type": "integer", "example": 136001 } } ], "responses": { "200": { "description": "Deployment request detail retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "id": { "description": "Request deploy ID", "type": "integer", "example": 136001 }, "status": { "properties": { "key": { "type": "string", "example": "Finished" }, "name": { "type": "string", "example": "Finished" }, "text_color": { "type": "string", "example": "#1bc5bd" }, "background_color": { "type": "string", "example": "#c9f7f5" }, "tooltip": { "type": "string", "nullable": true } }, "type": "object" }, "total_product": { "description": "Total products in request", "type": "integer", "example": 10 }, "total_completed": { "description": "Successfully deployed", "type": "integer", "example": 8 }, "total_failed": { "description": "Failed deployments", "type": "integer", "example": 1 }, "total_in_transit": { "description": "Currently deploying", "type": "integer", "example": 0 }, "total_pending": { "description": "Waiting to deploy", "type": "integer", "example": 1 }, "process": { "description": "Progress ratio", "type": "string", "example": "9/10" }, "type": { "description": "Deployment type", "type": "string", "example": "insert" }, "started_at": { "type": "string", "format": "datetime", "example": "2025-10-22 08:14:14", "nullable": true }, "finished_at": { "type": "string", "format": "datetime", "example": "2025-10-22 08:20:30", "nullable": true }, "created_at": { "type": "string", "format": "datetime", "example": "2025-10-22 08:14:14" }, "is_auto_deploy": { "type": "boolean", "example": false }, "is_pause": { "description": "1=can pause, 0=cannot", "type": "integer", "example": 1 }, "is_cancel": { "description": "1=can cancel, 0=cannot", "type": "integer", "example": 1 }, "is_sync": { "description": "1=can sync, 0=cannot", "type": "integer", "example": 1 }, "is_run": { "description": "1=can run, 0=cannot", "type": "integer", "example": 0 }, "is_warning": { "description": "1=has warning, 0=normal", "type": "integer", "example": 0 }, "warning_at": { "type": "string", "format": "datetime", "example": null, "nullable": true }, "last_update_limited": { "type": "string", "format": "datetime", "example": null, "nullable": true }, "reason": { "description": "Error message if failed", "type": "string", "example": "Error: Product already deployed", "nullable": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "user@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" }, "site": { "properties": { "id": { "type": "integer", "example": 6529 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "InkspireC" }, "is_active": { "type": "integer", "example": 1 }, "site_is_death": { "description": "1=suspended, 0=active", "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invalid workspace or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request deploy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "WorkspaceAuth": [] } ] } }, "/v1/report-product-deploy": { "get": { "tags": [ "Product Deployment" ], "summary": "List deployment history", "description": "Get paginated list of product deployment requests with their status, progress, and details. Use this to track all your deployment requests.", "operationId": "listDeployReports", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "platform_id", "in": "query", "description": "Filter by platform", "required": false, "schema": { "description": "1=Etsy, 4=TikTok, 5=Amazon", "type": "integer", "enum": [ 1, 4, 5 ], "example": 1 } }, { "name": "site_id", "in": "query", "description": "Filter by specific site", "required": false, "schema": { "type": "integer", "example": 6529 } }, { "name": "status", "in": "query", "description": "Filter by deployment status", "required": false, "schema": { "type": "string", "enum": [ "Initial", "Open", "Processing", "Finished", "Canceled", "Paused", "Making_Data" ], "example": "Finished" } }, { "name": "type", "in": "query", "description": "Filter by deployment type", "required": false, "schema": { "type": "string", "enum": [ "insert", "update", "update_partial", "update_variant", "update_image", "update_video", "update_digital", "delete" ], "example": "insert" } }, { "name": "search", "in": "query", "description": "Search keyword", "required": false, "schema": { "type": "string", "example": "InkspireC" } }, { "name": "date_from", "in": "query", "description": "Filter from date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-10-01" } }, { "name": "date_to", "in": "query", "description": "Filter to date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-10-31" } }, { "name": "sort", "in": "query", "description": "Sort field (prefix with - for descending)", "required": false, "schema": { "type": "string", "example": "-created_at" } } ], "responses": { "200": { "description": "Deployment reports retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Request deploy ID", "type": "integer", "example": 147528 }, "status": { "properties": { "key": { "type": "string", "example": "Finished" }, "text_color": { "type": "string", "example": "#1bc5bd" }, "background_color": { "type": "string", "example": "#c9f7f5" }, "name": { "type": "string", "example": "Finished" }, "tooltip": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "total_product": { "description": "Total products in request", "type": "integer", "example": 1 }, "total_completed": { "description": "Successfully deployed", "type": "integer", "example": 0 }, "total_failed": { "description": "Failed deployments", "type": "integer", "example": 0 }, "total_in_transit": { "description": "Currently deploying", "type": "integer", "example": 0 }, "total_pending": { "description": "Waiting to deploy", "type": "integer", "example": 0 }, "started_at": { "type": "string", "format": "datetime", "example": null, "nullable": true }, "finished_at": { "type": "string", "format": "datetime", "example": null, "nullable": true }, "process": { "description": "Progress ratio", "type": "string", "example": "/" }, "type": { "description": "Deployment type", "type": "string", "example": "insert" }, "is_auto_deploy": { "type": "boolean", "example": false }, "is_pause": { "description": "1=can pause, 0=cannot", "type": "integer", "example": 0 }, "is_cancel": { "description": "1=can cancel, 0=cannot", "type": "integer", "example": 0 }, "is_sync": { "description": "1=can sync, 0=cannot", "type": "integer", "example": 0 }, "is_run": { "description": "1=can run, 0=cannot", "type": "integer", "example": 0 }, "last_update_limited": { "type": "string", "example": null, "nullable": true }, "warning_at": { "type": "string", "example": null, "nullable": true }, "is_warning": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "format": "datetime", "example": "2025-11-11 07:45:17" }, "created_by": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "VN" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" }, "site": { "properties": { "id": { "type": "integer", "example": 6529 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "InkspireC" }, "is_destination": { "type": "integer", "example": 1 }, "is_active": { "type": "integer", "example": 1 }, "site_is_death": { "description": "1=suspended, 0=active", "type": "integer", "example": 0 }, "is_limit": { "type": "integer", "example": 0 }, "is_crawl": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 20 }, "count": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 10 }, "links": { "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/report-product-deploy?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invalid workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/order-shipments": { "post": { "tags": [ "Shipments" ], "summary": "Create order shipment", "description": "Create a shipment record for an order with tracking information", "operationId": "createOrderShipment", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Shipment information", "required": true, "content": { "application/json": { "schema": { "required": [ "order_id", "carrier_id", "tracking_number" ], "properties": { "order_id": { "description": "Order ID", "type": "integer", "example": 165329 }, "carrier_id": { "description": "Carrier ID from shipment-carriers API", "type": "integer", "example": 1 }, "tracking_number": { "description": "Tracking number", "type": "string", "example": "1Z999AA10123456784" }, "shipping_date": { "description": "Shipping date", "type": "string", "format": "date", "example": "2025-01-20" }, "notes": { "description": "Additional notes", "type": "string", "example": "Handle with care" } }, "type": "object" } } } }, "responses": { "200": { "description": "Shipment created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Shipment created successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 123 }, "order_id": { "type": "integer", "example": 165329 }, "carrier_id": { "type": "integer", "example": 1 }, "tracking_number": { "type": "string", "example": "1Z999AA10123456784" }, "status": { "type": "string", "example": "in_transit" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-01-20 10:30:45" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/authenticate-site": { "post": { "tags": [ "Sites" ], "summary": "Get OAuth authentication URL for connecting a new site", "description": "Generate OAuth authorization URL to connect e-commerce platforms. Supports Etsy, TikTok, and Amazon. Returns URL for user to complete platform authentication. State is signed with JWT for security and expires in 15 minutes.", "operationId": "authenticateSite", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "description": "Platform authentication parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "platform_id" ], "properties": { "platform_id": { "description": "Platform to authenticate (1=Etsy, 4=TikTok, 5=Amazon)", "type": "integer", "enum": [ 1, 4, 5 ], "example": 1 }, "redirect_url": { "description": "Custom redirect URL after successful authentication. Supported by Etsy only. Amazon does not support custom redirects.", "type": "string", "example": "https://myapp.com/oauth/callback" }, "authorization_url": { "description": "TikTok only: Authorization URL from TikTok Seller Center", "type": "string", "example": "https://services.tiktokshop.com/open/authorize?service_id=XXX" }, "custom_field_value": { "description": "TikTok only: Custom redirect URL or metadata (format: URL;metadata)", "type": "string", "example": "https://myapp.com/callback;utm_source=tiktok" }, "is_sync_admin": { "description": "Internal use: Sync with admin hub", "type": "string", "example": null }, "group_site_id": { "description": "Internal use: Group site identifier", "type": "integer", "example": null } }, "type": "object" } } } }, "responses": { "200": { "description": "Authorization URL generated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "url": { "description": "OAuth authorization URL. Redirect user to this URL to complete authentication. After successful authentication, user will be redirected to custom redirect_url with site_id parameter (e.g. https://myapp.com/callback?site_id=6529).", "type": "string", "example": "https://www.etsy.com/oauth/connect?client_id=xxx&state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters or Amazon custom redirect not supported", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Amazon OAuth does not support custom redirect URLs. Please use the default redirect flow." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invalid workspace session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The platform_id field is required." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sites/{id}": { "get": { "tags": [ "Sites" ], "summary": "Get site details", "description": "Get detailed information about a specific connected e-commerce site including sync status, product counts, and quota information", "operationId": "getSiteDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Site ID", "required": true, "schema": { "type": "integer", "example": 6529 } } ], "responses": { "200": { "description": "Site details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "id": { "description": "Site ID", "type": "integer", "example": 6529 }, "platform_id": { "description": "Platform identifier (1=Etsy, 3=Source, 4=TikTok, 5=Amazon, 6=Shopify)", "type": "integer", "example": 1 }, "name": { "description": "Site name", "type": "string", "example": "InkspireC" }, "is_destination": { "description": "Whether site is a destination for deployments (1=yes, 0=no)", "type": "integer", "example": 1 }, "is_active": { "description": "Site active status (1=active, 0=inactive)", "type": "integer", "example": 1 }, "site_is_death": { "description": "Site death status (1=dead, 0=alive)", "type": "integer", "example": 0 }, "is_limit": { "description": "Site limit status (1=limited, 0=not limited)", "type": "integer", "example": 0 }, "is_crawl": { "description": "Crawl enabled status (1=enabled, 0=disabled)", "type": "integer", "example": 1 }, "is_sync_admin": { "description": "Admin sync status", "type": "integer", "example": 0 }, "is_display": { "description": "Display status", "type": "integer", "example": 1 }, "is_add_watermark": { "description": "Watermark enabled (1=yes, 0=no)", "type": "integer", "example": 0 }, "watermark_url": { "description": "URL to watermark image", "type": "string", "example": "https://cdn.dodgeprint.com/concordart/watermarks/6529.png" }, "is_insufficient_scope": { "description": "Insufficient OAuth scope status", "type": "integer", "example": 0 }, "reported": { "description": "Last reported timestamp", "type": "string", "example": null, "nullable": true }, "last_sync_reported": { "description": "Last sync reported timestamp", "type": "string", "example": null, "nullable": true }, "receipt_new": { "description": "Count of new receipts", "type": "integer", "example": 0 }, "receipt_completed": { "description": "Count of completed receipts", "type": "integer", "example": 0 }, "last_sync_receipts": { "description": "Last receipts sync timestamp", "type": "string", "example": null, "nullable": true }, "before_sync": { "description": "Before sync count", "type": "integer", "example": 0 }, "after_sync": { "description": "After sync count", "type": "integer", "example": 0 }, "last_modified_timestamp": { "description": "Last modified timestamp", "type": "string", "example": null, "nullable": true }, "finished_sync_at": { "description": "Finished sync timestamp", "type": "string", "format": "datetime", "example": "2025-10-22 03:05:31" }, "last_sync_interacts": { "description": "Last sync interactions timestamp", "type": "string", "example": null, "nullable": true }, "last_sync_receipt_transactions": { "description": "Last sync receipt transactions timestamp", "type": "string", "example": null, "nullable": true }, "site_url": { "description": "URL to the e-commerce site", "type": "string", "example": "https://www.etsy.com/shop/InkspireC" }, "sync_receipts": { "description": "Receipts sync status", "type": "string", "example": "done" }, "status": { "description": "Site sync status", "type": "string", "example": "is_sync" }, "custom_labels": { "description": "Custom labels sync status", "type": "string", "example": "done" }, "total_products": { "description": "Breakdown of product counts by status", "properties": { "active": { "description": "Active products count", "type": "integer", "example": 7 }, "inactive": { "description": "Inactive products count", "type": "integer", "example": 0 }, "sold_out": { "description": "Sold out products count", "type": "integer", "example": 0 }, "expired": { "description": "Expired products count", "type": "integer", "example": 0 }, "draft": { "description": "Draft products count", "type": "integer", "example": 1 }, "editing": { "description": "Products being edited count", "type": "integer", "example": 0 }, "deleted": { "description": "Deleted products count", "type": "integer", "example": 0 } }, "type": "object" }, "shop_info": { "description": "Shop authentication information", "properties": { "access_token": { "description": "OAuth access token (always null for security)", "type": "string", "example": null, "nullable": true }, "refresh_token": { "description": "OAuth refresh token (always null for security)", "type": "string", "example": null, "nullable": true } }, "type": "object" }, "shop_id": { "description": "Platform-specific shop ID", "type": "string", "example": "58282706" }, "is_authorized_ads": { "description": "Whether site is authorized for advertising", "type": "boolean", "example": false }, "balance": { "description": "Site balance (negative means owed)", "type": "number", "format": "float", "example": -1.2 }, "timezone": { "description": "Site timezone", "type": "string", "example": null, "nullable": true }, "currency_code": { "description": "Site currency code", "type": "string", "example": "USD" }, "transaction_currency_code": { "description": "Transaction currency code", "type": "string", "example": "USD" }, "enable_create_products": { "description": "Whether product creation is enabled", "type": "boolean", "example": false }, "resource_quota": { "description": "Resource quota information", "properties": { "is_using_slot": { "description": "Whether using a resource slot", "type": "boolean", "example": true }, "allocation_id": { "description": "Resource allocation ID", "type": "integer", "example": 5885, "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Site not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/sites": { "get": { "tags": [ "Sites" ], "summary": "List connected e-commerce sites", "description": "Get all e-commerce sites connected to your workspace (Etsy, TikTok, Amazon, Shopify)", "operationId": "listSites", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "platform_id", "in": "query", "description": "Filter by platform (1=Etsy, 4=TikTok, 5=Amazon, 6=Shopify)", "required": false, "schema": { "type": "integer", "enum": [ 1, 4, 5, 6 ], "example": 1 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "Sites retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Site ID - Use in Deploy API", "type": "integer", "example": 6529 }, "platform_id": { "description": "Platform identifier", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Etsy Shop" }, "is_destination": { "type": "integer", "example": 1 }, "is_active": { "type": "integer", "example": 1 }, "site_is_death": { "type": "integer", "example": 0 }, "is_limit": { "type": "integer", "example": 0 }, "is_crawl": { "type": "integer", "example": 1 }, "site_url": { "type": "string", "example": "https://www.etsy.com/shop/MyEtsyShop" }, "finished_sync_at": { "type": "string", "format": "datetime", "example": "2025-10-22 03:05:31" }, "resource_share": { "properties": { "resourceable_id": { "type": "integer", "example": 6529 }, "total_users": { "type": "integer", "example": 1 }, "top_users": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" } }, "type": "object" } } }, "type": "object" }, "resource_quota": { "properties": { "is_using_slot": { "type": "boolean", "example": true }, "allocation_id": { "type": "integer", "example": 5885 } }, "type": "object" }, "timezone": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "paging": { "properties": { "total": { "type": "integer", "example": 4 }, "count": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 2 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 2 }, "links": { "properties": { "next": { "type": "string", "example": "https://api.dodgeprint.com/api/v1/sites?page=2" } }, "type": "object" } }, "type": "object" }, "meta": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invalid workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v2/deploy-products": { "put": { "tags": [ "Product Deployment V2 (BETA)" ], "summary": "Update Product - Update existing marketplace listing", "description": "Update an existing product listing on marketplace. Supports updating variants, metadata (title, description, tags), images, and platform-specific fields. Send only fields you want to update - API auto-detects update type and returns the detected type in response.", "operationId": "85718f501bfb5d9236f356ff40b1f50e", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "platform_id", "site_id", "product_on_site_id" ], "properties": { "type": { "description": "Operation type", "type": "string", "enum": [ "update" ], "example": "update" }, "platform_id": { "description": "Platform: 1=Etsy, 4=TikTok, 5=Amazon", "type": "integer", "enum": [ 1, 4, 5 ], "example": 1 }, "site_id": { "description": "Site ID", "type": "integer", "example": 123 }, "product_on_site_id": { "description": "Product on site ID (the listing to update)", "type": "integer", "example": 67890 }, "product_id": { "description": "Product ID (optional)", "type": "integer", "example": 789 }, "title": { "description": "Product title (optional, max 255 chars)", "type": "string", "example": "Updated Product Title" }, "description": { "description": "Product description (optional)", "type": "string", "example": "Updated product description with more details" }, "tags": { "description": "Product tags (optional, max 13 tags)", "type": "array", "items": { "type": "string" }, "example": [ "handmade", "unique", "gift" ] }, "images": { "description": "Gallery images (optional, max 10 images). Each image requires url field, position is optional.", "type": "array", "items": { "required": [ "url" ], "properties": { "url": { "description": "Image URL (must be HTTPS)", "type": "string", "format": "uri", "example": "https://cdn.example.com/image1.jpg" }, "position": { "description": "Display order (optional)", "type": "integer", "example": 1 } }, "type": "object" }, "nullable": true }, "group_variant_id": { "description": "Group variant ID (optional, alternative to inline variants)", "type": "integer", "example": 456 }, "variants": { "description": "Inline variants array (optional). Use this OR group_variant_id, not both. All variants must have consistent option schema (same dimension names in same order). Max 2 dimensions for Etsy.", "type": "array", "items": { "required": [ "price", "quantity", "options" ], "properties": { "price": { "description": "Variant price (min 0.01)", "type": "number", "format": "float", "example": 19.99 }, "quantity": { "description": "Stock quantity (min 0)", "type": "integer", "example": 100 }, "sku": { "description": "SKU code (optional, max 100 chars)", "type": "string", "maxLength": 100, "example": "T2-S-R", "nullable": true }, "options": { "description": "Variant option dimensions (min 1, max 2 for Etsy). Must be consistent across all variants.", "type": "array", "items": { "required": [ "name", "value" ], "properties": { "name": { "description": "Dimension name (e.g., Size, Color)", "type": "string", "maxLength": 50, "example": "Size" }, "value": { "description": "Dimension value (e.g., Small, Red)", "type": "string", "maxLength": 100, "example": "Small" } }, "type": "object" }, "maxItems": 2, "minItems": 1 } }, "type": "object" }, "nullable": true }, "category_id": { "description": "Category ID (optional)", "type": "integer", "example": 2197 }, "shipping_profile_id": { "description": "Shipping profile ID (Etsy only, optional)", "type": "integer", "example": 100 }, "return_policy_id": { "description": "Return policy ID (Etsy only, optional)", "type": "integer", "example": 200 }, "shop_section_id": { "description": "Shop section ID (Etsy only, optional)", "type": "integer", "example": 300, "nullable": true }, "content_id": { "description": "Content template ID (optional)", "type": "integer", "example": 3968, "nullable": true }, "when_made": { "description": "When item was made (Etsy only, optional)", "type": "string", "example": "made_to_order", "nullable": true }, "who_made": { "description": "Who made the item (Etsy only, optional)", "type": "string", "enum": [ "i_did", "collective", "someone_else" ], "example": "i_did", "nullable": true }, "is_supply": { "description": "Is this a supply/tool? (Etsy only, optional)", "type": "boolean", "example": false, "nullable": true }, "processing_profile_id": { "description": "Processing time profile ID (Etsy only, optional for updates). Get 'readiness_state_id' from GET /v1/processing-profiles endpoint.", "type": "string", "example": "1742858595", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "product_deploy_id": { "type": "integer", "example": 12347 }, "product_on_site_id": { "type": "integer", "example": 67890 }, "product_origin_id": { "type": "string", "example": "1234567890" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Product on site does not exist" } }, "type": "object" } } } }, "409": { "description": "Lock timeout", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 409 }, "message": { "type": "string", "example": "Another deployment is currently processing this product. Please try again in a few moments." } }, "type": "object" } } } }, "500": { "description": "Update failed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "Update variant failed: Invalid inventory data" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Product Deployment V2 (BETA)" ], "summary": "Insert Product - Deploy new product to marketplace", "description": "Deploy a new product to Etsy, Amazon, or TikTok marketplace. Creates a new listing synchronously and returns result immediately.\n *\n * **Two Deployment Modes:**\n *\n * **Mode 1: Deploy Existing Product**\n * - Provide `product_id` (existing product from products table)\n * - Product must already exist in your workspace\n * - Example: `{\"product_id\": 789, \"platform_id\": 1, ...}`\n *\n * **Mode 2: Auto-create & Deploy New Product**\n * - Provide `title` instead of `product_id`\n * - System auto-creates minimal product with title, auto-generated SKU, and category\n * - Optionally provide `sku_origin` for custom SKU\n * - Example: `{\"title\": \"Summer T-Shirt 2024\", \"platform_id\": 1, ...}`\n *\n * **Note:** You must provide either `product_id` OR `title`, not both.", "operationId": "5a6bb1d30f5f19f7bd40680ef19b0b9c", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "platform_id", "site_id" ], "properties": { "type": { "description": "Operation type", "type": "string", "enum": [ "insert" ], "example": "insert" }, "platform_id": { "description": "Platform: 1=Etsy, 4=TikTok, 5=Amazon", "type": "integer", "enum": [ 1, 4, 5 ], "example": 1 }, "site_id": { "description": "Site ID from sites table", "type": "integer", "example": 123 }, "product_id": { "description": "[Optional] Product ID. If not provided, auto-creates product using title+images.", "type": "integer", "example": 789 }, "title": { "description": "[Required if product_id not provided] Product title", "type": "string", "maxLength": 255, "example": "Summer T-Shirt 2024" }, "sku_origin": { "description": "[Optional] Custom SKU. Auto-generated if not provided.", "type": "string", "maxLength": 100, "example": "SUMMER-TEE-001" }, "images": { "description": "[Required if product_id not provided] Product images (1-10 images)", "type": "array", "items": { "required": [ "url" ], "properties": { "url": { "description": "HTTPS image URL", "type": "string", "format": "uri", "example": "https://example.com/image.jpg" }, "position": { "description": "Image position (0-based). Uses array index if not provided.", "type": "integer", "example": 0 } }, "type": "object" } }, "description": { "description": "[Recommended] Product description. HTML supported. Essential for SEO.", "type": "string", "maxLength": 5000, "example": "

Beautiful handcrafted product made with premium materials.

" }, "tags": { "description": "[Optional] Product tags. Max 13 tags, 20 chars each (Etsy limit).", "type": "array", "items": { "type": "string", "maxLength": 20 }, "example": [ "handmade", "gift", "vintage" ] }, "materials": { "description": "[Optional] Materials used. Max 13 items, 45 chars each (Etsy limit).", "type": "array", "items": { "type": "string", "maxLength": 45 }, "example": [ "cotton", "polyester" ] }, "group_variant_id": { "description": "Group variant ID (required if variants not provided)", "type": "integer", "example": 456 }, "variants": { "description": "Inline variants array (required if group_variant_id not provided). Max 2 variant dimensions for Etsy.", "type": "array", "items": { "required": [ "price", "quantity", "options" ], "properties": { "price": { "description": "Variant price", "type": "number", "format": "float", "example": 19.99 }, "quantity": { "description": "Available stock quantity", "type": "integer", "example": 100 }, "sku": { "description": "Optional SKU for inventory tracking", "type": "string", "maxLength": 100, "example": "TSHIRT-SM-BLK" }, "options": { "description": "Variant option dimensions (e.g., Size, Color). Max 2 for Etsy.", "type": "array", "items": { "required": [ "name", "value" ], "properties": { "name": { "description": "Option name (e.g., Size, Color)", "type": "string", "maxLength": 50, "example": "Size" }, "value": { "description": "Option value (e.g., Small, Red)", "type": "string", "maxLength": 100, "example": "Small" } }, "type": "object" }, "maxItems": 2, "minItems": 1, "example": [ { "name": "Size", "value": "Small" }, { "name": "Color", "value": "Black" } ] } }, "type": "object" }, "example": [ { "price": 19.99, "quantity": 100, "sku": "TSHIRT-SM-BLK", "options": [ { "name": "Size", "value": "Small" }, { "name": "Color", "value": "Black" } ] }, { "price": 19.99, "quantity": 150, "options": [ { "name": "Size", "value": "Medium" }, { "name": "Color", "value": "Black" } ] }, { "price": 21.99, "quantity": 80, "options": [ { "name": "Size", "value": "Large" }, { "name": "Color", "value": "White" } ] } ] }, "category_id": { "description": "Category ID (required if using inline variants)", "type": "integer", "example": 2197 }, "shipping_profile_id": { "description": "[Etsy Required] Internal shipping profile ID from shipping_profiles table. System auto-converts to Etsy origin ID.", "type": "integer", "example": 100 }, "return_policy_id": { "description": "[Etsy Required] Internal return policy ID from return_policies table. System auto-converts to Etsy origin ID.", "type": "integer", "example": 200 }, "shop_section_id": { "description": "[Etsy Optional] Internal shop section ID from sections table. System auto-converts to Etsy origin ID.", "type": "integer", "example": 300 }, "content_id": { "description": "[Etsy Optional] Content template ID for description", "type": "integer", "example": 50 }, "when_made": { "description": "[Etsy Optional] When item was made", "type": "string", "enum": [ "made_to_order", "2020_2024", "2010_2019", "2000_2009", "1990_1999", "1980_1989", "1970_1979", "before_1970" ], "example": "made_to_order" }, "who_made": { "description": "[Etsy Optional] Who made the item", "type": "string", "enum": [ "i_did", "collective", "someone_else" ], "example": "i_did" }, "is_supply": { "description": "[Etsy Optional] Is this a craft supply?", "type": "boolean", "example": false }, "processing_profile_id": { "description": "[Etsy Required] Processing time profile ID for physical products. Defines product readiness state and processing time. Get 'readiness_state_id' from GET /v1/processing-profiles endpoint.", "type": "string", "example": "1742858595" }, "product_definitions": { "description": "[Amazon Required] Product definitions JSON", "type": "string" }, "bullet_point": { "description": "[Amazon Required] Bullet points", "type": "string" }, "product_type": { "description": "[Amazon Required] Product type", "type": "string" }, "generic_keyword": { "description": "[Amazon Optional] Generic keywords for search", "type": "string" }, "warehouses": { "description": "[TikTok Required] Warehouses JSON", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Product deployed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "product_deploy_id": { "description": "Deploy record ID", "type": "integer", "example": 12345 }, "product_on_site_id": { "description": "Product on site ID", "type": "integer", "example": 67890 }, "product_origin_id": { "description": "Platform listing ID", "type": "string", "example": "1234567890" }, "listing_url": { "description": "Direct link to marketplace listing", "type": "string", "example": "https://www.etsy.com/listing/1234567890" }, "status": { "description": "Listing status", "type": "string", "example": "active" }, "title": { "type": "string", "example": "Beautiful Handmade Product" }, "deployed_at": { "type": "string", "format": "date-time", "example": "2025-01-15 10:30:45" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Either group_variant_id or variants is required" } }, "type": "object" } } } }, "409": { "description": "Lock timeout - another deployment in progress", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 409 }, "message": { "type": "string", "example": "Another deployment is currently processing this product. Please try again in a few moments." } }, "type": "object" } } } }, "500": { "description": "Deployment failed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "Image [https://example.com/img.jpg] is invalid. Please check product images and try again." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Product Deployment V2 (BETA)" ], "summary": "Delete Product - Remove listing from marketplace", "description": "Delete a product listing from marketplace platform. Removes the listing from Etsy, Amazon, or TikTok. Product data remains in Dodgeprint but is removed from the marketplace.", "operationId": "c3da03c8404af40195bbb0657f26e1e9", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "platform_id", "site_id", "product_on_site_id" ], "properties": { "type": { "description": "Operation type", "type": "string", "enum": [ "delete" ], "example": "delete" }, "platform_id": { "description": "Platform: 1=Etsy, 4=TikTok, 5=Amazon", "type": "integer", "enum": [ 1, 4, 5 ], "example": 1 }, "site_id": { "description": "Site ID", "type": "integer", "example": 123 }, "product_on_site_id": { "description": "Product on site ID (the listing to delete)", "type": "integer", "example": 67890 } }, "type": "object" } } } }, "responses": { "200": { "description": "Product deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "product_deploy_id": { "type": "integer", "example": 12351 }, "product_on_site_id": { "type": "integer", "example": 67890 }, "product_origin_id": { "type": "string", "example": "1234567890" }, "deleted_at": { "type": "string", "format": "date-time", "example": "2025-01-15 12:00:00" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Product on site does not exist" } }, "type": "object" } } } }, "409": { "description": "Lock timeout", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 409 }, "message": { "type": "string", "example": "Another deployment is currently processing this product. Please try again in a few moments." } }, "type": "object" } } } }, "500": { "description": "Delete failed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "Cannot delete a listing in state: removed" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List workspaces", "description": "Get list of workspaces accessible by the authenticated user", "operationId": "listWorkspaces", "responses": { "200": { "description": "Workspaces retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 100 }, "name": { "type": "string", "example": "My Business Workspace" }, "description": { "type": "string", "example": null, "nullable": true }, "type": { "type": "string", "example": "business" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-04-05 05:53:55" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-08-04 11:27:45" }, "role": { "description": "User role in workspace", "type": "string", "example": "owner" }, "status": { "type": "integer", "example": 1 }, "total_members": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Workspaces" ], "summary": "Create a new workspace", "description": "Create a new workspace. The authenticated user will automatically become the owner of the workspace. Workspace names must be 3-255 characters and cannot contain special characters like commas, semicolons, quotes, or brackets.", "operationId": "createWorkspace", "requestBody": { "description": "Workspace creation data", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type" ], "properties": { "name": { "description": "Workspace name, 3-255 characters, cannot contain special characters", "type": "string", "maxLength": 255, "minLength": 3, "example": "My Business Workspace" }, "type": { "description": "Workspace type: 'personal' for individual use, 'business' for team collaboration", "type": "string", "enum": [ "personal", "business" ], "example": "business" }, "description": { "description": "Optional workspace description", "type": "string", "example": "Workspace for managing e-commerce products and orders" } }, "type": "object" } } } }, "responses": { "200": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "My Business Workspace" }, "slug": { "type": "string", "example": "my-business-workspace" }, "type": { "type": "string", "example": "business" }, "description": { "type": "string", "example": "Workspace for managing e-commerce products and orders" }, "status": { "description": "1: Active, 0: Inactive", "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-01-13 10:30:45" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-01-13 10:30:45" }, "owner": { "description": "User who created the workspace (automatically assigned as owner)", "properties": { "id": { "type": "integer", "example": 1001 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "The name field is required." }, "errors": { "description": "Validation error details", "properties": { "name": { "type": "array", "items": { "type": "string", "example": "Workspace name cannot contain special characters like commas, semicolons, quotes, or brackets" } }, "type": { "type": "array", "items": { "type": "string", "example": "The selected type is invalid." } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workspaces/{id}": { "get": { "tags": [ "Workspaces" ], "summary": "Get workspace details", "description": "Get detailed information about a specific workspace including owner and shops by platform", "operationId": "getWorkspaceDetail", "parameters": [ { "$ref": "#/components/parameters/X-Workspace-Id" }, { "name": "id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "integer", "example": 380 } } ], "responses": { "200": { "description": "Workspace details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "properties": { "id": { "type": "integer", "example": 100 }, "name": { "type": "string", "example": "My Business Workspace" }, "description": { "type": "string", "example": null, "nullable": true }, "type": { "type": "string", "example": "business" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-04-05 05:53:55" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-08-04 11:27:45" }, "role": { "type": "string", "example": "owner" }, "status": { "type": "integer", "example": 1 }, "total_members": { "type": "integer", "example": 2 }, "owner": { "properties": { "id": { "type": "integer", "example": 1001 }, "email": { "type": "string", "example": "john.doe@example.com" }, "full_name": { "type": "string", "example": "John Doe" }, "short_name": { "type": "string", "example": "JD" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "country_iso2": { "type": "string", "example": "VN" }, "roles": { "type": "array", "items": { "type": "string", "example": "user" } } }, "type": "object" }, "shops_by_platform": { "type": "array", "items": { "properties": { "platform_id": { "type": "integer", "example": 1 }, "count": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error - X-Workspace-ID is required", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "X-Workspace-ID is required" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "CategoryListExampleEtsy": { "title": "Categories List Example - Etsy", "description": "Example response when getting categories for Etsy platform", "type": "object", "example": { "success": true, "data": [ { "id": 2197, "name": "Wall Decor", "taxonomy_id": "1027", "platform_id": 1, "parent_id": null, "origin_id": null, "is_leaf": 1, "level": 1, "path": "/Wall Decor", "created_at": "2025-01-15 10:30:45", "updated_at": "2025-01-15 10:30:45" }, { "id": 2198, "name": "Home & Living", "taxonomy_id": "1059", "platform_id": 1, "parent_id": null, "origin_id": null, "is_leaf": 1, "level": 1, "path": "/Home & Living", "created_at": "2025-01-15 10:30:45", "updated_at": "2025-01-15 10:30:45" }, { "id": 2199, "name": "Clothing", "taxonomy_id": "1542", "platform_id": 1, "parent_id": null, "origin_id": null, "is_leaf": 1, "level": 1, "path": "/Clothing", "created_at": "2025-01-15 10:30:45", "updated_at": "2025-01-15 10:30:45" } ], "pagination": { "total": 156, "count": 3, "per_page": 10, "current_page": 1, "total_pages": 16 } } }, "CategoryListExampleAmazon": { "title": "Categories List Example - Amazon", "description": "Example response when getting categories for Amazon platform", "type": "object", "example": { "success": true, "data": [ { "id": 3501, "name": "Clothing, Shoes & Jewelry", "taxonomy_id": "7141123011", "platform_id": 3, "parent_id": null, "origin_id": null, "is_leaf": 0, "level": 1, "path": "/Clothing, Shoes & Jewelry", "created_at": "2025-01-15 10:30:45", "updated_at": "2025-01-15 10:30:45" }, { "id": 3502, "name": "T-Shirts", "taxonomy_id": "1040658", "platform_id": 3, "parent_id": 3501, "origin_id": null, "is_leaf": 1, "level": 2, "path": "/Clothing, Shoes & Jewelry/T-Shirts", "created_at": "2025-01-15 10:30:45", "updated_at": "2025-01-15 10:30:45" } ], "pagination": { "total": 428, "count": 2, "per_page": 10, "current_page": 1, "total_pages": 43 } } }, "CategoryDetailExample": { "title": "Category Detail Example", "description": "Example response when getting a specific category details", "type": "object", "example": { "success": true, "data": { "id": 2197, "name": "Wall Decor", "taxonomy_id": "1027", "platform_id": 1, "parent_id": null, "origin_id": null, "is_leaf": 1, "level": 1, "path": "/Wall Decor", "attributes": [ { "id": 101, "name": "Primary Color", "required": false }, { "id": 102, "name": "Secondary Color", "required": false } ], "created_at": "2025-01-15 10:30:45", "updated_at": "2025-01-15 10:30:45" } } }, "CreateVariantGroupExample1Dimension": { "title": "Create Variant Group - 1 Dimension Example", "description": "Example with single dimension (Size only). Suitable for simple products.", "type": "object", "example": { "name": "T-Shirt Sizes Only", "category_id": 2197, "dimension_labels": { "variant0": "Size" }, "variants": [ { "variant0": "Small", "price": 19.99, "quantity": 100 }, { "variant0": "Medium", "price": 19.99, "quantity": 150 }, { "variant0": "Large", "price": 21.99, "quantity": 120 }, { "variant0": "X-Large", "price": 23.99, "quantity": 80 } ] } }, "CreateVariantGroupExample2Dimensions": { "title": "Create Variant Group - 2 Dimensions Example", "description": "Example with two dimensions (Size + Color). Most common use case for Etsy products.", "type": "object", "example": { "name": "T-Shirt Size & Color Variants", "category_id": 2197, "dimension_labels": { "variant0": "Size", "variant1": "Color" }, "variants": [ { "variant0": "Small", "variant1": "Red", "price": 19.99, "quantity": 100 }, { "variant0": "Small", "variant1": "Blue", "price": 19.99, "quantity": 100 }, { "variant0": "Medium", "variant1": "Red", "price": 21.99, "quantity": 50 }, { "variant0": "Medium", "variant1": "Blue", "price": 21.99, "quantity": 50 }, { "variant0": "Large", "variant1": "Red", "price": 23.99, "quantity": 30 }, { "variant0": "Large", "variant1": "Blue", "price": 23.99, "quantity": 30 } ] } }, "CreateVariantGroupExample3Dimensions": { "title": "Create Variant Group - 3 Dimensions Example", "description": "Example with three dimensions (Type-Size + Color + Frame). Suitable for complex products like Canvas Prints on Amazon.", "type": "object", "example": { "name": "Canvas Prints - Complete Variants", "category_id": 2197, "product_type_id": 123, "dimension_labels": { "variant0": "Type-Size", "variant1": "Color", "variant2": "Frame" }, "variants": [ { "variant0": "Canvas 24x36 inch", "variant1": "Black", "variant2": "Framed", "price": 15.99, "quantity": 111 }, { "variant0": "Canvas 24x36 inch", "variant1": "Black", "variant2": "Unframed", "price": 12.99, "quantity": 150 }, { "variant0": "Canvas 18x24 inch", "variant1": "White", "variant2": "Framed", "price": 13.99, "quantity": 200 }, { "variant0": "Canvas 18x24 inch", "variant1": "White", "variant2": "Unframed", "price": 10.99, "quantity": 250 }, { "variant0": "Poster 24x36 inch", "variant1": "Glossy", "variant2": "Unframed", "price": 8.99, "quantity": 300 } ] } }, "CreateVariantGroupSuccessResponse": { "title": "Create Variant Group - Success Response", "description": "Expected response after successfully creating a variant group", "type": "object", "example": { "success": true, "message": "Created successfully", "data": { "id": 4029, "name": "T-Shirt Size & Color Variants", "variant_count": 6 } } }, "DeployAmazonExample": { "title": "Deploy to Amazon - Complete Example", "description": "Complete JSON request example for deploying a product to Amazon. Note: product_definitions, bullet_point, product_type, shipping_profile_id, and return_policy_id are required for Amazon.", "type": "object", "example": { "type": "insert", "site_id": 8456, "content_id": 2414, "selected": [ 1635986 ], "is_save_draft": false, "variants": { "id": 4028, "headers": [ { "key": "variant0", "name": "Size" }, { "key": "variant1", "name": "Color" } ], "variant_values": [], "category": { "id": 2197, "taxonomy_id": "1027", "origin_id": null }, "childs": [ { "id": 505660, "variant0": "Small", "variant1": "Navy", "price": 29.99, "quantity": 500 }, { "id": 505661, "variant0": "Medium", "variant1": "Navy", "price": 29.99, "quantity": 500 }, { "id": 505662, "variant0": "Large", "variant1": "Graphite", "price": 31.99, "quantity": 300 }, { "id": 505663, "variant0": "X-Large", "variant1": "Graphite", "price": 33.99, "quantity": 200 } ] }, "shipping_profile_id": 6811, "return_policy_id": 5, "category": 2197, "listing_type": "physical", "product_definitions": "SHIRT", "bullet_point": "bullet_template_1", "product_type": "SHIRT", "generic_keyword": "premium cotton shirt casual wear men women", "brands": [ { "origin_id": "BRAND123" } ], "shipping_package_template_id": 1, "product_attributes": [], "is_draft": false } }, "DeployAmazonExampleResponse": { "title": "Deploy to Amazon - Response Example", "description": "Expected response after successful deployment to Amazon", "type": "object", "example": { "success": true, "message": "Product deployment initiated successfully", "data": { "product_on_site_id": 345678, "status": "pending", "estimated_time": "5-15 seconds" } } }, "DeployEtsyExample": { "title": "Deploy to Etsy - Complete Example", "description": "Complete JSON request example for deploying a product to Etsy. This example includes all required Etsy-specific fields.", "type": "object", "example": { "type": "insert", "site_id": 6529, "content_id": 2414, "selected": [ 1635986 ], "is_save_draft": false, "variants": { "id": 4028, "headers": [ { "key": "variant0", "name": "Size" }, { "key": "variant1", "name": "Color" } ], "variant_values": [], "category": { "id": 2197, "taxonomy_id": "1027", "origin_id": null }, "childs": [ { "id": 505660, "variant0": "Small", "variant1": "Black", "price": 24.99, "quantity": 100 }, { "id": 505661, "variant0": "Medium", "variant1": "Black", "price": 24.99, "quantity": 100 }, { "id": 505662, "variant0": "Large", "variant1": "White", "price": 26.99, "quantity": 50 } ] }, "shipping_profile_id": 6811, "category": 2197, "return_policy_id": 5, "tags": [ "custom t-shirt", "personalized", "cotton", "gift", "handmade" ], "shop_section_id": 28745001, "personalization_id": 1, "tag_id": 1, "tag_by_product": false, "listing_type": "physical", "when_made": "made_to_order", "who_made": "i_did", "is_supply": false, "is_draft": false } }, "DeployEtsyExampleResponse": { "title": "Deploy to Etsy - Response Example", "description": "Expected response after successful deployment to Etsy", "type": "object", "example": { "success": true, "message": "Product deployment initiated successfully", "data": { "product_on_site_id": 123456, "status": "pending", "estimated_time": "5-15 seconds" } } }, "DeployTikTokExample": { "title": "Deploy to TikTok Shop - Complete Example", "description": "Complete JSON request example for deploying a product to TikTok Shop. Note: content_id, warehouses, and tags are required for TikTok.", "type": "object", "example": { "type": "insert", "site_id": 7234, "content_id": 2414, "selected": [ 1635986 ], "is_save_draft": false, "variants": { "id": 4028, "headers": [ { "key": "variant0", "name": "Size" }, { "key": "variant1", "name": "Color" } ], "variant_values": [], "category": { "id": 2197, "taxonomy_id": "3", "origin_id": null }, "childs": [ { "id": 505660, "variant0": "Small", "variant1": "Black", "price": 19.99, "quantity": 200 }, { "id": 505661, "variant0": "Medium", "variant1": "Blue", "price": 19.99, "quantity": 150 }, { "id": 505662, "variant0": "Large", "variant1": "Red", "price": 21.99, "quantity": 100 } ] }, "warehouses": "WAREHOUSE_US", "tags": [ "trendy", "fashion", "streetwear", "tiktok viral", "summer collection" ], "listing_type": "physical", "category": 2197, "is_draft": false, "generic_keyword": "fashion tshirt streetwear casual" } }, "DeployTikTokExampleResponse": { "title": "Deploy to TikTok Shop - Response Example", "description": "Expected response after successful deployment to TikTok Shop", "type": "object", "example": { "success": true, "message": "Product deployment initiated successfully", "data": { "product_on_site_id": 789012, "status": "pending", "estimated_time": "5-15 seconds" } } }, "DeployMinimalExample": { "title": "Deploy Product - Minimal Example (Quickstart)", "description": "Minimal required fields for product deployment. This is the simplest example for testing. Note: Actual required fields vary by platform - see Platform-Specific Requirements table.", "type": "object", "example": { "type": "insert", "site_id": 6529, "selected": [ 1635986 ], "variants": { "id": 4028, "headers": [ { "key": "variant0", "name": "Size" } ], "childs": [ { "id": 505660, "variant0": "One Size", "price": 19.99, "quantity": 100 } ] } } }, "DeployMinimalExampleResponse": { "title": "Deploy Product - Minimal Response", "description": "Expected response after minimal deployment request", "type": "object", "example": { "success": true, "message": "Product deployment initiated successfully", "data": { "product_on_site_id": 999888, "status": "pending", "estimated_time": "5-15 seconds" } } }, "User": { "title": "User", "description": "User object", "properties": { "id": { "type": "integer", "example": 1 }, "full_name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "johndoe@example.com" } }, "type": "object" }, "UnauthorizedResponse": { "title": "Unauthorized Response", "description": "Response for unauthorized access", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" }, "SuccessResponse": { "title": "Success Response", "description": "Response for successful operation", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successful operation" } }, "type": "object" }, "PagingSchema": { "title": "Paging Schema", "description": "Paging object schema", "properties": { "total": { "type": "integer", "example": 3 }, "count": { "type": "integer", "example": 3 }, "limit": { "type": "integer", "example": 15 }, "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "links": { "type": "array", "items": {} } }, "type": "object" }, "ErrorResponse": { "title": "Error Response", "description": "Response for error operation", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error message" } }, "type": "object" }, "SiteListResponse": { "title": "Site List Response", "description": "Danh sách các site", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSchema" } } }, "type": "object" }, "SiteSchema": { "title": "Site", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Amazon Store" }, "platform": { "type": "string", "example": "amazon" }, "status": { "type": "integer", "example": 1 } }, "type": "object" }, "ForbiddenResponse": { "title": "Forbidden Response", "description": "Khi người dùng không có quyền truy cập API", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have permission to access this resource." }, "code": { "type": "integer", "example": 403 } }, "type": "object" }, "SiteResponse": { "title": "Site Response", "description": "Chi tiết một site", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "$ref": "#/components/schemas/SiteSchema" } }, "type": "object" }, "NotFoundResponse": { "title": "Not Found Response", "description": "Trả về khi không tìm thấy bản ghi", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Site not found" } }, "type": "object" }, "ProductOnSiteListResponse": { "title": "Product On Site List Response", "description": "Danh sách sản phẩm đã được đẩy lên các site", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOnSiteSchema" } } }, "type": "object" }, "ProductOnSiteSchema": { "title": "Product On Site", "properties": { "id": { "type": "integer", "example": 123 }, "site_name": { "type": "string", "example": "Amazon" }, "product_name": { "type": "string", "example": "T-shirt - Blue M" }, "status": { "type": "string", "example": "active" }, "synced_at": { "type": "string", "format": "date-time", "example": "2025-06-23T12:00:00Z" } }, "type": "object" }, "ProductOnSiteResponse": { "title": "Product On Site Response", "description": "Chi tiết một sản phẩm đã được đẩy lên site", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "$ref": "#/components/schemas/ProductOnSiteSchema" } }, "type": "object" }, "OrderSchema": { "title": "Order", "description": "Thông tin đơn hàng", "properties": { "id": { "type": "integer", "example": 123 }, "order_number": { "type": "string", "example": "ORD-20250623-0001" }, "status": { "type": "string", "example": "completed" }, "total": { "type": "number", "format": "float", "example": 99.99 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-23T10:00:00Z" } }, "type": "object" }, "OrderListResponse": { "title": "Order List Response", "description": "Danh sách đơn hàng", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSchema" } } }, "type": "object" }, "WorkspaceMemberSchema": { "title": "Workspace Member", "description": "Workspace member information", "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 223 }, "workspace_id": { "type": "integer", "example": 359 }, "role": { "type": "string", "example": "admin" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-08-18 04:30:00" }, "updated_at": { "type": "string", "format": "datetime", "example": "2025-08-18 04:30:15" }, "user": { "properties": { "id": { "type": "integer", "example": 223 }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "john@example.com" } }, "type": "object", "nullable": true } }, "type": "object" }, "ExportRequest": { "title": "Export Request", "description": "Export request model with filter conditions and scheduling", "properties": { "id": { "type": "integer", "example": 1 }, "workspace_id": { "type": "integer", "example": 359 }, "user_id": { "type": "integer", "example": 223 }, "module": { "type": "string", "enum": [ "orders", "products", "ledger", "report" ], "example": "orders" }, "name": { "type": "string", "example": "Monthly Orders Export" }, "description": { "type": "string", "example": "Export all completed orders for this month", "nullable": true }, "filter_conditions": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "selected_columns": { "type": "array", "items": { "type": "string" }, "nullable": true }, "sort_options": { "properties": { "field": { "type": "string", "example": "created_at" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } }, "type": "object", "nullable": true }, "export_format": { "type": "string", "default": "xlsx", "enum": [ "xlsx", "csv" ], "example": "xlsx" }, "limit": { "type": "integer", "maximum": 100000, "minimum": 1, "example": 1000, "nullable": true }, "include_headers": { "type": "boolean", "default": true, "example": true }, "is_scheduled": { "type": "boolean", "default": false, "example": false }, "schedule_cron": { "type": "string", "example": "0 0 * * *", "nullable": true }, "next_run_at": { "type": "string", "format": "date-time", "example": "2025-08-19 00:00:00", "nullable": true }, "last_run_at": { "type": "string", "format": "date-time", "example": "2025-08-18 00:00:00", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ], "example": "completed" }, "error_message": { "type": "string", "nullable": true }, "export_file_id": { "type": "integer", "example": 123, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-08-18 10:30:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-08-18 10:35:00" }, "user": { "$ref": "#/components/schemas/User" }, "export_file": { "$ref": "#/components/schemas/ExportFileWithProgress" } }, "type": "object" }, "UpdateExportRequest": { "title": "Update Export Request", "description": "Update export request payload", "properties": { "name": { "type": "string", "example": "Updated Export Name" }, "description": { "type": "string", "nullable": true }, "filter_conditions": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "selected_columns": { "type": "array", "items": { "type": "string" } }, "sort_options": { "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": [ "asc", "desc" ] } }, "type": "object" }, "export_format": { "type": "string", "enum": [ "xlsx", "csv" ] }, "limit": { "type": "integer", "maximum": 100000, "minimum": 1 }, "include_headers": { "type": "boolean" }, "is_scheduled": { "type": "boolean" }, "schedule_cron": { "type": "string" } }, "type": "object" }, "ExportFileWithProgress": { "title": "Export File With Progress", "description": "Export file model with real-time progress tracking", "properties": { "id": { "type": "integer", "example": 123 }, "workspace_id": { "type": "integer", "example": 359 }, "user_id": { "type": "integer", "example": 223 }, "export_request_id": { "type": "integer", "example": 1, "nullable": true }, "export_type": { "type": "string", "example": "orders" }, "filename": { "type": "string", "example": "orders_export_20250818_103000.xlsx" }, "original_filename": { "type": "string", "example": "Monthly Orders Export" }, "s3_path": { "type": "string", "example": "exports/359/orders/2025/08/18/orders_export_20250818_103000.xlsx" }, "file_size": { "type": "integer", "example": 2048576 }, "file_size_formatted": { "type": "string", "example": "2.00 MB" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "example": "completed" }, "filters_used": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" }, "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "export_format": { "type": "string", "enum": [ "xlsx", "csv" ], "example": "xlsx" }, "error_message": { "type": "string", "nullable": true }, "total_records": { "type": "integer", "example": 1500, "nullable": true }, "processed_records": { "type": "integer", "example": 750, "nullable": true }, "progress_percentage": { "type": "number", "format": "float", "maximum": 100, "minimum": 0, "example": 50, "nullable": true }, "processing_rate": { "description": "Records processed per second", "type": "number", "format": "float", "example": 125.5, "nullable": true }, "estimated_completion_at": { "type": "string", "format": "date-time", "example": "2025-08-18 10:45:00", "nullable": true }, "time_remaining": { "type": "string", "example": "5 minutes 30 seconds", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-08-18 10:30:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-08-18 10:35:00" }, "completed_at": { "type": "string", "format": "date-time", "example": "2025-08-18 10:40:00", "nullable": true }, "user": { "$ref": "#/components/schemas/User" }, "export_request": { "$ref": "#/components/schemas/ExportRequestSimple" } }, "type": "object" }, "ExportRequestSimple": { "title": "Export Request Simple", "description": "Simplified export request for nested responses", "properties": { "id": { "type": "integer", "example": 1 }, "module": { "type": "string", "example": "orders" }, "name": { "type": "string", "example": "Monthly Orders Export" }, "export_format": { "type": "string", "example": "xlsx" }, "is_scheduled": { "type": "boolean", "example": false } }, "type": "object" }, "FilterCondition": { "title": "Filter Condition", "description": "Filter condition for export requests", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "example": "orders.status_id" }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "like", "in", "nin", "between" ], "example": "eq" }, "value": { "type": "mixed", "example": "5" }, "condition": { "type": "string", "default": "and", "enum": [ "and", "or" ], "example": "and" } }, "type": "object" }, "ExportStatistics": { "title": "Export Statistics", "description": "Export statistics for workspace", "properties": { "period": { "type": "string", "enum": [ "day", "week", "month", "year" ], "example": "month" }, "total_exports": { "type": "integer", "example": 150 }, "completed_exports": { "type": "integer", "example": 145 }, "failed_exports": { "type": "integer", "example": 3 }, "pending_exports": { "type": "integer", "example": 2 }, "total_file_size": { "type": "integer", "example": 536870912 }, "total_file_size_formatted": { "type": "string", "example": "512.00 MB" }, "average_processing_time": { "description": "Average processing time in seconds", "type": "number", "format": "float", "example": 45.5 }, "exports_by_module": { "type": "object", "example": { "orders": 100, "products": 35, "ledger": 10, "report": 5 }, "additionalProperties": { "type": "integer" } }, "exports_by_format": { "type": "object", "example": { "xlsx": 120, "csv": 30 }, "additionalProperties": { "type": "integer" } }, "daily_exports": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "ExportPreview": { "title": "Export Preview", "description": "Preview of export data with field metadata", "properties": { "records": { "type": "array", "items": { "type": "object" }, "example": [ { "reference_id": "ORD-12345", "customer_email": "john@example.com", "grand_total": 150 }, { "reference_id": "ORD-12346", "customer_email": "jane@example.com", "grand_total": 200 } ] }, "alias_fields": { "type": "object", "example": { "reference_id": { "name": "Order Reference", "has_permission": true }, "customer_email": { "name": "Customer Email", "has_permission": true, "sensitive": true }, "grand_total": { "name": "Total Amount", "has_permission": true, "sensitive": true } } }, "metadata": { "properties": { "total_records": { "type": "integer", "example": 1543 }, "preview_limit": { "type": "integer", "example": 10 }, "export_size_estimate": { "type": "string", "example": "2.5 MB" }, "has_more_records": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "FieldMetadata": { "title": "Field Metadata", "description": "Metadata for a single field", "properties": { "name": { "type": "string", "example": "Order Reference" }, "has_permission": { "type": "boolean", "example": true }, "sensitive": { "type": "boolean", "example": false, "nullable": true }, "type": { "type": "string", "enum": [ "string", "integer", "decimal", "datetime", "email" ], "example": "string", "nullable": true } }, "type": "object" }, "InvitationMetadata": { "description": "Invitation notification metadata", "properties": { "workspace_id": { "type": "integer", "example": 4 }, "invite_token": { "type": "string", "example": "eyJpdiI6Im11VjJ6Wng5T1..." }, "role": { "type": "string", "example": "member" }, "inviter_id": { "type": "integer", "example": 223 }, "expires_at": { "type": "string", "format": "date-time", "example": "2025-03-31T15:04:05.000000Z" }, "inviter": { "properties": { "id": { "type": "integer", "example": 223 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "avatar": { "type": "string", "example": "https://example.com/avatar.png", "nullable": true } }, "type": "object" }, "invitation_status": { "type": "string", "enum": [ "pending", "accepted", "declined", "expired" ], "example": "pending" } }, "type": "object" }, "NewOrderMetadata": { "description": "New order notification metadata", "properties": { "site_id": { "type": "integer", "example": 12 }, "order_reference_id": { "type": "string", "example": "ORD-123456" }, "order_total": { "type": "number", "format": "float", "example": 129.99 } }, "type": "object" }, "NotificationResponse": { "description": "Notification response item", "properties": { "id": { "type": "integer", "example": 1 }, "type": { "type": "string", "enum": [ "invitation", "resource_share", "site_suspended", "site_reactivated", "new_order" ], "example": "invitation" }, "message": { "type": "string", "example": "You have been invited to join the workspace My Workspace 1 by John Doe." }, "metadata": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/InvitationMetadata" }, { "$ref": "#/components/schemas/ResourceShareMetadata" }, { "$ref": "#/components/schemas/SiteStatusMetadata" }, { "$ref": "#/components/schemas/NewOrderMetadata" } ] }, "is_read": { "type": "boolean", "example": false }, "read_at": { "type": "string", "format": "date-time", "example": "11 minutes ago", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "11 minutes ago" } }, "type": "object" }, "NotificationSuccessResponse": { "description": "Standard success response for notification operations", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully" }, "data": { "type": "object" } }, "type": "object" }, "Order": { "title": "Order", "description": "Complete order details including customer, items, shipping, and payment information", "properties": { "id": { "description": "Internal order ID", "type": "integer", "example": 383364 }, "reference_id": { "description": "Platform order ID", "type": "string", "example": "3856094962" }, "marketplace_id": { "description": "Marketplace identifier", "type": "string", "example": null, "nullable": true }, "purchase_date": { "description": "Order purchase date", "type": "string", "example": null, "nullable": true }, "status_id": { "description": "Order status ID (5=Completed)", "type": "integer", "example": 5 }, "subtotal": { "description": "Order subtotal before fees and taxes", "type": "number", "format": "float", "example": 6.99 }, "shipping_fee": { "description": "Shipping cost", "type": "number", "format": "float", "example": 0 }, "discount_amount": { "description": "Total discount applied", "type": "number", "format": "float", "example": 0 }, "tax_amount": { "description": "Tax amount", "type": "number", "format": "float", "example": 0 }, "grand_total": { "description": "Final order total", "type": "number", "format": "float", "example": 8.39 }, "currency_code": { "description": "Currency code", "type": "string", "example": "USD" }, "expected_ship_timestamp": { "description": "Expected ship date", "type": "string", "example": "2025-11-11 19:05:40" }, "order_create_timestamp": { "description": "Order creation date", "type": "string", "example": "2025-11-11 19:05:33" }, "order_update_timestamp": { "description": "Last update date", "type": "string", "example": null, "nullable": true }, "payment_method": { "description": "Payment method (cc=credit card)", "type": "string", "example": "cc" }, "payment_status": { "description": "Payment status", "type": "string", "example": null, "nullable": true }, "site_name": { "description": "Shop name", "type": "string", "example": "My Shop" }, "shipment_status_code": { "description": "Shipment status code", "type": "string", "example": null, "nullable": true }, "gift_message": { "description": "Gift message from buyer", "type": "string", "example": "" }, "form_of_product": { "description": "Product form type", "type": "integer", "example": 1 }, "is_old_order": { "description": "Legacy order flag", "type": "integer", "example": null, "nullable": true }, "customer_note": { "description": "Customer notes", "type": "string", "example": null, "nullable": true }, "shipping_method": { "description": "Shipping method", "type": "string", "example": null, "nullable": true }, "latest_ship_date": { "description": "Latest ship date", "type": "string", "example": null, "nullable": true }, "shipping_label_url": { "description": "Shipping label URL", "type": "string", "example": null, "nullable": true }, "paid_amount": { "description": "Amount paid", "type": "number", "format": "float", "example": null, "nullable": true }, "refunded_fee": { "description": "Refunded amount", "type": "number", "format": "float", "example": null, "nullable": true }, "refunded_date": { "description": "Refund date", "type": "string", "example": null, "nullable": true }, "payment_net": { "description": "Net payment amount", "type": "number", "format": "float", "example": null, "nullable": true }, "tracking_push_platform_status": { "description": "Tracking sync status", "type": "string", "example": "pending" }, "site": { "description": "Site/shop information", "properties": { "id": { "type": "integer", "example": 7005 }, "platform_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Shop" }, "site_is_death": { "type": "integer", "example": 1 }, "is_crawl": { "type": "integer", "example": 0 }, "is_add_watermark": { "type": "integer", "example": 0 }, "is_insufficient_scope": { "type": "integer", "example": 0 }, "reported": { "type": "string", "example": null, "nullable": true }, "last_sync_reported": { "type": "string", "example": null, "nullable": true }, "receipt_new": { "type": "integer", "example": 0 }, "receipt_completed": { "type": "integer", "example": 0 }, "last_sync_receipts": { "type": "string", "example": null, "nullable": true }, "before_sync": { "type": "integer", "example": 0 }, "after_sync": { "type": "integer", "example": 0 }, "last_modified_timestamp": { "type": "string", "example": null, "nullable": true }, "finished_sync_at": { "type": "string", "example": "2025-10-22 03:08:15" }, "last_sync_interacts": { "type": "string", "example": null, "nullable": true }, "last_sync_receipt_transactions": { "type": "string", "example": null, "nullable": true }, "site_url": { "type": "string", "example": "https://www.etsy.com/shop/MyShop" }, "shop_id": { "type": "string", "example": "53341375" } }, "type": "object" }, "customer": { "description": "Customer information", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" } }, "type": "object" }, "order_address": { "description": "Order addresses", "properties": { "state": { "type": "string", "example": null, "nullable": true }, "postal_code": { "type": "string", "example": null, "nullable": true }, "country": { "type": "string", "example": null, "nullable": true }, "country_iso2": { "type": "string", "example": null, "nullable": true }, "billing_address": { "description": "Billing address details", "properties": { "id": { "type": "integer", "example": 387887 }, "address_1": { "type": "string", "example": "123 Main St" }, "address_2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "postal_code": { "type": "string", "example": "10001" }, "country": { "type": "string", "example": "US" }, "country_iso2": { "type": "string", "example": "US" }, "order_id": { "type": "integer", "example": 383364 }, "order_address_id": { "type": "integer", "example": 358206 }, "email": { "type": "string", "example": "customer@example.com" }, "phone": { "type": "string", "example": null, "nullable": true }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "is_verified": { "type": "boolean", "example": false }, "verification_status": { "type": "string", "example": null, "nullable": true }, "verified_at": { "type": "string", "example": null, "nullable": true }, "verification": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "shipping_address": { "description": "Shipping address details", "properties": { "id": { "type": "integer", "example": 387887 }, "address_1": { "type": "string", "example": "123 Main St" }, "address_2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "postal_code": { "type": "string", "example": "10001" }, "country": { "type": "string", "example": "US" }, "country_iso2": { "type": "string", "example": "US" }, "order_id": { "type": "integer", "example": 383364 }, "order_address_id": { "type": "integer", "example": 358206 }, "email": { "type": "string", "example": "customer@example.com" }, "phone": { "type": "string", "example": null, "nullable": true }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "is_verified": { "type": "boolean", "example": false }, "verification_status": { "type": "string", "example": null, "nullable": true }, "verified_at": { "type": "string", "example": null, "nullable": true }, "verification": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" }, "items": { "description": "Order items/products", "type": "array", "items": { "properties": { "quantity": { "type": "integer", "example": 1 }, "unit_price": { "type": "number", "format": "float", "example": 6.99 }, "total_price": { "type": "number", "format": "float", "example": 6.99 }, "product_on_site_id": { "type": "integer", "example": 1098086 }, "name": { "type": "string", "example": "Product Name" }, "reference_id": { "type": "string", "example": "4396179911" }, "sku": { "type": "string", "example": null, "nullable": true }, "image_url": { "type": "string", "example": "https://example.com/image.jpg" }, "customer_note": { "type": "string", "example": null, "nullable": true }, "variations": { "description": "Product variations", "properties": { "category": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "original_option": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "shipments": { "description": "Order shipments", "type": "array", "items": { "type": "object" } }, "status_name": { "description": "Human-readable status", "type": "string", "example": "Completed" }, "shipment_status": { "description": "Shipment status", "type": "string", "example": null, "nullable": true }, "resource_quota": { "description": "Resource quota information", "properties": { "is_using_slot": { "description": "Whether order is using a quota slot", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "ResourceShareMetadata": { "description": "Resource sharing notification metadata", "properties": { "workspace_id": { "type": "integer", "example": 4 }, "invite_token": { "type": "string", "example": "eyJpdiI6Im11VjJ6Wng5T1..." }, "resourceable_id": { "type": "integer", "example": 12 }, "resourceable_type": { "type": "string", "example": "site" }, "inviter_id": { "type": "integer", "example": 223 }, "expires_at": { "type": "string", "format": "date-time", "example": "2025-03-31T15:04:05.000000Z" }, "inviter": { "properties": { "id": { "type": "integer", "example": 223 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" } }, "type": "object" }, "invitation_status": { "type": "string", "enum": [ "pending", "accepted", "declined", "expired" ], "example": "pending" } }, "type": "object" }, "SiteStatusMetadata": { "description": "Site status change notification metadata", "properties": { "site_id": { "type": "integer", "example": 12 }, "site_name": { "type": "string", "example": "My E-commerce Site" }, "reason": { "type": "string", "example": "Payment overdue", "nullable": true } }, "type": "object" }, "SupplierAuthenticationState": { "title": "Supplier Authentication State", "description": "Comprehensive authentication state information for a supplier", "required": [ "status", "is_authenticated", "needs_reauthentication", "message" ], "properties": { "status": { "description": "Current authentication status", "type": "string", "enum": [ "not_required", "pending", "authenticated", "failed", "expired" ], "example": "authenticated" }, "is_authenticated": { "description": "Whether the supplier is currently authenticated", "type": "boolean", "example": true }, "needs_reauthentication": { "description": "Whether reauthentication is required", "type": "boolean", "example": false }, "message": { "description": "Human-readable status message", "type": "string", "example": "Authenticated" }, "expires_at": { "description": "When the current authentication expires (OAuth2 only)", "type": "string", "format": "date-time", "example": "2025-07-20T18:00:00Z", "nullable": true }, "expiring_soon": { "description": "Whether the token is expiring within 24 hours (OAuth2 only)", "type": "boolean", "example": false }, "last_attempt": { "description": "Timestamp of the last authentication attempt", "type": "string", "format": "date-time", "example": "2025-06-20T18:00:00Z", "nullable": true }, "failure_count": { "description": "Number of consecutive authentication failures", "type": "integer", "example": 0 } }, "type": "object" }, "SupplierType": { "description": "Available supplier types in the system", "type": "string", "enum": [ "printify", "merchize", "google_sheet" ], "example": "google_sheet" }, "SupplierStatus": { "description": "Supplier connection status", "type": "string", "enum": [ "active", "inactive", "testing", "error" ], "example": "active" }, "AuthMethod": { "description": "Authentication method used by the supplier", "type": "string", "enum": [ "oauth2", "api_key", "none" ], "example": "oauth2" }, "SupplierSummary": { "required": [ "id", "supplier_code", "supplier_name", "status", "is_configured", "requires_oauth2" ], "properties": { "id": { "description": "Unique supplier ID", "type": "integer", "example": 17 }, "supplier_code": { "$ref": "#/components/schemas/SupplierType" }, "supplier_name": { "description": "Display name for the supplier", "type": "string", "example": "My Google Sheets" }, "connection_name": { "description": "Unique connection identifier", "type": "string", "example": "production", "nullable": true }, "status": { "$ref": "#/components/schemas/SupplierStatus" }, "is_configured": { "description": "Whether supplier has all required configuration", "type": "boolean", "example": true }, "requires_oauth2": { "description": "Whether supplier needs OAuth2 authentication", "type": "boolean", "example": true }, "has_valid_oauth_token": { "description": "Whether OAuth2 token is valid (if applicable)", "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-20T11:35:49.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-06-20T11:35:49.000000Z" } }, "type": "object" }, "SupplierDefinition": { "required": [ "id", "supplier_code", "supplier_name", "auth_method", "required_fields", "is_active" ], "properties": { "id": { "type": "integer", "example": 3 }, "supplier_code": { "$ref": "#/components/schemas/SupplierType" }, "supplier_name": { "type": "string", "example": "Google Sheets" }, "auth_method": { "$ref": "#/components/schemas/AuthMethod" }, "required_fields": { "description": "Configuration fields required for this supplier type", "type": "object", "example": { "spreadsheet_id": { "type": "string", "label": "Spreadsheet ID", "required": true, "description": "The ID of your Google Spreadsheet", "placeholder": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" } } }, "default_base_url": { "type": "string", "example": "https://sheets.googleapis.com/v4", "nullable": true }, "description": { "type": "string", "example": "Integrate with Google Sheets for custom fulfillment workflows" }, "is_active": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 3 }, "oauth_config": { "description": "OAuth2 configuration (if applicable)", "properties": { "auth_url": { "type": "string", "example": "https://accounts.google.com/o/oauth2/v2/auth" }, "token_url": { "type": "string", "example": "https://oauth2.googleapis.com/token" }, "revoke_url": { "type": "string", "example": "https://oauth2.googleapis.com/revoke" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "https://www.googleapis.com/auth/spreadsheets", "https://www.googleapis.com/auth/drive.file" ] } }, "type": "object", "nullable": true } }, "type": "object" }, "SupplierDetail": { "allOf": [ { "$ref": "#/components/schemas/SupplierSummary" }, { "properties": { "supplier_type": { "$ref": "#/components/schemas/SupplierType" }, "auth_method": { "$ref": "#/components/schemas/AuthMethod" }, "base_url": { "type": "string", "example": "https://sheets.googleapis.com/v4", "nullable": true }, "priority": { "type": "integer", "maximum": 10, "minimum": 0, "example": 5 }, "configuration": { "description": "Current supplier configuration (sensitive data excluded)", "type": "object", "example": { "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" } }, "definition": { "$ref": "#/components/schemas/SupplierDefinition" } }, "type": "object" } ] }, "GoogleSheetTemplate": { "properties": { "headers": { "description": "Column headers for the fulfillment template", "type": "array", "items": { "type": "string" }, "example": [ "Order ID", "Customer Name", "Product Name", "Quantity", "Status" ] }, "sample_data": { "description": "Sample data rows to populate", "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "example": [ [ "ORD-001", "John Doe", "T-Shirt", "2", "Pending" ] ] } }, "type": "object" }, "GoogleSheet": { "required": [ "id", "name", "createdTime", "modifiedTime", "webViewLink" ], "properties": { "id": { "description": "Google Sheets ID", "type": "string", "example": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" }, "name": { "description": "Spreadsheet name", "type": "string", "example": "Fulfillment Orders 2025-06-20" }, "createdTime": { "type": "string", "format": "date-time", "example": "2025-06-20T10:30:00.000Z" }, "modifiedTime": { "type": "string", "format": "date-time", "example": "2025-06-20T11:45:00.000Z" }, "webViewLink": { "type": "string", "format": "uri", "example": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit" } }, "type": "object" }, "OrderData": { "description": "Fulfillment order data for syncing to Google Sheets", "properties": { "order_id": { "type": "string", "example": "ORD-123" }, "order_date": { "type": "string", "format": "date", "example": "2025-06-20" }, "customer_name": { "type": "string", "example": "John Doe" }, "customer_email": { "type": "string", "format": "email", "example": "john@example.com" }, "product_name": { "type": "string", "example": "Custom T-Shirt" }, "product_sku": { "type": "string", "example": "TSH-001-M-BLK" }, "quantity": { "type": "string", "example": "2" }, "unit_price": { "type": "string", "example": "$19.99" }, "total_amount": { "type": "string", "example": "$39.98" }, "shipping_address": { "type": "string", "example": "123 Main St" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "zip_code": { "type": "string", "example": "10001" }, "country": { "type": "string", "example": "USA" }, "order_status": { "type": "string", "example": "Paid" }, "fulfillment_status": { "type": "string", "example": "Pending" }, "tracking_number": { "type": "string", "example": "", "nullable": true }, "shipping_method": { "type": "string", "example": "Standard" }, "notes": { "type": "string", "example": "Rush delivery requested", "nullable": true } }, "type": "object" }, "SupplierWithAuthentication": { "title": "Supplier with Authentication Information", "description": "Supplier information with detailed authentication state", "required": [ "id", "workspace_id", "supplier_code", "supplier_name", "supplier_type", "auth_method", "status", "priority", "authentication_state" ], "properties": { "id": { "description": "Unique supplier identifier", "type": "integer", "example": 1 }, "workspace_id": { "description": "Workspace identifier", "type": "integer", "example": 100 }, "supplier_code": { "description": "Unique supplier code", "type": "string", "example": "merchize" }, "supplier_name": { "description": "Human-readable supplier name", "type": "string", "example": "Merchize" }, "supplier_type": { "description": "Type of supplier service", "type": "string", "enum": [ "print_on_demand", "dropshipping", "custom" ], "example": "print_on_demand" }, "auth_method": { "description": "Authentication method required", "type": "string", "enum": [ "api_key", "oauth2", "none" ], "example": "api_key" }, "base_url": { "description": "Base API URL for the supplier", "type": "string", "example": "https://api.merchize.com", "nullable": true }, "status": { "description": "Current supplier status", "type": "string", "enum": [ "active", "inactive", "testing", "error" ], "example": "active" }, "priority": { "description": "Priority order for supplier selection (1 = highest)", "type": "integer", "example": 1 }, "auth_status": { "description": "Current authentication status", "type": "string", "enum": [ "not_required", "pending", "authenticated", "failed", "expired" ], "example": "authenticated" }, "last_auth_attempt": { "description": "Timestamp of last authentication attempt", "type": "string", "format": "date-time", "example": "2024-06-20T18:00:00Z", "nullable": true }, "auth_expires_at": { "description": "When authentication expires (OAuth2 only)", "type": "string", "format": "date-time", "example": "2025-07-20T18:00:00Z", "nullable": true }, "auth_error_message": { "description": "Last authentication error message", "type": "string", "example": null, "nullable": true }, "auth_failure_count": { "description": "Number of consecutive authentication failures", "type": "integer", "example": 0 }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time", "example": "2024-06-20T18:00:00Z" }, "updated_at": { "description": "Last update timestamp", "type": "string", "format": "date-time", "example": "2024-06-20T18:00:00Z" }, "authentication_state": { "$ref": "#/components/schemas/SupplierAuthenticationState" } }, "type": "object" }, "TagAnalyticsResponse": { "description": "Tag analytics response", "properties": { "message": { "type": "string", "example": "Success" }, "status": { "type": "integer", "example": 200 }, "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TagAnalyticsData" } } }, "type": "object" }, "TagAnalyticsData": { "description": "Tag analytics data for a single tag", "properties": { "tag_name": { "type": "string", "example": "vintage camera" }, "hash_data": { "type": "string", "example": "098f6bcd4621d373cade4e832627b4f6" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-05-15 09:34:09" }, "analyzed_at": { "type": "string", "format": "date-time", "example": "2025-05-15 09:34:09" }, "time_ranges": { "type": "array", "items": { "$ref": "#/components/schemas/TimeRangeData" } } }, "type": "object" }, "TimeRangeData": { "description": "Analytics data for a specific time period", "properties": { "period": { "type": "string", "example": "today" }, "number_listings": { "type": "integer", "example": 2 }, "number_listings_before": { "type": "integer", "example": 0 }, "sales": { "type": "integer", "example": 8 }, "sales_before": { "type": "integer", "example": 16 }, "views": { "type": "integer", "example": 1392 }, "views_before": { "type": "integer", "example": 7556 }, "favorers": { "type": "integer", "example": 44 }, "favorers_before": { "type": "integer", "example": 252 }, "number_listings_up": { "type": "integer", "example": 2 }, "sales_up": { "type": "integer", "example": -8 }, "views_up": { "type": "integer", "example": -6164 }, "favorers_up": { "type": "integer", "example": -208 }, "number_listings_growth": { "type": "number", "format": "float", "example": 100 }, "sales_growth": { "type": "number", "format": "float", "example": -50 }, "views_growth": { "type": "number", "format": "float", "example": -81.58 }, "favorers_growth": { "type": "number", "format": "float", "example": -82.54 } }, "type": "object" }, "ValidationErrorResponse": { "description": "Validation error response", "properties": { "message": { "type": "string", "example": "The product title field is required." }, "status": { "type": "integer", "example": 422 }, "success": { "type": "boolean", "example": false }, "errors": { "properties": { "product_title": { "type": "array", "items": { "type": "string", "example": "The product title field is required." } } }, "type": "object" } }, "type": "object" }, "WorkspaceGroupSchema": { "title": "Workspace Group Schema", "description": "Workspace Group schema", "properties": { "id": { "type": "integer", "example": 2 }, "workspace_id": { "type": "integer", "example": 4 }, "name": { "type": "string", "example": "Group 2" }, "slug": { "type": "string", "example": "group-2" }, "description": { "type": "string", "example": "This is my workspace" }, "created_by": { "type": "integer", "example": 223 }, "status": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-03-21 02:45:28" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-03-21 02:45:28" }, "deleted_at": { "type": "string", "format": "date-time", "example": null }, "total_users": { "type": "integer", "example": 1 }, "new_users_last_7_days": { "type": "integer", "example": 1 }, "total_accessible_resources": { "type": "integer", "example": 0 }, "top_users": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 283 }, "full_name": { "type": "string", "example": "John Doe" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "johndoe@example.com" }, "total_resources": { "type": "integer", "example": 2 }, "joined_at": { "type": "string", "format": "date-time", "example": "2025-03-22 09:29:40" } }, "type": "object" } } }, "type": "object" }, "WorkspaceGroupListResponse": { "title": "Workspace Group List Response", "description": "Workspace Group list response", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Workspace groups retrieved successfully" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceGroupSchema" } }, "meta": { "$ref": "#/components/schemas/PagingSchema" } }, "type": "object" }, "WorkspaceGroupResponse": { "title": "Workspace Group Response", "description": "Workspace Group response", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Workspace group retrieved successfully" }, "data": { "$ref": "#/components/schemas/WorkspaceGroupSchema" } }, "type": "object" }, "WorkspaceGroupCreateRequest": { "title": "Workspace Group Create Request", "description": "Workspace Group create request", "properties": { "name": { "type": "string", "example": "Workspace Group Name" }, "description": { "type": "string", "example": "Workspace Group Description" } }, "type": "object" }, "WorkspaceGroupUpdateRequest": { "title": "Workspace Group Update Request", "description": "Workspace Group update request", "properties": { "name": { "type": "string", "example": "Workspace Group Name" }, "description": { "type": "string", "example": "Workspace Group Description" } }, "type": "object" }, "WorkspaceSchema": { "title": "Workspace Schema", "description": "User object schema", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Workspace Name" }, "description": { "type": "string", "example": "Workspace Description" }, "type": { "type": "string", "example": "Workspace Type" }, "created_at": { "type": "string", "format": "date-time", "example": "2021-01-01 00:00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2021-01-01 00:00:00" }, "total_members": { "type": "integer", "example": 1 } }, "type": "object" }, "WorkspaceListResponse": { "title": "Workspace List Response", "description": "Workspace list response", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceSchema" } } }, "type": "object" }, "WorkspaceResponse": { "title": "Workspace Response", "description": "Workspace response", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 200 }, "data": { "$ref": "#/components/schemas/WorkspaceSchema" } }, "type": "object" }, "WorkspaceUpdateRequest": { "title": "Workspace Update Request", "description": "Workspace update request", "properties": { "name": { "type": "string", "example": "Workspace Name" }, "status": { "description": "1: Active, 0: Inactive", "type": "integer", "example": 1 }, "description": { "type": "string", "example": "Workspace Description" } }, "type": "object" } }, "parameters": { "X-Workspace-ID": { "name": "X-Workspace-ID", "in": "header", "description": "Workspace ID", "required": true, "schema": { "type": "integer", "example": 123 } }, "id": { "name": "id", "in": "path", "description": "Object ID", "required": true, "schema": { "type": "integer" } }, "limitParam": { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, "pageParam": { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "sortParam": { "name": "sort", "in": "query", "description": "Field to sort results by. Prefix with '-' for descending order (e.g. -created_at)", "required": false, "schema": { "type": "string", "default": "-created_at" } }, "searchParam": { "name": "search", "in": "query", "description": "Search term to filter results", "required": false, "schema": { "type": "string" } }, "notificationUnreadParam": { "name": "unread", "in": "query", "description": "Filter notifications by unread status (1: unread only, 0: all)", "required": false, "schema": { "type": "integer", "default": 0, "enum": [ 0, 1 ] } }, "notificationTypeParam": { "name": "type", "in": "query", "description": "Filter notifications by type", "required": false, "schema": { "type": "string", "enum": [ "invitation", "resource_share", "site_suspended", "site_reactivated", "new_order" ] } }, "X-Workspace-Id": { "name": "x-workspace-id", "in": "header", "description": "Your workspace ID from Dodgeprint dashboard", "required": true, "schema": { "type": "integer", "example": 100 } }, "Page": { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "example": 1 } }, "Limit": { "name": "limit", "in": "query", "description": "Number of items per page (max: 100)", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "example": 10 } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT Bearer Token authentication. To obtain an API access token, visit: https://app.dodgeprint.com/profile/developer/api-access" } } }, "tags": [ { "name": "Sites", "description": "Manage connected e-commerce sites" }, { "name": "Variant Groups", "description": "Manage variant groups - size/color/SKU configurations for products" }, { "name": "Content Templates", "description": "Manage content templates - titles, descriptions, and images for product listings" }, { "name": "Shipping Profiles", "description": "Manage shipping configurations for different regions and carriers" }, { "name": "Categories", "description": "Manage product categories for e-commerce platforms" }, { "name": "Tags", "description": "Manage product tags for search and organization" }, { "name": "Sections", "description": "Manage Etsy shop sections for organizing products" }, { "name": "Return Policies", "description": "Manage return policies for product listings" }, { "name": "Personalizations", "description": "Manage personalization templates for Etsy products" }, { "name": "Processing Profiles", "description": "Manage processing time profiles for Etsy products. Define how long products take to make (ready_to_ship or made_to_order with 1-10 days/weeks processing time). Used in product deployment via processing_profile_id." }, { "name": "Orders", "description": "Order management and tracking" }, { "name": "Shipments", "description": "Shipment creation and carrier management" }, { "name": "Workspaces", "description": "Workspace management and collaboration" }, { "name": "Ledger Transactions", "description": "Ledger transaction management for Etsy and Shopify sites" }, { "name": "Product Deployment V2 (BETA)", "description": "Product Deployment API V2 - Synchronous single product operations (insert, update, delete)" }, { "name": "Product Types", "description": "Product Types" }, { "name": "Products", "description": "Products" }, { "name": "Tag Templates", "description": "Tag Templates" }, { "name": "Variant Attributes", "description": "Variant Attributes" }, { "name": "Product Deployment", "description": "Product Deployment" }, { "name": "Products on Site", "description": "Products on Site" } ], "x-tagGroups": [ { "name": "Authentication", "tags": [ "Authentication" ] }, { "name": "Sites", "tags": [ "Sites" ] }, { "name": "Listing - Deploy", "tags": [ "Listing - Deploy" ] }, { "name": "Listing - Configuration", "tags": [ "Variant Groups", "Content Templates", "Shipping Profiles", "Categories", "Tags", "Sections", "Return Policies", "Personalizations", "Processing Profiles" ] }, { "name": "Listing - Products", "tags": [ "Listing - Products" ] }, { "name": "Orders", "tags": [ "Orders" ] }, { "name": "Shipments", "tags": [ "Shipments" ] }, { "name": "Workspaces", "tags": [ "Workspaces" ] }, { "name": "Ledger Transactions", "tags": [ "Ledger Transactions" ] } ], "security": [ { "bearerAuth": [] } ] }