This article shows you where to find the full technical reference for CommentSold's Open API, including request parameters, filters, request body fields, and example responses. It's written for developers and technical teams building custom integrations, such as automations in n8n, Zapier, Make, or your own backend.
| Note: The Open API tab in your admin lists the available endpoints and your credentials. Detailed parameter and response documentation lives on the CommentSold developer site: developers.commentsold.com. |
Prerequisites
Before getting started, make sure you have:
- A Small Business or Large Business plan. Open API isn't available on lower plans.
- Open API enabled and credentials generated in Setup > Open API.
- Development resources. Open API isn't a no-code feature, so you'll need someone comfortable making HTTP requests and handling JSON.
To learn how to enable Open API and generate credentials, see Connect CommentSold to Other Business Tools With Open API.
Access the API Reference
- Open the developer site. Go to developers.commentsold.com. No login is required to read the documentation.
- Skip the partner authorization steps in the Introduction. The Introduction at the top of the developer site explains the OAuth authorization flow for CommentSold partners, who are third-party apps installed by many shops. If you're connecting your own shop, you don't need that flow. Keep using the connection and credentials you set up in Setup > Open API. The Errors part of the Introduction still applies to everyone.
- Select an endpoint group. Use the left-hand navigation to open a group, such as Products or Orders. Each endpoint lists its query parameters, request body fields (with required fields marked), example responses, and possible errors.
- Download the OpenAPI spec (optional). Use the download button on the developer site to save the full OpenAPI 3.0 specification as a YAML file. You can import this file into Postman, Insomnia, or other API tools to generate a ready-made collection.
|
Tip! In Postman, select Import and choose the downloaded YAML file. Postman creates a collection with every endpoint, grouped the same way as the developer site. |
|
Important! If your integration is already connected and working, don't change how you authenticate. The authorization, consent, and token steps in the developer site's Introduction are for partner apps only. Everything else on the developer site, including endpoints, parameters, request fields, and example responses, works the same for your connection. |
API Basics
| Item | Details |
| Base URL | https://openapi.commentsold.com |
| Path format | Every path starts with /{version}/{shop_id}. For example: /2026-08/{shop_id}/products |
| Authentication | Send your access token in the header: Authorization: Bearer <token> |
| Get a token | For your own integration, request a token from POST /{version}/{shop_id}/oauth/token using the credentials from Setup > Open API. Tokens last one hour. |
| Check your access | GET /whoami returns your shop ID, shop name, and the scopes your token has. Call this first if a request is refused. |
| Format |
JSON requests and responses
|
Available Endpoint Groups
Endpoints are organized into these groups on the developer site:
| Group | What you can do |
| Products | Search, create, update, publish or archive products; add variants and images; find low-stock products |
| Variants | Update a variant and set its price |
| Inventory | Adjust stock and view a variant's stock history |
| Orders | List orders and get a single order |
| Fulfillment | Record a shipment for an order |
| Collections | Create and delete collections; add or remove products |
| Categories | Search the product taxonomy to find category IDs |
| Live selections | Create, rename, and delete live selections; add or remove products |
| Live replays | List lives and retrieve a live's recording and featured products |
| Webhooks | Subscribe to events, list subscriptions, and delete them |
| Credentials / Identity | Get an access token and confirm your credential |
Search Products (GET /products)
Use GET /{version}/{shop_id}/products to search and page through your catalog. All parameters are optional.
| Parameter | Description |
| query | Free-text search across product name, brand, brand style, note, product type, and SKU/style |
| status | published (default), draft, archived, or any |
| tags | Returns products with any of the listed tags |
| low_stock_only | When true, returns only products with a variant below its low-stock limit |
| include_descriptions | When true, also searches product descriptions. Default false |
| sort | newest (default), quantity, price, created_at, published_at, or name |
| order | asc or desc (default). Ignored when sort is newest |
| include | Pass variants to embed each product's full variant list (SKU, color, size, quantity, price, and more) |
| variant_status | active (default), archived, or any |
| page / per_page | Page number and page size. Default page size is 25 |
Example Response
|
{ "query": "", "status": "published", "tags": [], "sort": "newest", "order": "desc", "page": 1, "per_page": 25, "total": 1, "last_page": 1, "items": [ { "product_id": 2109, "product_name": "Ribbed Knit Cardigan", "style": "RKC-114", "brand": "10", "status": "published", "created_at": "2020-01-01T21:04:05-06:00", "published_at": "2019-12-01T21:04:05-06:00", "webstore_url": "https://acme-outfitters.commentsold.com/products/id/2109", "variant_count": 0, "total_quantity": 0, "lowest_price": null, "highest_price": null, "tags": [], "is_low_stock": false } ] } |
Paging Through a Large Catalog
- Every response includes total and last_page. Increase page until you reach last_page.
- Use a fixed sort, such as sort=created_at&order=asc, so results stay in a stable order while you page.
- Add include=variants to get variant details in the same call instead of one extra call per product. With variants embedded, the maximum page size drops to 50. The response shows the per_page value actually applied.
Create a Product (POST /products)
Use POST /{version}/{shop_id}/products with a JSON body. Only name and variants are required.
| Field | Required | Description |
| name | Yes | Product name |
| variants | Yes | At least one variant. A single-variant product still needs one entry |
| sku | No | Product-level SKU/style. Defaults to the first variant's SKU |
| description / short_description | No | Full description (HTML allowed) and short description for the mobile app |
| brand / brand_style / product_type | No | Catalog details |
| category | No | Category ID. Look it up with GET /categories |
| tags / collections | No | Product tags and collection IDs to add the product to |
| charge_taxes / tax_code | No | Taxes are charged by default |
| published | No | Publishes to the storefront immediately. Defaults to true |
Variant fields: sku and price are required. Optional fields are sale_price, quantity (defaults to 0), cost, color, size, and barcode.
Example Request Body
|
{ "name": "Ribbed Knit Cardigan", "brand": "Acme", "tags": ["fall", "knitwear"], "published": false, "variants": [ { "sku": "RKC-114-BLK-S", "price": 39.99, "quantity": 10, "color": "Black", "size": "S" }, { "sku": "RKC-114-BLK-M", "price": 39.99, "quantity": 12, "color": "Black", "size": "M" } ] } |
|
Tip! Set published to false while testing so new products don't appear on your storefront until you're ready. |
Prevent Duplicate Products
- Search by SKU first. Call GET /products?query=YOUR-SKU&status=any. The search covers SKU/style and, with status=any, includes draft and archived products.
- Create only when nothing matches. If a product exists, use PATCH /products/{id} to update it instead.
- Handle the duplicate error. If a SKU already exists, POST /products returns a 409 with the code duplicate_sku. Treat this as "already exists" in your workflow rather than retrying.
Errors and Rate Limits
Every error uses the same format:
{ "error": { "code": "forbidden_by_permission", "message": "…" }, "request_id": "9b1c…" }
| Status | What it means |
| 403 | Your token is missing the scope or permission for this endpoint. Check GET /whoami |
| 409 | Conflict with the shop's current data, such as a duplicate SKU. Retrying unchanged won't fix it |
| 422 | The request body didn't match the expected fields. error.detail names the fields |
| 429 | Too many requests. Wait the number of seconds in the Retry-After header before trying again |
Build your workflow logic around error.code, not the message text, since messages may change.
|
Important! An integration can only do what the team member who set it up can do. If that user can't access orders, the integration can't either. Use an account with the permissions your workflow needs. |
FAQs
Is there a Postman collection?
Download the OpenAPI spec from developers.commentsold.com and import it into Postman. This creates a full collection automatically.
Can I use Open API with n8n?
Yes. Use n8n's HTTP Request node with the base URL, path format, and bearer token described above. The HTTP Request node works with every endpoint.
How do I avoid polling for new orders?
Subscribe to events with POST /webhooks. CommentSold notifies your workflow when the event happens, so you don't need to repeatedly call GET /orders.
Who do I contact if a request fails?
Contact CommentSold Support and include the request_id from the response. It's also returned as a response header on every request.