{"openapi":"3.0.0","paths":{"/api/v1/health":{"get":{"operationId":"HealthController_check_v1","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"example":"ok"},"info":{"type":"object","example":{"database":{"status":"up","responseTime":12}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["up","degraded","down"]},"responseTime":{"type":"number","description":"Time the health indicator took to respond, in ms"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["up","degraded","down"]},"responseTime":{"type":"number","description":"Time the health indicator took to respond, in ms"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up","responseTime":12}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["up","degraded","down"]},"responseTime":{"type":"number","description":"Time the health indicator took to respond, in ms"}},"additionalProperties":true}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error","shutting_down"],"example":"error"},"info":{"type":"object","example":{"database":{"status":"up","responseTime":12}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["up","degraded","down"]},"responseTime":{"type":"number","description":"Time the health indicator took to respond, in ms"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect","responseTime":3005}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["up","degraded","down"]},"responseTime":{"type":"number","description":"Time the health indicator took to respond, in ms"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up","responseTime":12},"redis":{"status":"down","message":"Could not connect","responseTime":3005}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["up","degraded","down"]},"responseTime":{"type":"number","description":"Time the health indicator took to respond, in ms"}},"additionalProperties":true}}}}}}}},"summary":"Report API and database health","tags":["Health"]}},"/api/v1/me":{"get":{"operationId":"MeController_getMe_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeDto"}}}}},"security":[{"cookie":[]}],"summary":"The signed-in user and the workspaces they belong to","tags":["Workspaces"]},"delete":{"description":"Deletes the workspaces only you use, with everything in them, and removes you from the others. Refused (409) while you own a workspace other people use.","operationId":"MeController_deleteMe_v1","parameters":[],"responses":{"204":{"description":""}},"security":[{"cookie":[]}],"summary":"Delete your account","tags":["Workspaces"]}},"/api/v1/workspaces/{workspaceId}":{"get":{"operationId":"WorkspacesController_getWorkspace_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDto"}}}}},"summary":"A workspace and your role in it","tags":["Workspaces"]},"patch":{"operationId":"WorkspacesController_update_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDto"}}}}},"summary":"Rename a workspace or set its time zone","tags":["Workspaces"]},"delete":{"description":"Disconnects every store (removing the app unless another workspace uses the store), then deletes products, stock, listings, orders, activity and API keys. It cannot be undone.","operationId":"WorkspacesController_deleteWorkspace_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWorkspaceDto"}}}},"responses":{"204":{"description":""}},"summary":"Delete a workspace and everything in it","tags":["Workspaces"]}},"/api/v1/organizations/{organizationId}/workspaces":{"post":{"description":"For owners of a workspace in the organization, such as one per client or brand. You own the new workspace. Refused (402) past the plan’s workspace limit.","operationId":"OrganizationWorkspacesController_create_v1","parameters":[{"name":"organizationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"security":[{"cookie":[]}],"summary":"Create a workspace","tags":["Workspaces"]}},"/api/v1/workspaces/{workspaceId}/members":{"get":{"operationId":"MembersController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceMemberDto"}}}}}},"summary":"The members of a workspace","tags":["Members"]}},"/api/v1/workspaces/{workspaceId}/members/{userId}":{"patch":{"description":"Only for members whose role yours covers, to a role yours covers. Their API keys that the new role could not have created are revoked.","operationId":"MembersController_changeRole_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRoleDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMemberDto"}}}}},"summary":"Change a member's role","tags":["Members"]},"delete":{"description":"Only members whose role yours covers. Their API keys here are revoked.","operationId":"MembersController_remove_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"summary":"Remove a member","tags":["Members"]}},"/api/v1/workspaces/{workspaceId}/membership":{"delete":{"description":"Your API keys here are revoked. Refused (409) for its last owner and for your only workspace.","operationId":"MembershipController_leave_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"cookie":[]}],"summary":"Leave a workspace","tags":["Members"]}},"/api/v1/workspaces/{workspaceId}/invitations":{"get":{"operationId":"InvitationsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvitationDto"}}}}}},"summary":"Pending invitations of a workspace","tags":["Members"]},"post":{"description":"Emails a link that works for 7 days. A new invitation to the same address replaces the pending one. Refused (409) for members and past 50 pending invitations, and (402) when the plan has no seat for someone new to the organization.","operationId":"InvitationsController_invite_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMemberDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"summary":"Invite someone by email","tags":["Members"]}},"/api/v1/workspaces/{workspaceId}/invitations/{invitationId}":{"delete":{"operationId":"InvitationsController_revoke_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"invitationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"summary":"Revoke a pending invitation; its link stops working","tags":["Members"]}},"/api/v1/invitations/preview":{"post":{"description":"Open to anyone with the link, so it can be shown before signing in. 404 when the link is unknown, used, revoked or expired.","operationId":"InvitationLinksController_preview_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationTokenDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationPreviewDto"}}}}},"summary":"What an invitation link is for","tags":["Members"]}},"/api/v1/invitations/accept":{"post":{"description":"Needs a signed-in user whose email is the invited address (403 otherwise).","operationId":"InvitationLinksController_accept_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationTokenDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedInvitationDto"}}}}},"security":[{"cookie":[]}],"summary":"Accept an invitation and join its workspace","tags":["Members"]}},"/api/v1/workspaces/{workspaceId}/roles":{"get":{"operationId":"CustomRolesController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleCatalogDto"}}}}},"summary":"Every role: the built-in ones with their permissions, and custom ones","tags":["Roles"]},"post":{"operationId":"CustomRolesController_create_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomRoleInputDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomRoleDto"}}}}},"summary":"Create a role from permissions you have","tags":["Roles"]}},"/api/v1/workspaces/{workspaceId}/roles/{roleId}":{"put":{"description":"Applies to everyone holding it at once. API keys created by its members that now allow more than the role are revoked.","operationId":"CustomRolesController_update_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"roleId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomRoleInputDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomRoleDto"}}}}},"summary":"Change a role","tags":["Roles"]},"delete":{"description":"Refused (409) while members, pending invitations or API keys hold it.","operationId":"CustomRolesController_delete_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"roleId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"summary":"Delete a role","tags":["Roles"]}},"/api/v1/workspaces/{workspaceId}/api-keys":{"get":{"operationId":"ApiKeysController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyDto"}}}}}},"summary":"Active API keys of a workspace","tags":["API keys"]},"post":{"operationId":"ApiKeysController_create_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuedApiKeyDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"summary":"Create an API key. The secret is returned once.","tags":["API keys"]}},"/api/v1/workspaces/{workspaceId}/api-keys/{apiKeyId}":{"delete":{"description":"Answers 403 unless the caller created the key or has every permission the key has.","operationId":"ApiKeysController_revoke_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"apiKeyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""},"403":{"description":"The key has more access than the caller"}},"summary":"Revoke an API key","tags":["API keys"]}},"/api/v1/api-key":{"get":{"description":"Lets a program, such as the MCP server, find the workspace its key works in.","operationId":"CurrentApiKeyController_get_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentApiKeyDto"}}}}},"summary":"The API key making this request","tags":["API keys"]}},"/api/v1/organizations/{organizationId}/subscription":{"get":{"description":"For people holding `billing:view` (owners and admins) in a workspace of the organization; others in it get 403, and outsiders 404. Usage is counted across all of its workspaces. Needs a signed-in user.","operationId":"OrganizationSubscriptionController_get_v1","parameters":[{"name":"organizationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDto"}}}}},"security":[{"cookie":[]}],"summary":"The organization’s plan, its limits and current usage","tags":["Plans"]}},"/api/v1/workspaces/{workspaceId}/products":{"get":{"description":"Each row’s `stores` badges carry `displayState`, `displayReason` and `displayRequirement`, computed by the same rule as the store’s own pages.","operationId":"ProductsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches title, handle or SKU","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ProductStatus"}},{"name":"gap","required":false,"in":"query","description":"Only products that lack this value","schema":{"$ref":"#/components/schemas/CatalogGap"}},{"name":"tags","required":false,"in":"query","description":"Only products with any of these tags. Repeat the parameter for several.","schema":{"type":"array","items":{"type":"string"}}},{"name":"vendor","required":false,"in":"query","description":"Only products of this vendor, ignoring case","schema":{"type":"string"}},{"name":"storeFilter","required":false,"in":"query","description":"By the stores products are in; `in_store` and `not_in_store` need `storeId`","schema":{"$ref":"#/components/schemas/ProductStoreFilter"}},{"name":"storeId","required":false,"in":"query","description":"The store `storeFilter` is about","schema":{"format":"uuid","type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"title","allOf":[{"$ref":"#/components/schemas/ProductSort"}]}},{"name":"direction","required":false,"in":"query","schema":{"default":"asc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPageDto"}}}}},"summary":"Products of a workspace, in title order","tags":["Catalog"]},"post":{"operationId":"ProductsController_create_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDto"}}}}},"summary":"Create a product with its variants","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}":{"get":{"operationId":"ProductsController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDto"}}}}},"summary":"A product with its variants, stock and media","tags":["Catalog"]},"put":{"description":"Variants sent with an id are edited, new ones are added and missing ones are removed. Stock changes are written to the inventory ledger as adjustments.","operationId":"ProductsController_update_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDto"}}}}},"summary":"Replace a product","tags":["Catalog"]},"delete":{"operationId":"ProductsController_delete_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"summary":"Delete a product, its variants and their stock","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/product-bulk-actions":{"post":{"description":"Set a status, add or remove tags, move every variant price by a percentage, or delete. Each action runs as one statement, scoped to the workspace.","operationId":"ProductBulkActionsController_apply_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkProductActionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkProductResultDto"}}}}},"summary":"Change many products at once","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/product-views":{"get":{"operationId":"ProductViewsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductViewDto"}}}}}},"summary":"Saved filters of the product list, oldest first","tags":["Catalog"]},"post":{"operationId":"ProductViewsController_create_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductViewDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductViewDto"}}}}},"summary":"Save the current filters of the product list as a view","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/product-views/{viewId}":{"delete":{"operationId":"ProductViewsController_delete_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"viewId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"summary":"Delete a saved view","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/product-imports":{"post":{"description":"In `create` mode, products whose handle is already in the catalog are skipped, never overwritten. In `update` mode, products are found by handle and only the columns in the file change: a missing column keeps its value, an empty cell clears it. Variants are matched by SKU, then by option values, and are never deleted; stock is left as it is. In `inventory` mode, a `sku,available` CSV sets the stock of tracked variants. Invalid records are reported; the rest are applied. Every import is recorded in the import history. Product modes need `products:edit`, `inventory` needs `inventory:edit`.","operationId":"ProductImportsController_import_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"allOf":[{"$ref":"#/components/schemas/ImportProductsDto"},{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The catalog file"}}}]}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportResultDto"}}}}},"summary":"Import products or stock from a file","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/import-jobs":{"get":{"operationId":"ImportJobsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ImportJobStatus"}},{"name":"format","required":false,"in":"query","description":"Where the records came from: a file of this format, or a channel","schema":{"$ref":"#/components/schemas/CatalogImportFormat"}},{"name":"direction","required":false,"in":"query","schema":{"default":"desc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobPageDto"}}}}},"summary":"Import history of a workspace, newest first","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/import-jobs/{jobId}":{"get":{"operationId":"ImportJobsController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobDetailDto"}}}}},"summary":"An import with its skipped and failed records","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/media/product-images":{"post":{"description":"Returns a URL to put in a product’s `media`. The format is read from the file.","operationId":"ProductImagesController_upload_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, WebP or GIF"}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedImageDto"}}}}},"summary":"Upload a product image","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/catalog-stats":{"get":{"operationId":"CatalogStatsController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogStatsDto"}}}}},"summary":"Product and stock counts for the workspace overview","tags":["Catalog"]}},"/api/v1/workspaces/{workspaceId}/activity":{"get":{"description":"Includes operations that failed, such as an import that created nothing.","operationId":"ActivityController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"action","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ActivityAction"}},{"name":"outcome","required":false,"in":"query","description":"`FAILED` lists only what went wrong","schema":{"$ref":"#/components/schemas/ActivityOutcome"}},{"name":"direction","required":false,"in":"query","schema":{"default":"desc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"subjectType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ActivitySubjectType"}},{"name":"subjectId","required":false,"in":"query","description":"Events about this record, including bulk actions that touched it","schema":{"format":"uuid","type":"string"}},{"name":"actorUserId","required":false,"in":"query","description":"Only what this user did","schema":{"format":"uuid","type":"string"}},{"name":"actorApiKeyId","required":false,"in":"query","description":"Only what this API key did","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityPageDto"}}}}},"summary":"Who changed what in the workspace, newest first","tags":["Activity"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/activity":{"get":{"description":"Includes bulk actions that changed it, and its deletion.","operationId":"ProductActivityController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"type":"string"}},{"name":"action","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ActivityAction"}},{"name":"outcome","required":false,"in":"query","description":"`FAILED` lists only what went wrong","schema":{"$ref":"#/components/schemas/ActivityOutcome"}},{"name":"direction","required":false,"in":"query","schema":{"default":"desc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityPageDto"}}}}},"summary":"The history of one product, newest first","tags":["Activity"]}},"/api/v1/workspaces/{workspaceId}/inventory-items":{"get":{"operationId":"InventoryItemsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the SKU or the product title","schema":{"type":"string"}},{"name":"stockLevel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/StockLevel"}},{"name":"sort","required":false,"in":"query","schema":{"default":"title","allOf":[{"$ref":"#/components/schemas/InventorySort"}]}},{"name":"direction","required":false,"in":"query","schema":{"default":"asc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryPageDto"}}}}},"summary":"Stock of every variant, by product title","tags":["Inventory"]}},"/api/v1/workspaces/{workspaceId}/inventory-items/{inventoryItemId}/adjustments":{"post":{"description":"Adds or removes units, or sets the counted stock, and records the change in the ledger with its reason and author. Reserved units are not changed.","operationId":"InventoryItemsController_adjust_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustStockDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemDto"}}}}},"summary":"Adjust the stock on hand of a variant","tags":["Inventory"]}},"/api/v1/workspaces/{workspaceId}/inventory-items/{inventoryItemId}/movements":{"get":{"operationId":"InventoryItemsController_history_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}},{"name":"reason","required":false,"in":"query","schema":{"$ref":"#/components/schemas/InventoryMovementReason"}},{"name":"direction","required":false,"in":"query","schema":{"default":"desc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMovementPageDto"}}}}},"summary":"Stock history of a variant, newest first","tags":["Inventory"]}},"/api/v1/workspaces/{workspaceId}/channel-connections":{"get":{"operationId":"ChannelConnectionsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}}},"summary":"Channel accounts connected to the workspace, in connection order","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/authorizations":{"post":{"description":"Returns the URL to send the merchant to. After they approve the app, the channel redirects to the API, which stores the connection and sends them back to the web app’s Channels page with the parameters of `ChannelConnectRedirectDto`. Needs a signed-in user, and the browser must store the cookie this response sets (send it with credentials): the callback only accepts the same browser and session that started the connection.","operationId":"ChannelConnectionsController_startAuthorization_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAuthorizationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedAuthorizationDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"summary":"Start connecting a channel account","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}":{"get":{"operationId":"ChannelConnectionsController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"One channel connection","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/disconnect":{"post":{"description":"Revokes Crossmart’s access on the channel (for Shopify, uninstalls the app unless another workspace uses the same store) and wipes the stored credentials. Listings stay.","operationId":"ChannelConnectionsController_disconnect_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Disconnect a channel account","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/imports":{"post":{"description":"Queues an import of every product of the channel account. Products already linked to it are refreshed, products that match the catalog by handle or SKU are linked, and the rest are created with their stock. Returns the import history entry; poll it with `GET /import-jobs/{jobId}` to follow the progress. While an import of the connection runs, this returns that import instead of starting another. 409 when the connection is not connected.","operationId":"ChannelImportsController_start_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobDetailDto"}}}}},"summary":"Import the connected channel’s catalog","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/ebay/listing-defaults":{"put":{"description":"Business policies, condition and ship-from address for every listing. The address is saved on eBay as the account’s Crossmart inventory location.","operationId":"EbayAccountController_saveListingDefaults_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEbayListingDefaultsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Set an eBay connection’s listing defaults","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/ebay/business-policies/opt-in":{"post":{"description":"eBay may take a few minutes to enable them; refresh the policies once they are created.","operationId":"EbayAccountController_optInToBusinessPolicies_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Opt an eBay account in to business policies","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/ebay/business-policies/defaults":{"post":{"description":"Creates free standard shipping, immediate payment and 30-day return policies on the eBay account (opting it in to business policies first when needed), reads the policies again and chooses the new ones as the listing defaults. Policies that already exist are used as they are, so calling this twice is harmless. Marketplaces without a default shipping service answer 422.","operationId":"EbayAccountController_createDefaultPolicies_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Create default business policies on an eBay account","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/ebay/business-policies/refresh":{"post":{"description":"After the merchant creates or edits policies on eBay. Defaults are kept.","operationId":"EbayAccountController_refreshPolicies_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Read an eBay account’s business policies again","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/google-merchant/listing-setup":{"put":{"description":"The country listings target (their currency and language follow) and each product’s page address. Saving creates the Merchant Center API data source for a new country.","operationId":"GoogleMerchantAccountController_saveListingSetup_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGoogleListingSetupDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Set where a Google Merchant Center connection lists","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/etsy/listing-setup":{"put":{"description":"Who made the items, when, whether they are supplies, and the shop’s shipping and processing profiles every listing uses. Etsy requires all of them for physical listings.","operationId":"EtsyShopController_saveListingSetup_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEtsyListingSetupDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Set an Etsy connection’s listing setup","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/etsy/shop/refresh":{"post":{"description":"After the merchant creates or edits shipping or processing profiles on Etsy. The listing setup is kept.","operationId":"EtsyShopController_refreshShop_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Read an Etsy shop and its profiles again","tags":["Channels"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/products":{"get":{"description":"Products the store should have or still has: listed, pending (being published), failed or removing (being delisted). Pass `state=excluded` for the catalog products it does not have. `displayState` narrows them to the state a merchant reads (`needs_details`, `ready`, …). Counts per state follow `search`, so they can label filter tabs.","operationId":"ChannelProductsController_listProducts_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"state","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ChannelProductState"}},{"name":"displayState","required":false,"in":"query","description":"Only products showing this display state. Without `state` it looks at every catalog product, so `draft` and `removed` find those not in the store.","schema":{"$ref":"#/components/schemas/ListingDisplayState"}},{"name":"search","required":false,"in":"query","description":"Matches title, handle or SKU","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"title","allOf":[{"$ref":"#/components/schemas/ChannelProductSort"}]}},{"name":"direction","required":false,"in":"query","schema":{"default":"asc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelProductPageDto"}}}}},"summary":"The store’s products with their state on the channel","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/pricing":{"put":{"description":"The store’s listings get the new prices at once. A null rule sends catalog prices.","operationId":"ChannelRulesController_updatePricing_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePricingDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}}},"summary":"Set the connection’s pricing rule","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/pricing/preview":{"post":{"description":"Without `productId`, the first product of the selection is priced.","operationId":"ChannelRulesController_previewPricing_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingPreviewRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingPreviewDto"}}}}},"summary":"Price a real product with a rule, saved or not","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/product-selection":{"put":{"description":"Applies at once: products the rule now adds are published, and products it now drops are delisted. Products added by hand stay; those removed by hand stay out. Refused (402) without saving when the plan has no room for the active listings it would add.","operationId":"ChannelSelectionController_updateSelection_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductSelectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnectionDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"summary":"Set the store’s automatic rule","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/product-selection/preview":{"post":{"operationId":"ChannelSelectionController_previewSelection_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductSelectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectionPreviewDto"}}}}},"summary":"The products a selection lists, with counts, saved or not","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/sync":{"post":{"description":"Queues every selected product to be published (or updated when the channel has it) and every listing that is no longer selected to be delisted. Jobs run in the background. Each listing it queues is marked (`syncRequestedAt`, `displayState: publishing`) until its job finishes; follow them with `GET …/sync`. Refused (402) before anything is queued when the plan has no room for the active listings it would add.","operationId":"ChannelSyncController_requestSync_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRequestResultDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"summary":"Publish the selected products and sync the connection","tags":["Listings"]},"get":{"description":"Counts the listings a sync or retry queued whose job has not finished yet, and those in error. Poll it after `POST …/sync`: the sync is done when `pending` is 0.","operationId":"ChannelSyncController_syncProgress_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncProgressDto"}}}}},"summary":"How far the connection’s sync has come","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/listings":{"get":{"operationId":"ChannelSyncController_listListings_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ListingStatus"}},{"name":"cursor","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelListingPageDto"}}}}},"summary":"The connection’s listings, most recently changed first","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/products/add":{"post":{"description":"They stay until removed and are published at once. Refused (402) without changes when the plan has no room for the active listings they would add.","operationId":"StoreProductsController_add_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreProductsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreProductsResultDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}}},"summary":"Add products to the store","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/channel-connections/{connectionId}/products/remove":{"post":{"description":"They are delisted at once, and the automatic rule leaves them out.","operationId":"StoreProductsController_remove_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreProductsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreProductsResultDto"}}}}},"summary":"Remove products from the store","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels":{"get":{"description":"Listing status, channel prices with their explanation, shown stock and overrides.","operationId":"ProductChannelsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductChannelDto"}}}}}},"summary":"The product on each connected channel","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}":{"post":{"description":"The product stays in the store until it is removed, whatever the automatic rule says, and is published there at once.","operationId":"ProductChannelsController_add_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}}},"summary":"Add the product to a store","tags":["Listings"]},"delete":{"description":"The product is delisted there at once, and the automatic rule leaves it out.","operationId":"ProductChannelsController_remove_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}}},"summary":"Remove the product from a store","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}/retry":{"post":{"description":"Re-queues this product’s publish (or update) to this store only, unlike `POST …/sync`, which resyncs the whole store. A failed or delisted listing becomes pending at once, so the answer shows `displayState: publishing`; the job runs in the background. Refused (409) when the store is not connected (`code: store_not_connected`: it needs re-auth or was disconnected) or does not select the product (`code: product_not_in_store`), and (402) when the plan has no room for another active listing.","operationId":"ProductChannelsController_retry_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}},"404":{"description":"The product or the store is not in the workspace"},"409":{"description":"The store is not connected (`store_not_connected`), or the product is not selected for it (`product_not_in_store`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingRetryErrorDto"}}}}},"summary":"Publish the product to one store again","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}/override":{"put":{"description":"Replaces the overrides: absent or null fields follow the product. When the channel already lists the product, an update is queued.","operationId":"ProductChannelsController_saveOverride_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingOverrideDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}}},"summary":"Override the product on one channel","tags":["Listings"]},"patch":{"description":"Absent fields keep their override; null reverts a field to the product’s value. Each `variantPrices` entry replaces that variant’s prices only, and both prices null revert the variant to the pricing rule. When the channel already lists the product, an update is queued.","operationId":"ProductChannelsController_patchOverride_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingOverridePatchDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}}},"summary":"Change some of the product’s overrides on one channel","tags":["Listings"]},"delete":{"operationId":"ProductChannelsController_clearOverride_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}}},"summary":"Remove the product’s overrides on one channel","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}/listing":{"get":{"description":"Every field (title, description, tags, images, visibility, and each variant’s price and compare-at price) with the product’s value, the store’s override (null when it follows the product) and the value the store gets, plus the stock limits, category, a summary of the item specifics and the display state. Revert one field with `PATCH …/override`.","operationId":"ListingEditorController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingEditorDto"}}}},"404":{"description":"The product or the store is not in the workspace"}},"summary":"The product’s listing on one store, for the listing editor","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}/category-suggestions":{"get":{"description":"Searches the channel’s categories for `search`, or for the product’s title.","operationId":"ProductChannelCategoryController_suggest_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Keywords; the product’s title when absent","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChannelCategoryDto"}}}}}},"summary":"Suggest channel categories for the product","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}/category":{"put":{"description":"Null lets the next publish pick the channel’s best match. When the channel already lists the product, an update is queued.","operationId":"ProductChannelCategoryController_choose_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChooseChannelCategoryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductChannelDto"}}}}},"summary":"Choose the product’s channel category","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/products/{productId}/channels/{connectionId}/item-specifics":{"get":{"description":"The item specifics the listing’s channel category asks for (none until it has a category), with the values set on the listing.","operationId":"ProductChannelItemSpecificsController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingItemSpecificsDto"}}}}},"summary":"Get the listing’s item specifics","tags":["Listings"]},"put":{"description":"Replaces the item specifics set on the listing. They are sent on publish ahead of the ones Crossmart derives (such as Brand from the vendor). The listing is sent again when the channel holds it or its last publish failed.","operationId":"ProductChannelItemSpecificsController_save_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveItemSpecificsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingItemSpecificsDto"}}}}},"summary":"Set the listing’s item specifics","tags":["Listings"]}},"/api/v1/workspaces/{workspaceId}/orders":{"get":{"description":"Orders hold no buyer details. Each line shows the stock it holds.","operationId":"OrdersController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/OrderStatus"}},{"name":"connectionId","required":false,"in":"query","description":"Orders of one store","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Matches the order number","schema":{"type":"string"}},{"name":"direction","required":false,"in":"query","schema":{"default":"desc","allOf":[{"$ref":"#/components/schemas/SortDirection"}]}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPageDto"}}}}},"summary":"Orders from every connected store, newest first","tags":["Orders"]}},"/api/v1/workspaces/{workspaceId}/orders/{orderId}":{"get":{"operationId":"OrdersController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"orderId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetailDto"}}}}},"summary":"One order with its lines and the stock each holds","tags":["Orders"]}},"/api/v1/workspaces/{workspaceId}/analytics/sales":{"get":{"description":"Order totals in the workspace currency, bucketed in the given time zone. Cancelled orders and orders in other currencies are left out.","operationId":"SalesReportController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"range","required":false,"in":"query","schema":{"default":"last_30_days","allOf":[{"$ref":"#/components/schemas/SalesRange"}]}},{"name":"timeZone","required":false,"in":"query","description":"IANA time zone that days, weeks and months follow. Defaults to the workspace's time zone, else UTC.","schema":{"example":"America/New_York","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesReportDto"}}}}},"summary":"Sales over time, by store, compared with the period before","tags":["Analytics"]}},"/api/v1/workspaces/{workspaceId}/analytics/inventory":{"get":{"description":"Values are in the workspace currency; variants without a cost are counted apart.","operationId":"InventoryReportController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryReportDto"}}}}},"summary":"Stock value, stock levels and each store’s listings, as of now","tags":["Analytics"]}},"/api/v1/workspaces/{workspaceId}/analytics/listings":{"get":{"description":"Counts follow the same rule as each store’s product list. Each failed listing carries `displayState`, `displayReason` and `displayRequirement`, so a client can link to the fix.","operationId":"ListingHealthReportController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingHealthReportDto"}}}}},"summary":"Each store’s products by display state, and the latest failed listings, as of now","tags":["Analytics"]}},"/api/v1/workspaces/{workspaceId}/suggestions":{"get":{"description":"Filter by `PENDING` for the inbox.","operationId":"SuggestionsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"`PENDING` is the inbox","schema":{"$ref":"#/components/schemas/SuggestionStatus"}},{"name":"productId","required":false,"in":"query","description":"Suggestions for one product","schema":{"format":"uuid","type":"string"}},{"name":"connectionId","required":false,"in":"query","description":"Suggestions for one store","schema":{"format":"uuid","type":"string"}},{"name":"kind","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SuggestionKind"}},{"name":"cursor","required":false,"in":"query","description":"`nextCursor` from the previous page","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","description":"1-based page number, for tables with page numbers. It wins over `cursor`.","schema":{"minimum":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionPageDto"}}}}},"summary":"Suggestions, newest first","tags":["Suggestions"]}},"/api/v1/workspaces/{workspaceId}/suggestions/bulk-approve":{"post":{"description":"Applies each pending suggestion, or marks it `STALE` when its field changed since it was made. Suggestions that are not pending are skipped.","operationId":"SuggestionsController_bulkApprove_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkApproveSuggestionsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReviewResultDto"}}}}},"summary":"Approve several suggestions","tags":["Suggestions"]}},"/api/v1/workspaces/{workspaceId}/suggestions/{suggestionId}":{"get":{"operationId":"SuggestionsController_get_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"suggestionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionDto"}}}}},"summary":"One suggestion","tags":["Suggestions"]}},"/api/v1/workspaces/{workspaceId}/suggestions/{suggestionId}/approve":{"post":{"description":"Applies the change the way an edit would (a channel override, synced to the store), and returns it `APPLIED`. When its field changed since it was made, nothing is applied and it returns `STALE`. A suggestion that is no longer pending answers 409.","operationId":"SuggestionsController_approve_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"suggestionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionDto"}}}}},"summary":"Approve a suggestion","tags":["Suggestions"]}},"/api/v1/workspaces/{workspaceId}/suggestions/{suggestionId}/reject":{"post":{"description":"Nothing is changed. A suggestion that is no longer pending answers 409.","operationId":"SuggestionsController_reject_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}},{"name":"suggestionId","required":true,"in":"path","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionDto"}}}}},"summary":"Reject a suggestion","tags":["Suggestions"]}},"/api/v1/workspaces/{workspaceId}/ai/status":{"get":{"operationId":"AiController_status_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiStatusDto"}}}}},"summary":"Whether AI features are available on this server","tags":["AI"]}},"/api/v1/workspaces/{workspaceId}/ai/usage":{"get":{"description":"Per feature and model, in a period; the current UTC month by default.","operationId":"AiController_usageReport_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Start, included","schema":{"format":"date-time","type":"string"}},{"name":"to","required":false,"in":"query","description":"End, excluded","schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiUsageReportDto"}}}}},"summary":"AI calls and tokens used by the workspace","tags":["AI"]}},"/api/v1/workspaces/{workspaceId}/ai/content-generations":{"post":{"description":"Queues the Content Generator for each product: it writes a title and description fitted to the store’s channel. The results arrive as pending suggestions to review; nothing changes until one is approved. Each product uses one AI credit: answers 402 when the plan’s credits this month do not cover them (while plans are enforced), 429 past the rate limit, and 503 while AI is not configured.","operationId":"AiController_generateContent_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateContentDto"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentGenerationReceiptDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}},"429":{"description":"Too many AI requests from you in this workspace. Wait a minute and try again."}},"summary":"Generate channel content with AI","tags":["AI"]}},"/api/v1/workspaces/{workspaceId}/ai/content-drafts":{"post":{"description":"Rewrites the fields asked for, for the catalog or for one store, optionally following an instruction. The answer is a draft for the editor: nothing is stored until the merchant saves it. Uses one AI credit: answers 402 when the plan has none left this month (while plans are enforced), 429 past the rate limit, and 503 while AI is not configured.","operationId":"AiController_draftContent_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContentDraftDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentDraftDto"}}}},"402":{"description":"The organization’s plan does not allow this (`ENTITLEMENTS_ENFORCED` is on). `code` and `feature` say why; upgrading the plan resolves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitErrorDto"}}}},"429":{"description":"Too many AI requests from you in this workspace. Wait a minute and try again."}},"summary":"Rewrite a product’s title or description with AI, right away","tags":["AI"]}},"/api/v1/oauth/workspace":{"post":{"description":"Called by the web app before it continues the OAuth flow. The agent will only ever act in this workspace, within your role there.","operationId":"AgentAuthorizationController_pickWorkspace_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickAgentWorkspaceDto"}}}},"responses":{"204":{"description":""}},"security":[{"cookie":[]}],"summary":"Pick the workspace for the agent being authorized","tags":["Agents"]}},"/api/v1/workspaces/{workspaceId}/agent-connections":{"get":{"description":"Your own connections, or every member’s if you may manage API keys. Signed-in users only.","operationId":"AgentConnectionsController_list_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentConnectionDto"}}}}}},"security":[{"cookie":[]}],"summary":"AI agents connected to the workspace","tags":["Agents"]}},"/api/v1/workspaces/{workspaceId}/agent-connections/{connectionId}":{"delete":{"description":"Revokes its tokens at once. The agent must be authorized again to come back.","operationId":"AgentConnectionsController_revoke_v1","parameters":[{"name":"workspaceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"connectionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"cookie":[]}],"summary":"Disconnect an agent","tags":["Agents"]}},"/api/v1/ask":{"post":{"description":"Answers from Crossmart’s public documentation and plan lineup only, citing the pages it used. When they do not answer the question, `outcome` is `unknown` and the answer points to the support address. It never sees or changes any account or workspace data. No credentials are needed: anonymous callers may ask 5 questions a minute and 50 a day per IP address; with an API key, session or agent token, 20 a minute and 500 a day. Answers 429 past those, and 503 when AI is not configured or the platform’s daily question budget is spent.","operationId":"AskController_ask_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskQuestionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskAnswerDto"}}}},"429":{"description":"Too many questions from you. Wait a little and try again, or browse https://docs.crossmart.io."},"503":{"description":"AI is not configured, Ask is turned off, or today’s questions are spent"}},"security":[{},{"bearer":[]},{"cookie":[]},{"api_key":[]}],"summary":"Ask a question about Crossmart","tags":["Ask Crossmart"]}}},"info":{"title":"Crossmart API","description":"REST API of Crossmart, the open-source multichannel platform for sellers and their AI agents.","version":"0.0.0","contact":{},"license":{"name":"AGPL-3.0","url":"https://www.gnu.org/licenses/agpl-3.0.html"}},"tags":[],"servers":[],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"x-api-key"},"cookie":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"},"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"An AI agent’s OAuth access token, for workspace routes only. Agents get one by signing in through the MCP server (see docs/mcp.md)."}},"schemas":{"WorkspaceRole":{"type":"string","enum":["OWNER","ADMIN","EDITOR","APPROVER","VIEWER","CUSTOM"],"description":"Your role here"},"CustomRoleRefDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"WorkspacePermission":{"type":"string","enum":["workspace:view","workspace:manage","workspace:delete","members:view","members:manage","api-keys:manage","products:view","products:edit","inventory:view","inventory:edit","orders:view","reports:view","channels:view","channels:manage","listings:edit","activity:view","suggestions:view","suggestions:approve","billing:view","ai:generate"],"description":"What your role lets you do here. Check these, not the role, to adapt a UI."},"WorkspaceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"displayName":{"type":"string","description":"The name to show: the organization name while the workspace is named Default"},"slug":{"type":"string"},"currency":{"type":"string","example":"USD","description":"ISO 4217 code of the catalog prices"},"timeZone":{"type":"string","nullable":true,"example":"Asia/Jerusalem","description":"IANA time zone that reports follow; null until set"},"role":{"description":"Your role here","allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRole":{"nullable":true,"description":"The workspace’s own role, when `role` is CUSTOM","type":"object","allOf":[{"$ref":"#/components/schemas/CustomRoleRefDto"}]},"permissions":{"type":"array","description":"What your role lets you do here. Check these, not the role, to adapt a UI.","items":{"$ref":"#/components/schemas/WorkspacePermission"}}},"required":["id","organizationId","name","displayName","slug","currency","timeZone","role","customRole","permissions"]},"MeDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceDto"}}},"required":["id","name","email","workspaces"]},"UpdateWorkspaceDto":{"type":"object","properties":{"name":{"type":"string","example":"EU store","maxLength":200},"timeZone":{"type":"string","example":"Asia/Jerusalem","description":"IANA time zone where the workspace’s day starts, for reports, such as Asia/Jerusalem"}}},"DeleteWorkspaceDto":{"type":"object","properties":{"confirmName":{"type":"string","description":"The workspace’s name, typed to confirm: deleting it cannot be undone","maxLength":200}},"required":["confirmName"]},"CreateWorkspaceDto":{"type":"object","properties":{"name":{"type":"string","example":"EU store","maxLength":200},"currency":{"type":"string","example":"EUR","default":"USD","description":"ISO 4217 code of the catalog prices. It cannot change later."},"timeZone":{"type":"string","example":"Europe/Berlin","description":"IANA time zone where the workspace’s day starts, for reports, such as Asia/Jerusalem"}},"required":["name"]},"EntitlementErrorCode":{"type":"string","enum":["plan_limit_reached","plan_feature_not_included"]},"Feature":{"type":"string","enum":["active_listings","channel_connections","workspaces","members","api_keys","ai_credits","autonomous_agents","bring_your_own_key"]},"PlanLimitErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":402},"error":{"type":"string","example":"Payment Required"},"code":{"allOf":[{"$ref":"#/components/schemas/EntitlementErrorCode"}]},"message":{"type":"string","example":"The Free plan includes 2 connected channels, and 2 are in use. Upgrade the plan to add more."},"feature":{"allOf":[{"$ref":"#/components/schemas/Feature"}]},"plan":{"type":"string","example":"free","description":"The code of the organization’s plan"},"limit":{"type":"number","nullable":true,"description":"Null is unlimited"},"usage":{"type":"number"},"requested":{"type":"number","description":"How many more the request asked for"}},"required":["statusCode","error","code","message","feature","plan","limit","usage","requested"]},"WorkspaceMemberDto":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRole":{"nullable":true,"description":"The workspace’s own role, when `role` is CUSTOM","type":"object","allOf":[{"$ref":"#/components/schemas/CustomRoleRefDto"}]},"joinedAt":{"format":"date-time","type":"string"}},"required":["userId","name","email","role","customRole","joinedAt"]},"UpdateMemberRoleDto":{"type":"object","properties":{"role":{"description":"At most your own access. CUSTOM needs `customRoleId`.","allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRoleId":{"type":"string","format":"uuid","description":"One of the workspace’s roles, with CUSTOM"}},"required":["role"]},"InvitationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRole":{"nullable":true,"description":"The workspace’s own role, when `role` is CUSTOM","type":"object","allOf":[{"$ref":"#/components/schemas/CustomRoleRefDto"}]},"invitedByName":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","email","role","customRole","invitedByName","expiresAt","createdAt"]},"InviteMemberDto":{"type":"object","properties":{"role":{"description":"At most your own access. CUSTOM needs `customRoleId`.","allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRoleId":{"type":"string","format":"uuid","description":"One of the workspace’s roles, with CUSTOM"},"email":{"type":"string","example":"dana@example.com","maxLength":254}},"required":["role","email"]},"InvitationTokenDto":{"type":"object","properties":{"token":{"type":"string","maxLength":128}},"required":["token"]},"InvitationPreviewDto":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace's display name"},"inviterName":{"type":"string"},"email":{"type":"string","description":"The address invited; accepting needs an account with it"},"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"roleName":{"type":"string","example":"Editor","description":"The role as people read it"},"expiresAt":{"format":"date-time","type":"string"}},"required":["workspaceName","inviterName","email","role","roleName","expiresAt"]},"AcceptedInvitationDto":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]}},"required":["workspaceId","role"]},"BuiltInRoleDto":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspacePermission"}}},"required":["role","permissions"]},"CustomRoleDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspacePermission"}},"memberCount":{"type":"number","description":"Members holding the role now"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","description","permissions","memberCount","createdAt","updatedAt"]},"RoleCatalogDto":{"type":"object","properties":{"builtIn":{"description":"Most access first","type":"array","items":{"$ref":"#/components/schemas/BuiltInRoleDto"}},"custom":{"description":"By name","type":"array","items":{"$ref":"#/components/schemas/CustomRoleDto"}}},"required":["builtIn","custom"]},"CustomRoleInputDto":{"type":"object","properties":{"name":{"type":"string","example":"Stock clerk","maxLength":60},"description":{"type":"string","maxLength":200,"nullable":true},"permissions":{"type":"array","description":"At most your own permissions. workspace:view is always added; workspace:delete is for owners only.","items":{"$ref":"#/components/schemas/WorkspacePermission"}}},"required":["name","permissions"]},"ApiKeyDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRole":{"nullable":true,"description":"The workspace’s own role, when `role` is CUSTOM","type":"object","allOf":[{"$ref":"#/components/schemas/CustomRoleRefDto"}]},"prefix":{"type":"string","description":"The first characters of the key, to tell keys apart"},"lastUsedAt":{"format":"date-time","type":"string","nullable":true},"expiresAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","name","role","customRole","prefix","lastUsedAt","expiresAt","createdAt"]},"CreateApiKeyDto":{"type":"object","properties":{"role":{"description":"At most your own access. CUSTOM needs `customRoleId`.","allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRoleId":{"type":"string","format":"uuid","description":"One of the workspace’s roles, with CUSTOM"},"name":{"type":"string","example":"Claude Desktop","maxLength":100},"expiresAt":{"format":"date-time","type":"string","description":"Leave empty for a key that does not expire"}},"required":["role","name"]},"IssuedApiKeyDto":{"type":"object","properties":{"apiKey":{"$ref":"#/components/schemas/ApiKeyDto"},"secret":{"type":"string","description":"The full key. Shown once; store it now."}},"required":["apiKey","secret"]},"CurrentApiKeyDto":{"type":"object","properties":{"apiKeyId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid","description":"The one workspace the key works in"},"role":{"allOf":[{"$ref":"#/components/schemas/WorkspaceRole"}]},"customRole":{"nullable":true,"description":"The workspace’s own role, when `role` is CUSTOM","type":"object","allOf":[{"$ref":"#/components/schemas/CustomRoleRefDto"}]},"permissions":{"type":"array","description":"What the key may do","items":{"$ref":"#/components/schemas/WorkspacePermission"}}},"required":["apiKeyId","workspaceId","role","customRole","permissions"]},"PlanDto":{"type":"object","properties":{"code":{"type":"string","example":"growth","description":"Stable identifier of the plan"},"name":{"type":"string","example":"Growth"},"version":{"type":"number","example":1,"description":"The plan version the organization is on; later versions never change it"},"offered":{"type":"boolean","description":"Whether new organizations can choose this plan. False for a legacy plan, which an organization already on it keeps"}},"required":["code","name","version","offered"]},"SubscriptionStatus":{"type":"string","enum":["ACTIVE","TRIALING","PAST_DUE","CANCELED"]},"FeatureKind":{"type":"string","enum":["limit","flag"],"description":"A counted limit, or a flag the plan turns on or off"},"FeatureUsageDto":{"type":"object","properties":{"feature":{"allOf":[{"$ref":"#/components/schemas/Feature"}]},"kind":{"description":"A counted limit, or a flag the plan turns on or off","allOf":[{"$ref":"#/components/schemas/FeatureKind"}]},"enabled":{"type":"boolean","description":"Whether the plan includes the feature at all"},"limit":{"type":"number","nullable":true,"description":"How many the plan allows; null is unlimited, 0 is not included"},"usage":{"type":"number","nullable":true,"description":"How many are in use now, across the organization; null for flags"}},"required":["feature","kind","enabled","limit","usage"]},"SubscriptionDto":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid"},"plan":{"$ref":"#/components/schemas/PlanDto"},"status":{"allOf":[{"$ref":"#/components/schemas/SubscriptionStatus"}]},"currentPeriodEnd":{"type":"string","format":"date-time","nullable":true,"description":"When the paid period ends; null until billing is connected"},"enforced":{"type":"boolean","description":"Whether limits block actions here (402), or are only reported"},"features":{"description":"Every feature, with what the plan allows and what is in use","type":"array","items":{"$ref":"#/components/schemas/FeatureUsageDto"}}},"required":["organizationId","plan","status","currentPeriodEnd","enforced","features"]},"ProductStatus":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"]},"CatalogGap":{"type":"string","enum":["images","description","sku","barcode","out_of_stock"]},"ProductStoreFilter":{"type":"string","enum":["in_store","not_in_store","in_no_store","with_errors"]},"ProductSort":{"type":"string","enum":["title","updatedAt","createdAt"]},"SortDirection":{"type":"string","enum":["asc","desc"]},"PriceRangeDto":{"type":"object","properties":{"min":{"type":"string","example":"22.00","description":"Decimal string in the workspace currency"},"max":{"type":"string","example":"89.00"}},"required":["min","max"]},"ChannelType":{"type":"string","enum":["shopify","ebay","google_merchant","etsy","amazon","walmart"]},"ListingStatus":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE","ERROR","DELISTED"]},"ListingSource":{"type":"string","enum":["MANUAL","IMPORT","RULE"]},"ListingDisplayState":{"type":"string","enum":["draft","needs_details","ready","publishing","published","failed","removing","removed"],"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`."},"PublishRequirement":{"type":"string","enum":["reconnect","account_settings","shipping_policy","payment_policy","return_policy","ship_from_location","listing_setup","item_details","shipping_profile","processing_profile","images","active_product","category","item_specifics","option_names"],"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states."},"ProductStoreBadgeDto":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"channel":{"allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"storeName":{"type":"string","example":"Demo Store"},"status":{"allOf":[{"$ref":"#/components/schemas/ListingStatus"}]},"source":{"allOf":[{"$ref":"#/components/schemas/ListingSource"}]},"displayState":{"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`.","allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"displayReason":{"type":"string","nullable":true,"example":"Choose a shipping policy in this eBay connection’s listing defaults.","description":"For `needs_details` and `failed`: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states."},"displayRequirement":{"nullable":true,"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states.","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]}},"required":["connectionId","channel","storeName","status","source","displayState","displayReason","displayRequirement"]},"ProductSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"handle":{"type":"string"},"title":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"vendor":{"type":"string","nullable":true},"productType":{"type":"string","nullable":true},"variantCount":{"type":"number"},"totalAvailable":{"type":"number","nullable":true,"description":"Stock across variants that track it; null when none do"},"priceRange":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PriceRangeDto"}]},"imageUrl":{"type":"string","nullable":true},"stores":{"description":"The stores it is in, in the order it joined them","type":"array","items":{"$ref":"#/components/schemas/ProductStoreBadgeDto"}},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","handle","title","status","vendor","productType","variantCount","totalAvailable","priceRange","imageUrl","stores","updatedAt"]},"ProductPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummaryDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"OutOfStockPolicy":{"type":"string","enum":["STOP_SELLING","CONTINUE_SELLING"]},"VariantDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"number"},"sku":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true,"description":"GTIN, UPC, EAN or ISBN"},"optionValues":{"description":"One value per product option, in order","type":"array","items":{"type":"string"}},"price":{"type":"string","example":"89.00","description":"Decimal string in the workspace currency"},"compareAtPrice":{"type":"string","nullable":true,"example":"99.00"},"cost":{"type":"string","nullable":true,"example":"40.00","description":"What you pay per unit; never shown to buyers"},"weightGrams":{"type":"number","nullable":true},"requiresShipping":{"type":"boolean"},"taxable":{"type":"boolean"},"outOfStockPolicy":{"allOf":[{"$ref":"#/components/schemas/OutOfStockPolicy"}]},"tracked":{"type":"boolean","description":"Whether Crossmart tracks stock for this variant"},"available":{"type":"number"}},"required":["id","position","sku","barcode","optionValues","price","compareAtPrice","cost","weightGrams","requiresShipping","taxable","outOfStockPolicy","tracked","available"]},"MediaDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"altText":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","url","altText","position"]},"ProductDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"handle":{"type":"string"},"title":{"type":"string"},"descriptionHtml":{"type":"string"},"vendor":{"type":"string","nullable":true},"productType":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"status":{"allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"optionNames":{"example":["Size","Color"],"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/VariantDto"}},"media":{"type":"array","items":{"$ref":"#/components/schemas/MediaDto"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","handle","title","descriptionHtml","vendor","productType","tags","status","optionNames","variants","media","createdAt","updatedAt"]},"CreateMediaDto":{"type":"object","properties":{"url":{"type":"string","example":"https://cdn.example.com/mug.jpg"},"altText":{"type":"string"}},"required":["url"]},"CreateVariantDto":{"type":"object","properties":{"sku":{"type":"string","maxLength":255},"barcode":{"type":"string","description":"GTIN, UPC, EAN or ISBN"},"optionValues":{"description":"One value per product option, in order","type":"array","items":{"type":"string"}},"price":{"type":"string","example":"19.90"},"compareAtPrice":{"type":"string","example":"24.90"},"cost":{"type":"string","example":"40.00","description":"What you pay per unit. Used for pricing floors; never shown to buyers."},"weightGrams":{"type":"number","minimum":0},"requiresShipping":{"type":"boolean","default":true},"taxable":{"type":"boolean","default":true},"outOfStockPolicy":{"default":"STOP_SELLING","allOf":[{"$ref":"#/components/schemas/OutOfStockPolicy"}]},"tracked":{"type":"boolean","default":true,"description":"Track stock for this variant"},"quantity":{"type":"number","default":0,"description":"Opening stock"}},"required":["price"]},"CreateProductDto":{"type":"object","properties":{"title":{"type":"string","maxLength":255},"descriptionHtml":{"type":"string","maxLength":65535},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"default":"DRAFT","allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"optionNames":{"example":["Size","Color"],"type":"array","items":{"type":"string"}},"media":{"type":"array","items":{"$ref":"#/components/schemas/CreateMediaDto"}},"handle":{"type":"string","maxLength":255,"description":"Unique in the workspace. Defaults to the slugified title, or to `product-<random id>` when the title has no Latin letters or digits (such as a Hebrew title)."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/CreateVariantDto"}}},"required":["title","variants"]},"UpdateVariantDto":{"type":"object","properties":{"sku":{"type":"string","maxLength":255},"barcode":{"type":"string","description":"GTIN, UPC, EAN or ISBN"},"optionValues":{"description":"One value per product option, in order","type":"array","items":{"type":"string"}},"price":{"type":"string","example":"19.90"},"compareAtPrice":{"type":"string","example":"24.90"},"cost":{"type":"string","example":"40.00","description":"What you pay per unit. Used for pricing floors; never shown to buyers."},"weightGrams":{"type":"number","minimum":0},"requiresShipping":{"type":"boolean","default":true},"taxable":{"type":"boolean","default":true},"outOfStockPolicy":{"default":"STOP_SELLING","allOf":[{"$ref":"#/components/schemas/OutOfStockPolicy"}]},"tracked":{"type":"boolean","default":true,"description":"Track stock for this variant"},"id":{"type":"string","format":"uuid","description":"The variant to edit. Leave empty to add a new variant."},"quantity":{"type":"number","description":"Stock on hand; a change is logged as an adjustment. Leave it out to keep the variant’s current stock (a new variant then opens with none)."}},"required":["price"]},"UpdateProductDto":{"type":"object","properties":{"title":{"type":"string","maxLength":255},"descriptionHtml":{"type":"string","maxLength":65535},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"default":"DRAFT","allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"optionNames":{"example":["Size","Color"],"type":"array","items":{"type":"string"}},"media":{"type":"array","items":{"$ref":"#/components/schemas/CreateMediaDto"}},"handle":{"type":"string","maxLength":255},"variants":{"type":"array","items":{"$ref":"#/components/schemas/UpdateVariantDto"}}},"required":["title","handle","variants"]},"BulkProductAction":{"type":"string","enum":["set_status","add_tags","remove_tags","adjust_prices","delete"]},"BulkProductActionDto":{"type":"object","properties":{"productIds":{"maxItems":250,"type":"array","items":{"type":"string","format":"uuid"}},"action":{"allOf":[{"$ref":"#/components/schemas/BulkProductAction"}]},"status":{"description":"Required for `set_status`","allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"tags":{"description":"Required for `add_tags` and `remove_tags`","type":"array","items":{"type":"string"}},"percent":{"type":"number","minimum":-90,"maximum":500,"description":"Required for `adjust_prices`. 10 raises every price by 10%, -15 lowers it by 15%."}},"required":["productIds","action"]},"BulkProductResultDto":{"type":"object","properties":{"affected":{"type":"number","description":"Products changed. Ids from other workspaces are not counted."}},"required":["affected"]},"ProductViewDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"search":{"type":"string","nullable":true},"status":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"gap":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CatalogGap"}]},"createdAt":{"format":"date-time","type":"string"}},"required":["id","name","createdAt"]},"CreateProductViewDto":{"type":"object","properties":{"name":{"type":"string","maxLength":60,"description":"Unique in the workspace"},"search":{"type":"string","description":"Matches title, handle or SKU"},"status":{"allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"gap":{"allOf":[{"$ref":"#/components/schemas/CatalogGap"}]}},"required":["name"]},"CatalogImportFormat":{"type":"string","enum":["shopify_csv","inventory_csv","shopify_api"]},"CatalogImportMode":{"type":"string","enum":["create","update","inventory","create_or_link"],"description":"`create` adds new products (Shopify CSV), `update` replaces products matched by handle (Shopify CSV) and `inventory` sets stock by SKU (inventory CSV)"},"ImportProductsDto":{"type":"object","properties":{"format":{"allOf":[{"$ref":"#/components/schemas/CatalogImportFormat"}]},"mode":{"default":"create","description":"`create` adds new products (Shopify CSV), `update` replaces products matched by handle (Shopify CSV) and `inventory` sets stock by SKU (inventory CSV)","allOf":[{"$ref":"#/components/schemas/CatalogImportMode"}]}},"required":["format"]},"ImportIssueCode":{"type":"string","enum":["already_exists","duplicate_sku","invalid_value","missing_value","invalid_options","not_found","unknown_sku","not_tracked","duplicate_row","unmatched_variant","already_linked"]},"ImportIssueDto":{"type":"object","properties":{"code":{"allOf":[{"$ref":"#/components/schemas/ImportIssueCode"}]},"message":{"type":"string"},"handle":{"type":"string"},"sku":{"type":"string"},"row":{"type":"number","description":"Spreadsheet row number; the header is row 1"}},"required":["code","message"]},"CatalogImportResultDto":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid","description":"The import history entry of this import"},"mode":{"allOf":[{"$ref":"#/components/schemas/CatalogImportMode"}]},"createdProducts":{"type":"number"},"createdVariants":{"type":"number"},"updatedProducts":{"type":"number","description":"Products replaced by an update import"},"updatedVariants":{"type":"number","description":"Variants whose stock an inventory import set"},"skipped":{"description":"Records left as they were: already in the catalog, not found, stock not tracked","type":"array","items":{"$ref":"#/components/schemas/ImportIssueDto"}},"failed":{"description":"Records that could not be imported","type":"array","items":{"$ref":"#/components/schemas/ImportIssueDto"}}},"required":["jobId","mode","createdProducts","createdVariants","updatedProducts","updatedVariants","skipped","failed"]},"ImportJobStatus":{"type":"string","enum":["PROCESSING","COMPLETED","FAILED"]},"ImportJobCountsDto":{"type":"object","properties":{"created":{"type":"number"},"linked":{"type":"number","description":"Channel products linked to catalog products they matched; zero for file imports"},"updated":{"type":"number","description":"Products replaced by an update import, variants whose stock an inventory import set, or products a channel import found already linked"},"skipped":{"type":"number"},"failed":{"type":"number"}},"required":["created","linked","updated","skipped","failed"]},"ImportJobActorDto":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","nullable":true},"userName":{"type":"string","nullable":true,"description":"The user who sent the file; null for API keys and deleted users"},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"apiKeyName":{"type":"string","nullable":true,"description":"The API key that sent the file, if one did"}},"required":["userId","userName","apiKeyId","apiKeyName"]},"ImportJobDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"mode":{"allOf":[{"$ref":"#/components/schemas/CatalogImportMode"}]},"format":{"allOf":[{"$ref":"#/components/schemas/CatalogImportFormat"}]},"fileName":{"type":"string","description":"The file name, or the channel account a channel import read"},"connectionId":{"type":"string","format":"uuid","nullable":true,"description":"The channel connection a channel import reads; null for file imports"},"totalCount":{"type":"number","nullable":true,"description":"Records the source holds, when it reports them, to show progress"},"status":{"allOf":[{"$ref":"#/components/schemas/ImportJobStatus"}]},"counts":{"description":"Products for create and update imports; stock rows for inventory imports","allOf":[{"$ref":"#/components/schemas/ImportJobCountsDto"}]},"errorMessage":{"type":"string","nullable":true,"description":"Why the whole file was rejected"},"actor":{"$ref":"#/components/schemas/ImportJobActorDto"},"createdAt":{"format":"date-time","type":"string"},"finishedAt":{"format":"date-time","type":"string","nullable":true}},"required":["id","mode","format","fileName","connectionId","totalCount","status","counts","errorMessage","actor","createdAt","finishedAt"]},"ImportJobPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ImportJobDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"ImportIssueOutcome":{"type":"string","enum":["SKIPPED","FAILED"]},"ImportJobIssueDto":{"type":"object","properties":{"code":{"allOf":[{"$ref":"#/components/schemas/ImportIssueCode"}]},"message":{"type":"string"},"handle":{"type":"string"},"sku":{"type":"string"},"row":{"type":"number","description":"Spreadsheet row number; the header is row 1"},"outcome":{"allOf":[{"$ref":"#/components/schemas/ImportIssueOutcome"}]}},"required":["code","message","outcome"]},"ImportJobDetailDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"mode":{"allOf":[{"$ref":"#/components/schemas/CatalogImportMode"}]},"format":{"allOf":[{"$ref":"#/components/schemas/CatalogImportFormat"}]},"fileName":{"type":"string","description":"The file name, or the channel account a channel import read"},"connectionId":{"type":"string","format":"uuid","nullable":true,"description":"The channel connection a channel import reads; null for file imports"},"totalCount":{"type":"number","nullable":true,"description":"Records the source holds, when it reports them, to show progress"},"status":{"allOf":[{"$ref":"#/components/schemas/ImportJobStatus"}]},"counts":{"description":"Products for create and update imports; stock rows for inventory imports","allOf":[{"$ref":"#/components/schemas/ImportJobCountsDto"}]},"errorMessage":{"type":"string","nullable":true,"description":"Why the whole file was rejected"},"actor":{"$ref":"#/components/schemas/ImportJobActorDto"},"createdAt":{"format":"date-time","type":"string"},"finishedAt":{"format":"date-time","type":"string","nullable":true},"issues":{"description":"Skipped and failed records, in file order","type":"array","items":{"$ref":"#/components/schemas/ImportJobIssueDto"}}},"required":["id","mode","format","fileName","connectionId","totalCount","status","counts","errorMessage","actor","createdAt","finishedAt","issues"]},"ImageContentType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif"]},"UploadedImageDto":{"type":"object","properties":{"url":{"type":"string","description":"Use it as a product media `url`"},"contentType":{"allOf":[{"$ref":"#/components/schemas/ImageContentType"}]},"byteSize":{"type":"number"}},"required":["url","contentType","byteSize"]},"CatalogGapCountDto":{"type":"object","properties":{"gap":{"allOf":[{"$ref":"#/components/schemas/CatalogGap"}]},"products":{"type":"number","description":"Products with this gap"}},"required":["gap","products"]},"CatalogStatsDto":{"type":"object","properties":{"products":{"type":"number"},"activeProducts":{"type":"number"},"draftProducts":{"type":"number"},"archivedProducts":{"type":"number"},"variants":{"type":"number"},"outOfStockVariants":{"type":"number","description":"Tracked variants with nothing available"},"gaps":{"description":"Products lacking what channels require","type":"array","items":{"$ref":"#/components/schemas/CatalogGapCountDto"}}},"required":["products","activeProducts","draftProducts","archivedProducts","variants","outOfStockVariants","gaps"]},"ActivityAction":{"type":"string","enum":["product_created","product_updated","product_deleted","products_bulk_updated","products_bulk_deleted","products_imported","products_updated_by_import","stock_imported","channel_catalog_imported","product_view_created","product_view_deleted","api_key_created","api_key_revoked","agent_disconnected","member_invited","invitation_revoked","member_joined","member_role_changed","member_removed","member_left","workspace_created","workspace_renamed","workspace_time_zone_changed","custom_role_created","custom_role_updated","custom_role_deleted","inventory_adjusted","channel_connected","channel_disconnected","channel_connect_failed","listing_published","listing_updated","listing_sync_failed","listing_delisted","listing_added","listing_removed","listing_override_updated","channel_pricing_updated","channel_selection_updated","channel_listing_defaults_updated","channel_policies_opted_in","channel_default_policies_created","listing_category_changed","listing_item_specifics_changed","channel_sync_requested","listing_retry_requested","stock_oversold","content_generation_requested","content_generated","suggestion_approved","suggestion_rejected","suggestions_bulk_approved"]},"ActivityOutcome":{"type":"string","enum":["SUCCEEDED","FAILED"]},"ActivitySubjectType":{"type":"string","enum":["product","product_view","import_job","api_key","agent_connection","member","invitation","workspace","custom_role","channel_connection"]},"ActivityActorType":{"type":"string","enum":["USER","API_KEY","AGENT","SYSTEM"]},"ActivityActorDto":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/ActivityActorType"}]},"userId":{"type":"string","format":"uuid","nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"agentClientId":{"type":"string","nullable":true,"description":"The OAuth client id of the connected agent, for agent actions"},"name":{"type":"string","nullable":true,"description":"User or API key name; for an agent, the user it acted for. Null for system actions and deleted users or keys"},"email":{"type":"string","nullable":true,"description":"Set for users, and for the user an agent acted for"},"agentName":{"type":"string","nullable":true,"description":"The agent's name, such as \"Claude\", for agent actions"}},"required":["type","userId","apiKeyId","agentClientId","name","email","agentName"]},"ActivitySubjectDto":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/ActivitySubjectType"}]},"id":{"type":"string","format":"uuid","nullable":true},"label":{"type":"string","nullable":true,"description":"The name when the event happened"}},"required":["type","id","label"]},"ActivityEventDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"allOf":[{"$ref":"#/components/schemas/ActivityAction"}]},"outcome":{"allOf":[{"$ref":"#/components/schemas/ActivityOutcome"}]},"summary":{"type":"string","example":"Updated product “Linen Shirt”"},"actor":{"$ref":"#/components/schemas/ActivityActorDto"},"subject":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ActivitySubjectDto"}]},"itemCount":{"type":"number","nullable":true,"description":"Items the action covered, such as products changed in bulk"},"failureReason":{"type":"string","nullable":true,"description":"Why a failed action failed"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","action","outcome","summary","actor","subject","itemCount","failureReason","createdAt"]},"ActivityPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ActivityEventDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"StockLevel":{"type":"string","enum":["in_stock","low_stock","out_of_stock","untracked"]},"InventorySort":{"type":"string","enum":["title","available","updated_at"]},"InventoryItemDto":{"type":"object","properties":{"inventoryItemId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"productTitle":{"type":"string"},"optionValues":{"description":"One value per product option, in order","type":"array","items":{"type":"string"}},"sku":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true,"description":"The product’s first image"},"tracked":{"type":"boolean","description":"Whether Crossmart tracks stock for this variant"},"onHand":{"type":"number","description":"Units in stock: available plus reserved"},"reserved":{"type":"number","description":"Units held for open orders"},"available":{"type":"number","description":"Units that can still be sold, and what channels receive"},"stockLevel":{"allOf":[{"$ref":"#/components/schemas/StockLevel"}]},"updatedAt":{"format":"date-time","type":"string"}},"required":["inventoryItemId","variantId","productId","productTitle","optionValues","sku","imageUrl","tracked","onHand","reserved","available","stockLevel","updatedAt"]},"InventoryPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItemDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"StockAdjustmentMode":{"type":"string","enum":["delta","set"]},"InventoryMovementReason":{"type":"string","enum":["OPENING_BALANCE","ADJUSTMENT","CORRECTION","RECEIVED","RETURNED","DAMAGED","LOST","SOLD","IMPORTED","ORDER_SHIPPED"],"description":"One of RECEIVED, CORRECTION, RETURNED, DAMAGED, LOST, SOLD. The other reasons are recorded by Crossmart."},"AdjustStockDto":{"type":"object","properties":{"mode":{"allOf":[{"$ref":"#/components/schemas/StockAdjustmentMode"}]},"quantity":{"type":"number","minimum":-1000000,"maximum":1000000,"description":"With `delta`, units to add (or remove, when negative). With `set`, the new stock on hand."},"reason":{"description":"One of RECEIVED, CORRECTION, RETURNED, DAMAGED, LOST, SOLD. The other reasons are recorded by Crossmart.","allOf":[{"$ref":"#/components/schemas/InventoryMovementReason"}]},"note":{"type":"string","maxLength":500}},"required":["mode","quantity","reason"]},"InventoryMovementDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"delta":{"type":"number","description":"Units added (positive) or removed (negative)"},"reason":{"allOf":[{"$ref":"#/components/schemas/InventoryMovementReason"}]},"quantityAfter":{"type":"number","description":"Stock on hand right after this movement"},"note":{"type":"string","nullable":true},"userName":{"type":"string","nullable":true,"description":"The user who made the change; null for API keys and changes made by Crossmart"},"apiKeyName":{"type":"string","nullable":true,"description":"The API key that made the change, if any"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","delta","reason","quantityAfter","note","userName","apiKeyName","createdAt"]},"InventoryMovementPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryMovementDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"ConnectFailure":{"type":"string","enum":["invalid_state","expired_state","invalid_signature","invalid_account","access_denied","missing_scopes","not_permitted","session_required","channel_unavailable","plan_limit_reached","unexpected"],"description":"Set when connecting failed"},"ChannelConnectRedirectDto":{"type":"object","properties":{"connected":{"description":"Set when the account was connected","allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"error":{"description":"Set when connecting failed","allOf":[{"$ref":"#/components/schemas/ConnectFailure"}]},"channel":{"description":"The channel an error is about","allOf":[{"$ref":"#/components/schemas/ChannelType"}]}}},"ChannelConnectionStatus":{"type":"string","enum":["CONNECTED","NEEDS_REAUTH","DISCONNECTED","ERROR"]},"ChannelFeature":{"type":"string","enum":["storefront_visibility","order_sync"],"description":"What the connection cannot do until the merchant approves the app again"},"ShopifyLocationDto":{"type":"object","properties":{"id":{"type":"string","example":"gid://shopify/Location/1001"},"name":{"type":"string"}},"required":["id","name"]},"ShopifySettingsDto":{"type":"object","properties":{"shopName":{"type":"string"},"currencyCode":{"type":"string","example":"USD","description":"ISO 4217 code of the store’s currency"},"ianaTimezone":{"type":"string","nullable":true,"example":"America/New_York"},"primaryDomainUrl":{"type":"string","nullable":true,"description":"The storefront’s public URL"},"primaryLocation":{"nullable":true,"description":"Where Crossmart reads and writes stock","type":"object","allOf":[{"$ref":"#/components/schemas/ShopifyLocationDto"}]}},"required":["shopName","currencyCode","ianaTimezone","primaryDomainUrl","primaryLocation"]},"EbayMarketplaceId":{"type":"string","enum":["EBAY_US","EBAY_GB","EBAY_DE","EBAY_AU","EBAY_CA","EBAY_FR","EBAY_IT","EBAY_ES"]},"EbayPolicyDto":{"type":"object","properties":{"id":{"type":"string","example":"6000000001"},"name":{"type":"string","example":"Free shipping"}},"required":["id","name"]},"EbayBusinessPoliciesDto":{"type":"object","properties":{"fulfillment":{"type":"array","items":{"$ref":"#/components/schemas/EbayPolicyDto"}},"payment":{"type":"array","items":{"$ref":"#/components/schemas/EbayPolicyDto"}},"return":{"type":"array","items":{"$ref":"#/components/schemas/EbayPolicyDto"}}},"required":["fulfillment","payment","return"]},"EbayCondition":{"type":"string","enum":["NEW","LIKE_NEW","NEW_OTHER","NEW_WITH_DEFECTS","CERTIFIED_REFURBISHED","EXCELLENT_REFURBISHED","VERY_GOOD_REFURBISHED","GOOD_REFURBISHED","SELLER_REFURBISHED","USED_EXCELLENT","USED_VERY_GOOD","USED_GOOD","USED_ACCEPTABLE","FOR_PARTS_OR_NOT_WORKING"]},"EbayShipFromDto":{"type":"object","properties":{"postalCode":{"type":"string","example":"95125"},"country":{"type":"string","example":"US","description":"ISO 3166 alpha-2 country code"},"city":{"type":"string","nullable":true,"example":"San Jose"}},"required":["postalCode","country","city"]},"EbayListingDefaultsDto":{"type":"object","properties":{"fulfillmentPolicyId":{"type":"string","nullable":true},"paymentPolicyId":{"type":"string","nullable":true},"returnPolicyId":{"type":"string","nullable":true},"condition":{"allOf":[{"$ref":"#/components/schemas/EbayCondition"}]},"location":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/EbayShipFromDto"}]},"merchantLocationKey":{"type":"string","nullable":true,"description":"The inventory location Crossmart created on eBay for `location`"}},"required":["fulfillmentPolicyId","paymentPolicyId","returnPolicyId","condition","location","merchantLocationKey"]},"EbaySettingsDto":{"type":"object","properties":{"marketplaceId":{"allOf":[{"$ref":"#/components/schemas/EbayMarketplaceId"}]},"currencyCode":{"type":"string","example":"USD","description":"ISO 4217 code of the marketplace’s currency"},"username":{"type":"string","example":"demo_seller"},"userId":{"type":"string","description":"eBay’s immutable id of the user"},"businessPoliciesEnabled":{"type":"boolean","description":"False when the account has not opted in to business policies on eBay"},"policies":{"$ref":"#/components/schemas/EbayBusinessPoliciesDto"},"listingDefaults":{"description":"What listings are published with; policies resolve to the only one of a type","allOf":[{"$ref":"#/components/schemas/EbayListingDefaultsDto"}]},"readyToList":{"type":"boolean","description":"Whether listings can be published: policies of each type and a ship-from set"}},"required":["marketplaceId","currencyCode","username","userId","businessPoliciesEnabled","policies","listingDefaults","readyToList"]},"GoogleTargetCountry":{"type":"string","enum":["US","GB","CA","AU","DE","FR","IT","ES","NL","IL"]},"GoogleListingSetupDto":{"type":"object","properties":{"country":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetCountry"}]},"productUrlTemplate":{"type":"string","example":"https://acme.example/products/{handle}"},"dataSourceId":{"type":"string","description":"The Merchant Center API data source Crossmart publishes into"}},"required":["country","productUrlTemplate","dataSourceId"]},"GoogleMerchantSettingsDto":{"type":"object","properties":{"accountId":{"type":"string","example":"123456789"},"accountName":{"type":"string","example":"Acme Goods"},"homepageUri":{"type":"string","nullable":true,"description":"The website the account claimed; product links must be on it"},"homepageClaimed":{"type":"boolean","description":"Whether the account verified and claimed its website"},"country":{"allOf":[{"$ref":"#/components/schemas/GoogleTargetCountry"}]},"currencyCode":{"type":"string","example":"USD","description":"ISO 4217 code of the country’s currency"},"contentLanguage":{"type":"string","example":"en","description":"The language listings are written in"},"listingSetup":{"nullable":true,"description":"Null until the merchant saves it; publishing needs it","type":"object","allOf":[{"$ref":"#/components/schemas/GoogleListingSetupDto"}]},"readyToList":{"type":"boolean","description":"Whether the listing setup is saved, so products can be listed"}},"required":["accountId","accountName","homepageUri","homepageClaimed","country","currencyCode","contentLanguage","listingSetup","readyToList"]},"EtsyProfileDto":{"type":"object","properties":{"id":{"type":"string","example":"6722757781"},"name":{"type":"string","example":"Free US shipping"}},"required":["id","name"]},"EtsyShopProfilesDto":{"type":"object","properties":{"shipping":{"type":"array","items":{"$ref":"#/components/schemas/EtsyProfileDto"}},"processing":{"description":"Processing profiles: whether items are ready to ship or made to order, and how long they take","type":"array","items":{"$ref":"#/components/schemas/EtsyProfileDto"}}},"required":["shipping","processing"]},"EtsyWhoMade":{"type":"string","enum":["i_did","someone_else","collective"]},"EtsyWhenMade":{"type":"string","enum":["made_to_order","2020_2026","2010_2019","2007_2009","before_2007","2000_2006","1990s","1980s","1970s","1960s","1950s","1940s","1930s","1920s","1910s","1900s","1800s","1700s","before_1700"]},"EtsyListingSetupDto":{"type":"object","properties":{"whoMade":{"allOf":[{"$ref":"#/components/schemas/EtsyWhoMade"}]},"whenMade":{"allOf":[{"$ref":"#/components/schemas/EtsyWhenMade"}]},"isSupply":{"type":"boolean","description":"Whether the items are craft supplies rather than finished products"},"shippingProfileId":{"type":"string","nullable":true,"description":"The shipping profile listings use; null when the shop has none or several and none is chosen"},"processingProfileId":{"type":"string","nullable":true,"description":"The processing profile listings use"}},"required":["whoMade","whenMade","isSupply","shippingProfileId","processingProfileId"]},"EtsySettingsDto":{"type":"object","properties":{"shopId":{"type":"string","example":"87654321"},"shopName":{"type":"string","example":"ClayAndKiln"},"currencyCode":{"type":"string","example":"USD","description":"ISO 4217 code of the shop’s currency"},"shopUrl":{"type":"string","nullable":true,"example":"https://www.etsy.com/shop/ClayAndKiln"},"profiles":{"$ref":"#/components/schemas/EtsyShopProfilesDto"},"listingSetup":{"nullable":true,"description":"Null until the merchant saves it; publishing needs it","type":"object","allOf":[{"$ref":"#/components/schemas/EtsyListingSetupDto"}]},"readyToList":{"type":"boolean","description":"Whether the listing setup is complete, so products can be listed"}},"required":["shopId","shopName","currencyCode","shopUrl","profiles","listingSetup","readyToList"]},"ProductSelectionFilterDto":{"type":"object","properties":{"search":{"type":"string","description":"Matches title, handle or SKU"},"status":{"allOf":[{"$ref":"#/components/schemas/ProductStatus"}]},"gap":{"allOf":[{"$ref":"#/components/schemas/CatalogGap"}]},"tags":{"description":"Products with any of these tags","type":"array","items":{"type":"string"}},"vendor":{"type":"string","description":"Products of this vendor, ignoring case"}}},"ProductSelectionRuleDto":{"type":"object","properties":{"filter":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ProductSelectionFilterDto"}]},"includeProductIds":{"type":"array","items":{"type":"string","format":"uuid"}},"excludeProductIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["filter","includeProductIds","excludeProductIds"]},"PriceRounding":{"type":"string","enum":["none","ending_99","ending_95","whole"]},"PricingFloorDto":{"type":"object","properties":{"minMarginPercent":{"type":"string","example":"30","description":"Never price below cost plus this percentage (0 to 1000)"}},"required":["minMarginPercent"]},"CompareAtMode":{"type":"string","enum":["adjust","keep","omit"]},"PricingRuleDto":{"type":"object","properties":{"adjustmentPercent":{"type":"string","example":"15","description":"Markup (positive) or discount (negative), -90 to 500"},"fixedAmount":{"type":"string","example":"0","description":"Added after the percentage; may be negative"},"rounding":{"allOf":[{"$ref":"#/components/schemas/PriceRounding"}]},"floor":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PricingFloorDto"}]},"compareAt":{"allOf":[{"$ref":"#/components/schemas/CompareAtMode"}]},"fixedExchangeRate":{"type":"string","nullable":true,"example":"0.92","description":"Store-currency units per catalog-currency unit, used instead of the ECB daily rate. Only applies when the store sells in another currency than the workspace."}},"required":["adjustmentPercent","fixedAmount","rounding","floor","compareAt"]},"PublishReadinessDto":{"type":"object","properties":{"ready":{"type":"boolean","description":"True when listings can be published to this store"},"missing":{"type":"array","example":["shipping_policy","ship_from_location"],"description":"What to finish before publishing, in order; empty when ready. `reconnect` alone when the store needs to be connected again. eBay: `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`. Google: `listing_setup`. Etsy: `item_details`, `shipping_profile`, `processing_profile`. `account_settings` when the account was never read.","items":{"$ref":"#/components/schemas/PublishRequirement"}}},"required":["ready","missing"]},"ChannelConnectionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"externalAccountId":{"type":"string","example":"demo-store.myshopify.com","description":"The account on the channel"},"displayName":{"type":"string","example":"Demo Store"},"status":{"allOf":[{"$ref":"#/components/schemas/ChannelConnectionStatus"}]},"statusReason":{"type":"string","nullable":true,"description":"Why it needs re-auth or failed"},"grantedScopes":{"type":"array","items":{"type":"string"}},"missingFeatures":{"type":"array","description":"What the connection cannot do until the merchant approves the app again","items":{"$ref":"#/components/schemas/ChannelFeature"}},"shopify":{"nullable":true,"description":"The store’s details, for Shopify connections","type":"object","allOf":[{"$ref":"#/components/schemas/ShopifySettingsDto"}]},"ebay":{"nullable":true,"description":"The account’s details on its marketplace, for eBay connections","type":"object","allOf":[{"$ref":"#/components/schemas/EbaySettingsDto"}]},"googleMerchant":{"nullable":true,"description":"The Merchant Center account and its listing setup, for Google connections","type":"object","allOf":[{"$ref":"#/components/schemas/GoogleMerchantSettingsDto"}]},"etsy":{"nullable":true,"description":"The Etsy shop, its profiles and its listing setup, for Etsy connections","type":"object","allOf":[{"$ref":"#/components/schemas/EtsySettingsDto"}]},"productSelection":{"nullable":true,"description":"Which products the connection lists; null lists every product","type":"object","allOf":[{"$ref":"#/components/schemas/ProductSelectionRuleDto"}]},"pricing":{"nullable":true,"description":"How the connection prices variants; null sends catalog prices","type":"object","allOf":[{"$ref":"#/components/schemas/PricingRuleDto"}]},"connectedAt":{"format":"date-time","type":"string"},"disconnectedAt":{"format":"date-time","type":"string","nullable":true},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"failedListings":{"type":"number","description":"Listings in this store whose last sync failed"},"publishReadiness":{"description":"Whether listings can be published here, and what the store setup lacks","allOf":[{"$ref":"#/components/schemas/PublishReadinessDto"}]}},"required":["id","channel","externalAccountId","displayName","status","statusReason","grantedScopes","missingFeatures","shopify","ebay","googleMerchant","etsy","productSelection","pricing","connectedAt","disconnectedAt","lastSyncedAt","createdAt","updatedAt","failedListings","publishReadiness"]},"StartAuthorizationDto":{"type":"object","properties":{"channel":{"allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"accountHandle":{"type":"string","maxLength":255,"example":"demo-store.myshopify.com","description":"The account to connect. For Shopify, the store’s myshopify.com domain or handle. For eBay, the marketplace id, such as `EBAY_US`. For Etsy, the shop name (the merchant must sign in to that shop)."}},"required":["channel","accountHandle"]},"StartedAuthorizationDto":{"type":"object","properties":{"authorizationUrl":{"type":"string","description":"Send the merchant here to approve the app on the channel"},"accountHandle":{"type":"string","example":"demo-store.myshopify.com","description":"The account handle, normalized: a myshopify.com domain, an eBay marketplace id, or a lower-cased Etsy shop name"},"externalAccountId":{"type":"string","example":"demo-store.myshopify.com","deprecated":true,"description":"The same value as `accountHandle`. Use `accountHandle` instead."}},"required":["authorizationUrl","accountHandle","externalAccountId"]},"UpdateEbayListingDefaultsDto":{"type":"object","properties":{"fulfillmentPolicyId":{"type":"string","nullable":true,"description":"Shipping policy; null uses the account’s only one, when it has exactly one"},"paymentPolicyId":{"type":"string","nullable":true},"returnPolicyId":{"type":"string","nullable":true},"condition":{"allOf":[{"$ref":"#/components/schemas/EbayCondition"}]},"location":{"nullable":true,"description":"Saved on eBay as the account’s Crossmart inventory location","type":"object","allOf":[{"$ref":"#/components/schemas/EbayShipFromDto"}]}},"required":["fulfillmentPolicyId","paymentPolicyId","returnPolicyId","condition","location"]},"UpdateGoogleListingSetupDto":{"type":"object","properties":{"country":{"description":"Where listings sell; their currency and language follow","allOf":[{"$ref":"#/components/schemas/GoogleTargetCountry"}]},"productUrlTemplate":{"type":"string","example":"https://acme.example/products/{handle}","maxLength":2000,"description":"Each product’s page on the merchant’s website, with {handle} for its handle"}},"required":["country","productUrlTemplate"]},"UpdateEtsyListingSetupDto":{"type":"object","properties":{"whoMade":{"description":"Who made the items","allOf":[{"$ref":"#/components/schemas/EtsyWhoMade"}]},"whenMade":{"description":"When the items were made: `made_to_order`, or an era for vintage items","allOf":[{"$ref":"#/components/schemas/EtsyWhenMade"}]},"isSupply":{"type":"boolean","description":"Whether the items are craft supplies rather than finished products"},"shippingProfileId":{"type":"string","nullable":true,"example":"6722757781","description":"One of the shop’s shipping profiles; null follows the shop’s only one"},"processingProfileId":{"type":"string","nullable":true,"example":"18201076875","description":"One of the shop’s processing profiles; null follows the shop’s only one"}},"required":["whoMade","whenMade","isSupply","shippingProfileId","processingProfileId"]},"ChannelProductState":{"type":"string","enum":["listed","pending","failed","removing","removed_by_hand","excluded"]},"ChannelProductSort":{"type":"string","enum":["title","updatedAt"]},"ChannelCategoryDto":{"type":"object","properties":{"id":{"type":"string","example":"20625"},"name":{"type":"string","example":"Home & Garden > Kitchen, Dining & Bar > Dinnerware & Serving Dishes > Mugs","description":"The category with its ancestors, as the channel shows it"}},"required":["id","name"]},"ListingSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"allOf":[{"$ref":"#/components/schemas/ListingStatus"}]},"source":{"description":"How the product joined the store: by hand, by an import, or by the automatic rule","allOf":[{"$ref":"#/components/schemas/ListingSource"}]},"externalId":{"type":"string","nullable":true,"description":"The product’s id on the channel"},"externalUrl":{"type":"string","nullable":true,"description":"Where to see it on the channel"},"lastError":{"type":"string","nullable":true,"description":"Why the last sync failed"},"missingRequirement":{"nullable":true,"description":"What the channel refused the last publish for lacking (such as `item_specifics`), when the merchant can add it; null otherwise","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true},"syncRequestedAt":{"format":"date-time","type":"string","nullable":true,"description":"When a sync or retry queued its publish, update or delist; null once that job finished or gave up. While set, a selected listing shows `displayState: publishing`."},"category":{"nullable":true,"description":"The channel category it is listed in, on channels with categories (eBay)","type":"object","allOf":[{"$ref":"#/components/schemas/ChannelCategoryDto"}]}},"required":["id","status","source","externalId","externalUrl","lastError","missingRequirement","lastSyncedAt","syncRequestedAt","category"]},"ChannelProductDto":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/ProductSummaryDto"},"state":{"allOf":[{"$ref":"#/components/schemas/ChannelProductState"}]},"displayState":{"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`.","allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"displayReason":{"type":"string","nullable":true,"example":"Choose a shipping policy in this eBay connection’s listing defaults.","description":"For `needs_details` and `failed`: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states."},"displayRequirement":{"nullable":true,"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states.","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"listing":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ListingSummaryDto"}]}},"required":["product","state","displayState","displayReason","displayRequirement","listing"]},"ChannelProductCountsDto":{"type":"object","properties":{"listed":{"type":"number","description":"Selected and on the channel"},"pending":{"type":"number","description":"Selected, waiting for the next sync to publish them"},"failed":{"type":"number","description":"Their last sync failed"},"removing":{"type":"number","description":"On the channel but no longer selected; the next sync delists them"},"removed_by_hand":{"type":"number","description":"Removed by hand and off the channel; adding them back undoes it"},"excluded":{"type":"number","description":"Neither selected nor on the channel"}},"required":["listed","pending","failed","removing","removed_by_hand","excluded"]},"ChannelProductPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductDto"}},"counts":{"$ref":"#/components/schemas/ChannelProductCountsDto"},"nextCursor":{"type":"string","nullable":true},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","counts","nextCursor","total"]},"UpdatePricingDto":{"type":"object","properties":{"rule":{"nullable":true,"description":"The rule; null removes it, so catalog prices are sent as they are","type":"object","allOf":[{"$ref":"#/components/schemas/PricingRuleDto"}]}},"required":["rule"]},"PricingPreviewRequestDto":{"type":"object","properties":{"rule":{"nullable":true,"description":"The rule to try, saved or not; null shows catalog prices","type":"object","allOf":[{"$ref":"#/components/schemas/PricingRuleDto"}]},"productId":{"type":"string","format":"uuid","description":"The product to price; defaults to the first selected product"}},"required":["rule"]},"PricingPreviewProductDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"}},"required":["id","title"]},"PriceSource":{"type":"string","enum":["override","rule","base"]},"PriceStepKind":{"type":"string","enum":["base","conversion","percent","fixed_amount","rounding","floor","override"]},"PriceStepDto":{"type":"object","properties":{"kind":{"allOf":[{"$ref":"#/components/schemas/PriceStepKind"}]},"label":{"type":"string","example":"+15%"},"amount":{"type":"string","example":"102.35","description":"The price after this step"}},"required":["kind","label","amount"]},"PriceWarning":{"type":"string","enum":["missing_cost","below_floor","compare_at_dropped","clamped_to_zero","no_exchange_rate"]},"ResolvedPriceDto":{"type":"object","properties":{"price":{"type":"string","example":"102.99"},"compareAtPrice":{"type":"string","nullable":true},"source":{"allOf":[{"$ref":"#/components/schemas/PriceSource"}]},"steps":{"type":"array","items":{"$ref":"#/components/schemas/PriceStepDto"}},"explanation":{"type":"string","example":"$89.00 → +15% → .99 = $102.99"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PriceWarning"}},"unitCost":{"type":"string","nullable":true,"description":"The variant cost in the channel currency, converted like the price"}},"required":["price","compareAtPrice","source","steps","explanation","warnings","unitCost"]},"PricingPreviewVariantDto":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Blue / Large"},"basePrice":{"type":"string","example":"89.00"},"cost":{"type":"string","nullable":true},"resolved":{"$ref":"#/components/schemas/ResolvedPriceDto"}},"required":["variantId","title","basePrice","cost","resolved"]},"PricingPreviewDto":{"type":"object","properties":{"currencyCode":{"type":"string","example":"USD"},"product":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/PricingPreviewProductDto"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/PricingPreviewVariantDto"}}},"required":["currencyCode","product","variants"]},"UpdateProductSelectionDto":{"type":"object","properties":{"rule":{"nullable":true,"description":"The selection; null lists every product","type":"object","allOf":[{"$ref":"#/components/schemas/ProductSelectionRuleDto"}]}},"required":["rule"]},"SelectionPreviewDto":{"type":"object","properties":{"total":{"type":"number","description":"Products the selection lists"},"matchingFilter":{"type":"number","description":"Products the filter matches, before the manual lists"},"addedManually":{"type":"number","description":"Products added by hand that the filter does not match"},"removedManually":{"type":"number","description":"Products the filter matches that were removed by hand"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummaryDto"}},"nextCursor":{"type":"string","nullable":true},"toPublish":{"type":"number","description":"Products saving this rule publishes now"},"toRemove":{"type":"number","description":"Products saving this rule delists now"}},"required":["total","matchingFilter","addedManually","removedManually","items","nextCursor","toPublish","toRemove"]},"SyncRequestResultDto":{"type":"object","properties":{"queued":{"type":"number","description":"Selected products queued to be published or updated. With `delisting`, the total a progress bar counts down from `GET …/sync`’s `pending`."},"delisting":{"type":"number","description":"Listings queued to be delisted, as they are no longer selected"}},"required":["queued","delisting"]},"SyncProgressDto":{"type":"object","properties":{"pending":{"type":"number","description":"Listings whose publish, update or delist a sync or retry queued and whose job has not finished yet (each shows `syncRequestedAt`, and `displayState: publishing` while selected)"},"failed":{"type":"number","description":"The store’s listings in error now, whatever queued them"},"done":{"type":"boolean","description":"True once nothing a sync or retry queued is still pending"}},"required":["pending","failed","done"]},"ChannelListingDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"allOf":[{"$ref":"#/components/schemas/ListingStatus"}]},"source":{"description":"How the product joined the store: by hand, by an import, or by the automatic rule","allOf":[{"$ref":"#/components/schemas/ListingSource"}]},"externalId":{"type":"string","nullable":true,"description":"The product’s id on the channel"},"externalUrl":{"type":"string","nullable":true,"description":"Where to see it on the channel"},"lastError":{"type":"string","nullable":true,"description":"Why the last sync failed"},"missingRequirement":{"nullable":true,"description":"What the channel refused the last publish for lacking (such as `item_specifics`), when the merchant can add it; null otherwise","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true},"syncRequestedAt":{"format":"date-time","type":"string","nullable":true,"description":"When a sync or retry queued its publish, update or delist; null once that job finished or gave up. While set, a selected listing shows `displayState: publishing`."},"category":{"nullable":true,"description":"The channel category it is listed in, on channels with categories (eBay)","type":"object","allOf":[{"$ref":"#/components/schemas/ChannelCategoryDto"}]},"productId":{"type":"string","format":"uuid"},"productTitle":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"variantCount":{"type":"number"},"displayState":{"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`.","allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"displayReason":{"type":"string","nullable":true,"example":"Choose a shipping policy in this eBay connection’s listing defaults.","description":"For `needs_details` and `failed`: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states."},"displayRequirement":{"nullable":true,"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states.","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]}},"required":["id","status","source","externalId","externalUrl","lastError","missingRequirement","lastSyncedAt","syncRequestedAt","category","productId","productTitle","imageUrl","variantCount","displayState","displayReason","displayRequirement"]},"ChannelListingPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChannelListingDto"}},"nextCursor":{"type":"string","nullable":true},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"StoreProductsDto":{"type":"object","properties":{"productIds":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["productIds"]},"StoreProductsResultDto":{"type":"object","properties":{"count":{"type":"number","description":"Products added or removed"}},"required":["count"]},"ConnectionSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"displayName":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/ChannelConnectionStatus"}]},"currencyCode":{"type":"string","example":"USD"}},"required":["id","channel","displayName","status","currencyCode"]},"ListingVisibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"VariantPriceOverrideDto":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"price":{"type":"string","nullable":true,"example":"79.00"},"compareAtPrice":{"type":"string","nullable":true,"example":"99.00"}},"required":["variantId","price","compareAtPrice"]},"ListingOverrideViewDto":{"type":"object","properties":{"title":{"type":"string","nullable":true},"descriptionHtml":{"type":"string","nullable":true},"vendor":{"type":"string","nullable":true},"tags":{"nullable":true,"type":"array","items":{"type":"string"}},"mediaUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"visibility":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ListingVisibility"}]},"inventoryBuffer":{"type":"number","nullable":true},"maxQuantity":{"type":"number","nullable":true},"variantPrices":{"type":"array","items":{"$ref":"#/components/schemas/VariantPriceOverrideDto"}},"updatedAt":{"format":"date-time","type":"string"}},"required":["title","descriptionHtml","vendor","tags","mediaUrls","visibility","inventoryBuffer","maxQuantity","variantPrices","updatedAt"]},"ChannelVariantDto":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Blue / Large"},"price":{"$ref":"#/components/schemas/ResolvedPriceDto"},"rulePrice":{"type":"string","example":"102.99","description":"In the store’s currency: what its pricing rule gives, before a fixed price on the listing. Equal to the effective price unless the price is overridden."},"quantity":{"type":"number","nullable":true,"description":"The stock the channel shows; null when the variant does not track stock"}},"required":["variantId","title","price","rulePrice","quantity"]},"ProductChannelDto":{"type":"object","properties":{"connection":{"$ref":"#/components/schemas/ConnectionSummaryDto"},"selected":{"type":"boolean","description":"Whether the connection’s product selection includes it"},"displayState":{"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`.","allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"displayReason":{"type":"string","nullable":true,"example":"Choose a shipping policy in this eBay connection’s listing defaults.","description":"For `needs_details` and `failed`: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states."},"displayRequirement":{"nullable":true,"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states.","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"listing":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ListingSummaryDto"}]},"override":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ListingOverrideViewDto"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ChannelVariantDto"}}},"required":["connection","selected","displayState","displayReason","displayRequirement","listing","override","variants"]},"ListingRetryErrorCode":{"type":"string","enum":["store_not_connected","product_not_in_store"],"description":"`store_not_connected`: the store needs re-auth, was disconnected or is in error; reconnect it. `product_not_in_store`: the store does not select the product; add it."},"ListingRetryErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":409},"error":{"type":"string","example":"Conflict"},"code":{"description":"`store_not_connected`: the store needs re-auth, was disconnected or is in error; reconnect it. `product_not_in_store`: the store does not select the product; add it.","allOf":[{"$ref":"#/components/schemas/ListingRetryErrorCode"}]},"message":{"type":"string","example":"Connect this store again before publishing to it"}},"required":["statusCode","error","code","message"]},"ListingOverrideDto":{"type":"object","properties":{"title":{"type":"string","nullable":true,"maxLength":255},"descriptionHtml":{"type":"string","nullable":true},"vendor":{"type":"string","nullable":true,"maxLength":255,"description":"The brand this channel shows instead of the product’s vendor"},"tags":{"nullable":true,"description":"Replaces the product’s tags","type":"array","items":{"type":"string"}},"mediaUrls":{"nullable":true,"description":"The product’s image URLs to show, in order","type":"array","items":{"type":"string"}},"visibility":{"nullable":true,"description":"Show or hide on this channel, whatever the product’s status","allOf":[{"$ref":"#/components/schemas/ListingVisibility"}]},"inventoryBuffer":{"type":"number","nullable":true,"minimum":0,"description":"Units held back"},"maxQuantity":{"type":"number","nullable":true,"minimum":0,"description":"Most units shown"},"variantPrices":{"type":"array","items":{"$ref":"#/components/schemas/VariantPriceOverrideDto"}}}},"ListingOverridePatchDto":{"type":"object","properties":{"title":{"type":"string","nullable":true,"maxLength":255},"descriptionHtml":{"type":"string","nullable":true},"vendor":{"type":"string","nullable":true,"maxLength":255,"description":"The brand this channel shows instead of the product’s vendor"},"tags":{"nullable":true,"description":"Replaces the product’s tags","type":"array","items":{"type":"string"}},"mediaUrls":{"nullable":true,"description":"The product’s image URLs to show, in order","type":"array","items":{"type":"string"}},"visibility":{"nullable":true,"description":"Show or hide on this channel, whatever the product’s status","allOf":[{"$ref":"#/components/schemas/ListingVisibility"}]},"inventoryBuffer":{"type":"number","nullable":true,"minimum":0,"description":"Units held back"},"maxQuantity":{"type":"number","nullable":true,"minimum":0,"description":"Most units shown"},"variantPrices":{"type":"array","items":{"$ref":"#/components/schemas/VariantPriceOverrideDto"}}}},"InheritedTextDto":{"type":"object","properties":{"product":{"type":"string","description":"The product’s value"},"override":{"type":"string","nullable":true,"description":"Null when it follows the product"},"effective":{"type":"string","description":"What the store gets"},"overridden":{"type":"boolean","description":"Whether the store overrides it; reverting sets `override` to null"}},"required":["product","override","effective","overridden"]},"InheritedOptionalTextDto":{"type":"object","properties":{"product":{"type":"string","nullable":true,"description":"The product’s value"},"override":{"type":"string","nullable":true,"description":"Null when it follows the product"},"effective":{"type":"string","nullable":true,"description":"What the store gets"},"overridden":{"type":"boolean","description":"Whether the store overrides it; reverting sets `override` to null"}},"required":["product","override","effective","overridden"]},"InheritedTextListDto":{"type":"object","properties":{"product":{"type":"array","items":{"type":"string"}},"override":{"nullable":true,"description":"Null when it follows the product","type":"array","items":{"type":"string"}},"effective":{"type":"array","items":{"type":"string"}},"overridden":{"type":"boolean","description":"Whether the store overrides it; reverting sets `override` to null"}},"required":["product","override","effective","overridden"]},"InheritedVisibilityDto":{"type":"object","properties":{"product":{"description":"`VISIBLE` when the product is active, else `HIDDEN`","allOf":[{"$ref":"#/components/schemas/ListingVisibility"}]},"override":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ListingVisibility"}]},"effective":{"allOf":[{"$ref":"#/components/schemas/ListingVisibility"}]},"overridden":{"type":"boolean","description":"Whether the store overrides it; reverting sets `override` to null"}},"required":["product","override","effective","overridden"]},"ListingStockLimitsDto":{"type":"object","properties":{"inventoryBuffer":{"type":"number","nullable":true,"description":"Units held back from this store"},"maxQuantity":{"type":"number","nullable":true,"description":"The most units this store shows"}},"required":["inventoryBuffer","maxQuantity"]},"InheritedPriceDto":{"type":"object","properties":{"product":{"type":"string","example":"89.00","description":"The catalog price, in the workspace currency"},"override":{"type":"string","nullable":true,"example":"79.00"},"effective":{"type":"string","example":"102.99","description":"In the store’s currency: the override, else the pricing rule’s result"},"overridden":{"type":"boolean","description":"Whether the store overrides it; reverting sets `override` to null"}},"required":["product","override","effective","overridden"]},"InheritedCompareAtPriceDto":{"type":"object","properties":{"product":{"type":"string","nullable":true,"description":"In the workspace currency"},"override":{"type":"string","nullable":true},"effective":{"type":"string","nullable":true,"description":"In the store’s currency"},"overridden":{"type":"boolean","description":"Whether the store overrides it; reverting sets `override` to null"}},"required":["product","override","effective","overridden"]},"ListingEditorVariantDto":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Blue / Large"},"sku":{"type":"string","nullable":true},"price":{"$ref":"#/components/schemas/InheritedPriceDto"},"rulePrice":{"type":"string","example":"102.99","description":"In the store’s currency: what its pricing rule gives, before a fixed price on the listing. Equal to the effective price unless the price is overridden."},"compareAtPrice":{"$ref":"#/components/schemas/InheritedCompareAtPriceDto"},"resolvedPrice":{"description":"How the effective price was reached","allOf":[{"$ref":"#/components/schemas/ResolvedPriceDto"}]},"quantity":{"type":"number","nullable":true,"description":"The stock the store shows; null when the variant does not track stock"}},"required":["variantId","title","sku","price","rulePrice","compareAtPrice","resolvedPrice","quantity"]},"ListingCategoryFieldDto":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the channel has categories (eBay)"},"value":{"nullable":true,"description":"Null until the merchant chose one or a publish picked one","type":"object","allOf":[{"$ref":"#/components/schemas/ChannelCategoryDto"}]}},"required":["supported","value"]},"ListingItemSpecificsSummaryDto":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the channel has item specifics (eBay)"},"count":{"type":"number","description":"How many item specifics the merchant set on the listing"},"names":{"example":["Brand","Color"],"type":"array","items":{"type":"string"}}},"required":["supported","count","names"]},"ListingEditorDto":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"connection":{"$ref":"#/components/schemas/ConnectionSummaryDto"},"selected":{"type":"boolean","description":"Whether the connection’s product selection includes it"},"displayState":{"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`.","allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"displayReason":{"type":"string","nullable":true,"example":"Choose a shipping policy in this eBay connection’s listing defaults.","description":"For `needs_details` and `failed`: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states."},"displayRequirement":{"nullable":true,"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states.","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"listing":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ListingSummaryDto"}]},"title":{"$ref":"#/components/schemas/InheritedTextDto"},"descriptionHtml":{"$ref":"#/components/schemas/InheritedTextDto"},"vendor":{"description":"The brand the store shows","allOf":[{"$ref":"#/components/schemas/InheritedOptionalTextDto"}]},"tags":{"$ref":"#/components/schemas/InheritedTextListDto"},"images":{"description":"Image URLs in order; an override is a subset of the product’s, in its order","allOf":[{"$ref":"#/components/schemas/InheritedTextListDto"}]},"visibility":{"$ref":"#/components/schemas/InheritedVisibilityDto"},"stock":{"$ref":"#/components/schemas/ListingStockLimitsDto"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ListingEditorVariantDto"}},"category":{"$ref":"#/components/schemas/ListingCategoryFieldDto"},"itemSpecifics":{"$ref":"#/components/schemas/ListingItemSpecificsSummaryDto"},"overrideUpdatedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the overrides last changed; null when there are none"}},"required":["productId","connection","selected","displayState","displayReason","displayRequirement","listing","title","descriptionHtml","vendor","tags","images","visibility","stock","variants","category","itemSpecifics","overrideUpdatedAt"]},"ChooseChannelCategoryDto":{"type":"object","properties":{"category":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ChannelCategoryDto"}]}},"required":["category"]},"CategoryAspectUsage":{"type":"string","enum":["recommended","optional"]},"CategoryAspectMode":{"type":"string","enum":["free_text","selection_only"],"description":"`selection_only` takes one of `values`; `free_text` takes any text"},"CategoryAspectDto":{"type":"object","properties":{"name":{"type":"string","example":"Color"},"required":{"type":"boolean","description":"The channel refuses listings in the category without it"},"usage":{"allOf":[{"$ref":"#/components/schemas/CategoryAspectUsage"}]},"mode":{"description":"`selection_only` takes one of `values`; `free_text` takes any text","allOf":[{"$ref":"#/components/schemas/CategoryAspectMode"}]},"multiple":{"type":"boolean","description":"Whether a listing may give it several values"},"values":{"description":"The channel’s values, the first ones only","type":"array","items":{"type":"string"}}},"required":["name","required","usage","mode","multiple","values"]},"ItemSpecificDto":{"type":"object","properties":{"name":{"type":"string","example":"Material","maxLength":40},"values":{"example":["Stoneware"],"maxItems":30,"description":"Blank values are dropped; a specific left without values is removed","type":"array","items":{"type":"string"}}},"required":["name","values"]},"ListingItemSpecificsDto":{"type":"object","properties":{"category":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ChannelCategoryDto"}]},"aspects":{"description":"Required first, then recommended, then optional; none without a category","type":"array","items":{"$ref":"#/components/schemas/CategoryAspectDto"}},"itemSpecifics":{"type":"array","items":{"$ref":"#/components/schemas/ItemSpecificDto"}}},"required":["category","aspects","itemSpecifics"]},"SaveItemSpecificsDto":{"type":"object","properties":{"itemSpecifics":{"maxItems":60,"type":"array","items":{"$ref":"#/components/schemas/ItemSpecificDto"}}},"required":["itemSpecifics"]},"OrderStatus":{"type":"string","enum":["OPEN","PARTIALLY_FULFILLED","FULFILLED","CANCELLED"]},"OrderSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"#1001","description":"The number the merchant and buyer see"},"status":{"allOf":[{"$ref":"#/components/schemas/OrderStatus"}]},"currencyCode":{"type":"string","example":"USD"},"total":{"type":"string","example":"130.00","description":"What the buyer pays now"},"placedAt":{"format":"date-time","type":"string"},"connectionId":{"type":"string","format":"uuid"},"storeName":{"type":"string","example":"Demo Store"},"channel":{"type":"string","example":"shopify"},"itemCount":{"type":"number","description":"Units ordered, over every line"},"unmatchedLines":{"type":"number","description":"Lines that match no catalog variant, so their stock is not tracked"}},"required":["id","name","status","currencyCode","total","placedAt","connectionId","storeName","channel","itemCount","unmatchedLines"]},"OrderPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummaryDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"OrderLineDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"sku":{"type":"string","nullable":true},"quantity":{"type":"number"},"unitPrice":{"type":"string","example":"45.00"},"reservedQuantity":{"type":"number","description":"Units held for the order until they ship"},"fulfilledQuantity":{"type":"number","description":"Units shipped"},"variantId":{"type":"string","format":"uuid","nullable":true},"productId":{"type":"string","format":"uuid","nullable":true}},"required":["id","title","sku","quantity","unitPrice","reservedQuantity","fulfilledQuantity","variantId","productId"]},"OrderDetailDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"#1001","description":"The number the merchant and buyer see"},"status":{"allOf":[{"$ref":"#/components/schemas/OrderStatus"}]},"currencyCode":{"type":"string","example":"USD"},"total":{"type":"string","example":"130.00","description":"What the buyer pays now"},"placedAt":{"format":"date-time","type":"string"},"connectionId":{"type":"string","format":"uuid"},"storeName":{"type":"string","example":"Demo Store"},"channel":{"type":"string","example":"shopify"},"itemCount":{"type":"number","description":"Units ordered, over every line"},"unmatchedLines":{"type":"number","description":"Lines that match no catalog variant, so their stock is not tracked"},"externalId":{"type":"string","description":"The order’s id on its channel"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLineDto"}}},"required":["id","name","status","currencyCode","total","placedAt","connectionId","storeName","channel","itemCount","unmatchedLines","externalId","lines"]},"SalesRange":{"type":"string","enum":["last_7_days","last_30_days","last_90_days","last_12_months"]},"SalesInterval":{"type":"string","enum":["day","week","month"]},"SalesTotalsDto":{"type":"object","properties":{"sales":{"type":"string","example":"1290.00","description":"Order totals, cancelled orders left out"},"orders":{"type":"number"},"units":{"type":"number","description":"Units ordered"},"averageOrderValue":{"type":"string","nullable":true,"example":"43.00","description":"Sales per order"}},"required":["sales","orders","units","averageOrderValue"]},"ConnectionSalesDto":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"sales":{"type":"string","example":"120.00"},"orders":{"type":"number"}},"required":["connectionId","sales","orders"]},"SalesBucketDto":{"type":"object","properties":{"startsOn":{"type":"string","example":"2026-11-04","description":"First day of the bucket, in the time zone"},"sales":{"type":"string","example":"120.00"},"orders":{"type":"number"},"previousStartsOn":{"type":"string","example":"2026-10-05","description":"First day of the matching earlier bucket"},"previousSales":{"type":"string","example":"80.00"},"byConnection":{"description":"Stores with orders in the bucket","type":"array","items":{"$ref":"#/components/schemas/ConnectionSalesDto"}}},"required":["startsOn","sales","orders","previousStartsOn","previousSales","byConnection"]},"SalesStoreDto":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"sales":{"type":"string","example":"120.00"},"orders":{"type":"number"},"channel":{"type":"string","example":"shopify"},"displayName":{"type":"string","example":"Demo Store"}},"required":["connectionId","sales","orders","channel","displayName"]},"TopProductDto":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"title":{"type":"string"},"units":{"type":"number"},"sales":{"type":"string","example":"240.00","description":"Line prices times units"}},"required":["productId","title","units","sales"]},"SalesReportDto":{"type":"object","properties":{"range":{"allOf":[{"$ref":"#/components/schemas/SalesRange"}]},"interval":{"allOf":[{"$ref":"#/components/schemas/SalesInterval"}]},"timeZone":{"type":"string","example":"America/New_York"},"currencyCode":{"type":"string","example":"USD","description":"The workspace currency; amounts are in it"},"current":{"$ref":"#/components/schemas/SalesTotalsDto"},"previous":{"description":"The period of the same length before","allOf":[{"$ref":"#/components/schemas/SalesTotalsDto"}]},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/SalesBucketDto"}},"stores":{"description":"Every store, oldest first","type":"array","items":{"$ref":"#/components/schemas/SalesStoreDto"}},"topProducts":{"type":"array","items":{"$ref":"#/components/schemas/TopProductDto"}},"otherCurrencyOrders":{"type":"number","description":"Orders in other currencies, which the report leaves out"}},"required":["range","interval","timeZone","currencyCode","current","previous","buckets","stores","topProducts","otherCurrencyOrders"]},"InventoryValueDto":{"type":"object","properties":{"atCost":{"type":"string","example":"4120.50","description":"Units on hand times cost; no-cost variants left out"},"atPrice":{"type":"string","example":"9800.00","description":"Units on hand times price"},"unitsOnHand":{"type":"number","description":"Available plus held for orders"},"variantsWithoutCost":{"type":"number","description":"Variants with stock on hand but no cost"}},"required":["atCost","atPrice","unitsOnHand","variantsWithoutCost"]},"StockLevelCountsDto":{"type":"object","properties":{"inStock":{"type":"number"},"lowStock":{"type":"number"},"outOfStock":{"type":"number"},"untracked":{"type":"number","description":"Variants that do not track stock"}},"required":["inStock","lowStock","outOfStock","untracked"]},"ListingStatusCountDto":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ListingStatus"}]},"count":{"type":"number"}},"required":["status","count"]},"StoreHealthDto":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"channel":{"type":"string","example":"shopify"},"displayName":{"type":"string","example":"Demo Store"},"status":{"allOf":[{"$ref":"#/components/schemas/ChannelConnectionStatus"}]},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true},"listings":{"description":"Every listing status, in order","type":"array","items":{"$ref":"#/components/schemas/ListingStatusCountDto"}}},"required":["connectionId","channel","displayName","status","lastSyncedAt","listings"]},"InventoryReportDto":{"type":"object","properties":{"currencyCode":{"type":"string","example":"USD"},"value":{"$ref":"#/components/schemas/InventoryValueDto"},"stockLevels":{"$ref":"#/components/schemas/StockLevelCountsDto"},"lowStockThreshold":{"type":"number","description":"Available units at or below which stock counts as low"},"lowestStock":{"description":"Tracked variants out of stock or low, fewest available first (oversold before sold out), at most a few: the ones to restock first","type":"array","items":{"$ref":"#/components/schemas/InventoryItemDto"}},"stores":{"description":"Every store, oldest first","type":"array","items":{"$ref":"#/components/schemas/StoreHealthDto"}}},"required":["currencyCode","value","stockLevels","lowStockThreshold","lowestStock","stores"]},"ListingStateCountDto":{"type":"object","properties":{"state":{"allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"count":{"type":"number","description":"Products of the catalog in this state on the store"}},"required":["state","count"]},"StoreListingHealthDto":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"channel":{"allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"displayName":{"type":"string","example":"Demo Store"},"status":{"allOf":[{"$ref":"#/components/schemas/ChannelConnectionStatus"}]},"statusReason":{"type":"string","nullable":true,"description":"Why the store needs reconnecting or is in error; null otherwise"},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true},"states":{"description":"Every display state, in order, with how many products are in it: the same states and rule as the store’s product list (`draft` counts the catalog products not in the store)","type":"array","items":{"$ref":"#/components/schemas/ListingStateCountDto"}},"failedListings":{"type":"number","description":"Listings the channel refused on their last sync"}},"required":["connectionId","channel","displayName","status","statusReason","lastSyncedAt","states","failedListings"]},"StoreListingFailureDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"allOf":[{"$ref":"#/components/schemas/ListingStatus"}]},"source":{"description":"How the product joined the store: by hand, by an import, or by the automatic rule","allOf":[{"$ref":"#/components/schemas/ListingSource"}]},"externalId":{"type":"string","nullable":true,"description":"The product’s id on the channel"},"externalUrl":{"type":"string","nullable":true,"description":"Where to see it on the channel"},"lastError":{"type":"string","nullable":true,"description":"Why the last sync failed"},"missingRequirement":{"nullable":true,"description":"What the channel refused the last publish for lacking (such as `item_specifics`), when the merchant can add it; null otherwise","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true},"syncRequestedAt":{"format":"date-time","type":"string","nullable":true,"description":"When a sync or retry queued its publish, update or delist; null once that job finished or gave up. While set, a selected listing shows `displayState: publishing`."},"category":{"nullable":true,"description":"The channel category it is listed in, on channels with categories (eBay)","type":"object","allOf":[{"$ref":"#/components/schemas/ChannelCategoryDto"}]},"productId":{"type":"string","format":"uuid"},"productTitle":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"variantCount":{"type":"number"},"displayState":{"description":"The product on this store, in one state computed by the server: `draft` (not selected for the store), `needs_details` (selected, but the store setup or the product lacks something publishing needs), `ready` (publishable, not sent yet), `publishing` (queued or in flight, including an update of a published listing that a sync or retry queued), `published`, `failed`, `removing` (being taken off) or `removed`.","allOf":[{"$ref":"#/components/schemas/ListingDisplayState"}]},"displayReason":{"type":"string","nullable":true,"example":"Choose a shipping policy in this eBay connection’s listing defaults.","description":"For `needs_details` and `failed`: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states."},"displayRequirement":{"nullable":true,"description":"For `needs_details`: the requirement to fix first, so a client can open the right place. Store-setup requirements (`reconnect`, `account_settings`, `shipping_policy`, `payment_policy`, `return_policy`, `ship_from_location`, `listing_setup`) come before the product’s (`images`, `active_product`, `option_names`), which the server checks before publishing; `category` and `item_specifics` are known once the channel refused a publish. Null for the other states.","allOf":[{"$ref":"#/components/schemas/PublishRequirement"}]},"connectionId":{"type":"string","format":"uuid","description":"The store the listing is on"}},"required":["id","status","source","externalId","externalUrl","lastError","missingRequirement","lastSyncedAt","syncRequestedAt","category","productId","productTitle","imageUrl","variantCount","displayState","displayReason","displayRequirement","connectionId"]},"ListingHealthReportDto":{"type":"object","properties":{"stores":{"description":"Every store, oldest first","type":"array","items":{"$ref":"#/components/schemas/StoreListingHealthDto"}},"recentFailures":{"description":"The latest listings a channel refused, latest first, each with its display state and requirement so a client can link to the fix","type":"array","items":{"$ref":"#/components/schemas/StoreListingFailureDto"}},"failedListings":{"type":"number","description":"Failed listings in all, across the stores"}},"required":["stores","recentFailures","failedListings"]},"SuggestionStatus":{"type":"string","enum":["PENDING","APPLIED","REJECTED","STALE"]},"SuggestionKind":{"type":"string","enum":["listing_title","listing_description"]},"SuggestionConnectionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"allOf":[{"$ref":"#/components/schemas/ChannelType"}]},"displayName":{"type":"string","example":"Demo Store"}},"required":["id","channel","displayName"]},"SuggestionCreatorType":{"type":"string","enum":["AGENT","USER","API_KEY"]},"SuggestionAgent":{"type":"string","enum":["content_generator"],"description":"The agent that made it, for `AGENT` suggestions"},"SuggestionCreatorDto":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/SuggestionCreatorType"}]},"agent":{"nullable":true,"description":"The agent that made it, for `AGENT` suggestions","allOf":[{"$ref":"#/components/schemas/SuggestionAgent"}]},"userId":{"type":"string","format":"uuid","nullable":true,"description":"Who asked for it"},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true,"description":"The user’s or API key’s name"}},"required":["type","agent","userId","apiKeyId","name"]},"SuggestionReviewDto":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true},"reviewedAt":{"format":"date-time","type":"string"}},"required":["userId","apiKeyId","name","reviewedAt"]},"SuggestionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"productTitle":{"type":"string","example":"Stoneware Mug"},"imageUrl":{"type":"string","nullable":true},"connection":{"nullable":true,"description":"The store the change is for; null for the product’s own content","type":"object","allOf":[{"$ref":"#/components/schemas/SuggestionConnectionDto"}]},"kind":{"allOf":[{"$ref":"#/components/schemas/SuggestionKind"}]},"status":{"allOf":[{"$ref":"#/components/schemas/SuggestionStatus"}]},"currentValue":{"type":"string","description":"The value it replaces, as it was when it was made"},"proposedValue":{"type":"string"},"rationale":{"type":"string","description":"Why the agent proposes it"},"createdBy":{"$ref":"#/components/schemas/SuggestionCreatorDto"},"review":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/SuggestionReviewDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","productId","productTitle","imageUrl","connection","kind","status","currentValue","proposedValue","rationale","createdBy","review","createdAt","updatedAt"]},"SuggestionPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SuggestionDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Null on the last page"},"total":{"type":"number","description":"How many match in all, for page numbers"}},"required":["items","nextCursor","total"]},"BulkApproveSuggestionsDto":{"type":"object","properties":{"suggestionIds":{"minItems":1,"maxItems":100,"description":"Pending suggestions to approve; others are skipped","type":"array","items":{"type":"string","format":"uuid"}}},"required":["suggestionIds"]},"BulkReviewResultDto":{"type":"object","properties":{"items":{"description":"Each suggestion reviewed: `APPLIED`, or `STALE` when its field had changed","type":"array","items":{"$ref":"#/components/schemas/SuggestionDto"}},"skippedIds":{"description":"Ids not found in the workspace or no longer pending","type":"array","items":{"type":"string","format":"uuid"}}},"required":["items","skippedIds"]},"AiStatusDto":{"type":"object","properties":{"configured":{"type":"boolean","description":"False until the server has an AI provider key"},"provider":{"type":"string","example":"anthropic"},"model":{"type":"string","example":"claude-sonnet-5-5"}},"required":["configured","provider","model"]},"AiUsageTotalsDto":{"type":"object","properties":{"calls":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"}},"required":["calls","inputTokens","outputTokens"]},"AiFeature":{"type":"string","enum":["content_generation","content_draft","ask"]},"AiUsageLineDto":{"type":"object","properties":{"calls":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"feature":{"allOf":[{"$ref":"#/components/schemas/AiFeature"}]},"model":{"type":"string","example":"claude-sonnet-5-5"}},"required":["calls","inputTokens","outputTokens","feature","model"]},"AiUsageReportDto":{"type":"object","properties":{"from":{"format":"date-time","type":"string"},"to":{"format":"date-time","type":"string"},"totals":{"$ref":"#/components/schemas/AiUsageTotalsDto"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AiUsageLineDto"}}},"required":["from","to","totals","lines"]},"GenerateContentDto":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","description":"The store to write for"},"productIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["connectionId","productIds"]},"ContentGenerationReceiptDto":{"type":"object","properties":{"queued":{"type":"number","description":"Products queued; their suggestions arrive in the inbox"}},"required":["queued"]},"ContentField":{"type":"string","enum":["title","description"],"description":"The fields to rewrite"},"CreateContentDraftDto":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid","description":"The store the text is for; leave out for the catalog’s own content"},"fields":{"type":"array","minItems":1,"description":"The fields to rewrite","items":{"$ref":"#/components/schemas/ContentField"}},"instruction":{"type":"string","maxLength":500,"description":"What to change, such as \"shorter\" or \"mention it is dishwasher-safe\""},"title":{"type":"string","maxLength":100000,"description":"The title as edited and not yet saved; the saved one when left out"},"descriptionHtml":{"type":"string","maxLength":100000,"description":"The description as edited and not yet saved; the saved one when left out"}},"required":["productId","fields"]},"ContentDraftDto":{"type":"object","properties":{"title":{"type":"string","nullable":true,"description":"Null when not asked for"},"descriptionHtml":{"type":"string","nullable":true,"description":"Null when not asked for"}},"required":["title","descriptionHtml"]},"PickAgentWorkspaceDto":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","description":"A workspace the signed-in user belongs to"}},"required":["workspaceId"]},"AgentScope":{"type":"string","enum":["catalog:read","catalog:write","orders:read","stores:write","reports:read","suggestions:write"]},"AgentConnectionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clientId":{"type":"string","description":"The OAuth client id: a Client ID Metadata Document URL, or a registered id"},"clientName":{"type":"string","description":"The name the agent gives, such as \"Claude\""},"clientUri":{"type":"string","nullable":true,"description":"The agent’s home page"},"clientIcon":{"type":"string","nullable":true,"description":"The agent’s logo address, from its metadata. Crossmart never fetches it."},"userId":{"type":"string","format":"uuid","description":"The member who connected the agent"},"userName":{"type":"string"},"userEmail":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/AgentScope"}},"connectedAt":{"format":"date-time","type":"string"}},"required":["id","clientId","clientName","clientUri","clientIcon","userId","userName","userEmail","scopes","connectedAt"]},"AskQuestionDto":{"type":"object","properties":{"question":{"type":"string","minLength":3,"maxLength":500,"description":"A question about Crossmart, in any language","example":"Can I publish the same product to Shopify and eBay?"}},"required":["question"]},"AskOutcome":{"type":"string","enum":["answered","unknown","out_of_scope"],"description":"`answered` from the cited pages; `unknown` when the docs do not answer it (the answer points to support); `out_of_scope` when it is not about Crossmart"},"AskCitationDto":{"type":"object","properties":{"title":{"type":"string","description":"The page and section, such as \"Crossmart for developers › Rate limits\""},"url":{"type":"string","format":"uri","description":"The public page the answer is based on"}},"required":["title","url"]},"AskConfidence":{"type":"string","enum":["high","medium","low"]},"AskAnswerDto":{"type":"object","properties":{"outcome":{"description":"`answered` from the cited pages; `unknown` when the docs do not answer it (the answer points to support); `out_of_scope` when it is not about Crossmart","allOf":[{"$ref":"#/components/schemas/AskOutcome"}]},"answer":{"type":"string","description":"The answer, in plain text or short Markdown"},"citations":{"description":"Pages the answer is based on","type":"array","items":{"$ref":"#/components/schemas/AskCitationDto"}},"confidence":{"allOf":[{"$ref":"#/components/schemas/AskConfidence"}]},"handoff":{"type":"boolean","description":"True when a person should take over, at supportEmail"},"supportEmail":{"type":"string","format":"email"}},"required":["outcome","answer","citations","confidence","handoff","supportEmail"]}}},"security":[{"api_key":[]},{"cookie":[]},{"bearer":[]}]}