{"openapi":"3.1.0","info":{"title":"SEEGEA Public API","version":"1.0.0","summary":"Read the product catalog, collections and orders of a connected e-commerce shop.","description":"SEEGEA is a PIM that sits on top of Shopify and PrestaShop. The public API exposes the\ncatalog SEEGEA has already synchronised from the merchant CMS, so an agent can read\nproducts, variants, collections and orders through one shape whatever the CMS behind them.\n\n## Authentication\n\nTwo interchangeable credentials are accepted on every endpoint:\n\n- **API key** — send the key created in *Settings → API* as `Authorization: Bearer sgk_....<secret>`.\n- **OAuth 2.0 client credentials** — exchange the same key at `https://www.seegea.com/api/oauth/token` for a one-hour access token, then send that token as a Bearer token.\n\nBoth carry the scopes granted to the key. Request the narrowest scope that covers the job.\n\n## Plan\n\nAPI access is part of the Business plan. On any other plan every endpoint answers\n`403` with the code `PLAN_LIMIT_EXCEEDED` — a subscription boundary, not a transient error.\n\n## Pagination\n\nList endpoints are cursor-paginated. Follow `next_cursor` until `has_more` is `false`.\n\n## Rate limits\n\n120 requests per minute per credential. Responses carry\n`RateLimit-Limit` and `RateLimit-Remaining`; a 429 carries `Retry-After`.","termsOfService":"https://www.seegea.com/fr/legal/terms.html","contact":{"name":"SEEGEA","email":"contact@seegea.com","url":"https://www.seegea.com/fr/contact.html"},"license":{"name":"Proprietary","url":"https://www.seegea.com/fr/legal/terms.html"},"x-privacy-policy":"https://www.seegea.com/fr/legal/privacy.html"},"externalDocs":{"description":"SEEGEA API guide","url":"https://www.seegea.com/fr/developers/api-seegea.html"},"servers":[{"url":"https://www.seegea.com/api/v1","description":"Production"}],"tags":[{"name":"Shop","description":"The connected shop, its plan and its limits."},{"name":"Products","description":"Products and their variants."},{"name":"Collections","description":"Product collections and categories."},{"name":"Orders","description":"Read-only mirror of the CMS orders."}],"security":[{"oauth2":["catalog:read"]},{"apiKey":[]}],"x-rate-limit":{"requests":120,"window_seconds":60,"scope":"credential"},"paths":{"/shop":{"get":{"operationId":"getShop","tags":["Shop"],"summary":"Get the connected shop","description":"Returns the shop the credential belongs to: its CMS platform, currency, plan, product limit and the scopes the credential actually carries. Call this first to discover what the rest of the API will let you do.","security":[{"oauth2":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"The connected shop.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Shop"}}}}}},"401":{"description":"Missing or invalid credentials. The `WWW-Authenticate` header carries a `resource_metadata` parameter pointing at the protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential is valid but the call is not allowed: either it lacks the scope this operation requires (`FORBIDDEN`), or the shop is not on the Business plan (`PLAN_LIMIT_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this credential. Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"operationId":"listProducts","tags":["Products"],"summary":"List products","description":"Returns the shop products in a stable order (oldest first), cursor-paginated. Products hidden by the plan limit and soft-deleted products are never returned. Variants are omitted here — fetch a single product to get them.","security":[{"oauth2":["catalog:read"]},{"apiKey":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on the product title or handle.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter on the publication status of the product.","schema":{"type":"string","enum":["ACTIVE","DRAFT","ARCHIVED"]}},{"name":"vendor","in":"query","required":false,"description":"Exact match on the vendor / brand.","schema":{"type":"string"}},{"name":"product_type","in":"query","required":false,"description":"Exact match on the product type.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Return only products carrying this tag.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of records to return per page (max 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned as `next_cursor` by the previous page. Omit it to start from the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}]}}}},"401":{"description":"Missing or invalid credentials. The `WWW-Authenticate` header carries a `resource_metadata` parameter pointing at the protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential is valid but the call is not allowed: either it lacks the scope this operation requires (`FORBIDDEN`), or the shop is not on the Business plan (`PLAN_LIMIT_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this credential. Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}":{"get":{"operationId":"getProduct","tags":["Products"],"summary":"Get a product with its variants","description":"Returns one product and every variant attached to it, ordered by position. Responds 404 when the product does not exist, is soft-deleted, is hidden by the plan limit, or belongs to another shop.","security":[{"oauth2":["catalog:read"]},{"apiKey":[]}],"parameters":[{"name":"productId","in":"path","required":true,"description":"SEEGEA product id (UUID), as returned by `listProducts`.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The product and its variants.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductWithVariants"}}}}}},"401":{"description":"Missing or invalid credentials. The `WWW-Authenticate` header carries a `resource_metadata` parameter pointing at the protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential is valid but the call is not allowed: either it lacks the scope this operation requires (`FORBIDDEN`), or the shop is not on the Business plan (`PLAN_LIMIT_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product for this shop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this credential. Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections":{"get":{"operationId":"listCollections","tags":["Collections"],"summary":"List collections","description":"Returns the shop collections (Shopify collections, PrestaShop categories) in a stable order, cursor-paginated.","security":[{"oauth2":["catalog:read"]},{"apiKey":[]}],"parameters":[{"name":"published","in":"query","required":false,"description":"Restrict to published (`true`) or unpublished (`false`) collections.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Number of records to return per page (max 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned as `next_cursor` by the previous page. Omit it to start from the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of collections.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}]}}}},"401":{"description":"Missing or invalid credentials. The `WWW-Authenticate` header carries a `resource_metadata` parameter pointing at the protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential is valid but the call is not allowed: either it lacks the scope this operation requires (`FORBIDDEN`), or the shop is not on the Business plan (`PLAN_LIMIT_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this credential. Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List orders","description":"Returns the orders SEEGEA imported from the CMS, cursor-paginated. Customer email addresses are deliberately not exposed by this API.","security":[{"oauth2":["orders:read"]},{"apiKey":[]}],"parameters":[{"name":"financial_status","in":"query","required":false,"description":"Exact match on the CMS financial status (e.g. `PAID`, `PENDING`).","schema":{"type":"string"}},{"name":"fulfillment_status","in":"query","required":false,"description":"Exact match on the CMS fulfillment status (e.g. `FULFILLED`).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of records to return per page (max 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned as `next_cursor` by the previous page. Omit it to start from the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of orders.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}]}}}},"401":{"description":"Missing or invalid credentials. The `WWW-Authenticate` header carries a `resource_metadata` parameter pointing at the protected-resource metadata document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential is valid but the call is not allowed: either it lacks the scope this operation requires (`FORBIDDEN`), or the shop is not on the Business plan (`PLAN_LIMIT_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this credential. Retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client credentials grant (RFC 6749 section 4.4). The API key created in Settings → API is the `client_id` / `client_secret` pair. Authorization server metadata is published at `/.well-known/oauth-authorization-server`.","flows":{"clientCredentials":{"tokenUrl":"https://www.seegea.com/api/oauth/token","refreshUrl":"https://www.seegea.com/api/oauth/token","scopes":{"catalog:read":"Read products, variants, media and collections.","orders:read":"Read imported orders (read-only mirror of the CMS orders).","account:read":"Read the connected shop, its plan and its usage counters."}}}},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"SEEGEA API key","description":"Send the API key directly: `Authorization: Bearer sgk_<id>.<secret>`. The key carries the scopes it was created with."}},"schemas":{"Error":{"type":"object","description":"Uniform error envelope used by every 4xx and 5xx response.","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","examples":["UNAUTHORIZED","FORBIDDEN","PLAN_LIMIT_EXCEEDED","NOT_FOUND","RATE_LIMITED"]},"message":{"type":"string","description":"Human-readable explanation."}}}}},"Page":{"type":"object","description":"Cursor pagination envelope shared by every list endpoint.","required":["has_more","next_cursor"],"properties":{"has_more":{"type":"boolean","description":"True when another page is available."},"next_cursor":{"type":["string","null"],"description":"Cursor to pass back as `cursor` to fetch the next page."}}},"Shop":{"type":"object","description":"The e-commerce shop a credential belongs to.","required":["id","platform","plan","product_count","granted_scopes"],"properties":{"id":{"type":"string","format":"uuid","description":"SEEGEA shop id."},"name":{"type":["string","null"],"description":"Shop display name."},"domain":{"type":["string","null"],"description":"Shop domain on the CMS."},"platform":{"type":["string","null"],"description":"CMS behind this shop.","examples":["shopify","prestashop"]},"currency":{"type":["string","null"],"description":"ISO 4217 currency code."},"plan":{"type":"string","description":"Active SEEGEA subscription plan.","enum":["free","starter","pro","business"]},"plan_status":{"type":"string","description":"Subscription status."},"product_limit":{"type":["integer","null"],"description":"Products the plan allows; null means unlimited."},"product_count":{"type":"integer","description":"Products currently readable through the API."},"last_sync_at":{"type":["string","null"],"format":"date-time","description":"Last successful synchronisation with the CMS."},"created_at":{"type":"string","format":"date-time"},"granted_scopes":{"type":"array","description":"Scopes carried by the credential used for this call.","items":{"type":"string","enum":["catalog:read","orders:read","account:read"]}}}},"Product":{"type":"object","description":"A product as SEEGEA stores it, normalised across CMS platforms.","required":["id","external_id","title","status","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"SEEGEA product id."},"external_id":{"type":"string","description":"Id of the same product in the merchant CMS."},"title":{"type":"string","description":"Product title."},"handle":{"type":["string","null"],"description":"URL slug on the storefront."},"status":{"type":"string","description":"Publication status.","enum":["ACTIVE","DRAFT","ARCHIVED"]},"vendor":{"type":["string","null"],"description":"Vendor or brand."},"product_type":{"type":["string","null"],"description":"Product type."},"tags":{"type":"array","items":{"type":"string"},"description":"Product tags."},"description_html":{"type":["string","null"],"description":"Long description, as HTML."},"seo_title":{"type":["string","null"],"description":"SEO meta title."},"seo_description":{"type":["string","null"],"description":"SEO meta description."},"image_url":{"type":["string","null"],"description":"Main image URL."},"variant_count":{"type":"integer","description":"Number of variants."},"min_price":{"type":["string","null"],"description":"Lowest variant price, as a decimal string."},"max_price":{"type":["string","null"],"description":"Highest variant price, as a decimal string."},"total_stock":{"type":"integer","description":"Stock summed across variants."},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProductWithVariants":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","required":["variants"],"properties":{"variants":{"type":"array","description":"Every variant of the product, ordered by position.","items":{"$ref":"#/components/schemas/Variant"}}}}]},"Variant":{"type":"object","description":"A single purchasable variant of a product.","required":["id","external_id","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string","description":"Id of the variant in the merchant CMS."},"title":{"type":["string","null"],"description":"Variant label."},"sku":{"type":["string","null"],"description":"Stock keeping unit."},"barcode":{"type":["string","null"],"description":"EAN / UPC barcode."},"price":{"type":["string","null"],"description":"Selling price, decimal string."},"compare_at_price":{"type":["string","null"],"description":"Strikethrough price, decimal string."},"cost_price":{"type":["string","null"],"description":"Cost price, decimal string."},"inventory_quantity":{"type":["integer","null"],"description":"Stock on hand."},"weight":{"type":["string","null"],"description":"Weight, decimal string."},"weight_unit":{"type":["string","null"],"description":"Unit of `weight`."},"position":{"type":["integer","null"],"description":"Display order."},"image_url":{"type":["string","null"],"description":"Variant image URL."},"options":{"type":"array","description":"Option name/value pairs identifying the variant.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Collection":{"type":"object","description":"A collection (Shopify) or category (PrestaShop).","required":["id","external_id","title","published","products_count"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string","description":"Id of the collection in the CMS."},"title":{"type":"string"},"handle":{"type":["string","null"],"description":"URL slug on the storefront."},"description_html":{"type":["string","null"]},"published":{"type":"boolean","description":"Visible on the storefront."},"collection_type":{"type":["string","null"],"description":"How membership is decided.","examples":["manual","smart"]},"products_count":{"type":"integer"},"image_url":{"type":["string","null"]},"seo_title":{"type":["string","null"]},"seo_description":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"Order":{"type":"object","description":"An order imported from the CMS. Read-only, and without customer email addresses.","required":["id","external_id","order_number","items_count"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string","description":"Id of the order in the CMS."},"order_number":{"type":"string","description":"Merchant-facing order number."},"customer_name":{"type":["string","null"]},"currency":{"type":["string","null"],"description":"ISO 4217 currency code."},"total_price":{"type":["string","null"],"description":"Decimal string."},"subtotal_price":{"type":["string","null"],"description":"Decimal string."},"total_tax":{"type":["string","null"],"description":"Decimal string."},"total_shipping":{"type":["string","null"],"description":"Decimal string."},"financial_status":{"type":["string","null"]},"fulfillment_status":{"type":["string","null"]},"items_count":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}}}},"x-metadata":{"openapi_url":"https://www.seegea.com/openapi.json","oauth_authorization_server":"https://www.seegea.com/.well-known/oauth-authorization-server","oauth_protected_resource":"https://www.seegea.com/.well-known/oauth-protected-resource/api/v1","llms_txt":"https://www.seegea.com/llms.txt"}}