Read and Update Your Catalog, Listings and Orders in Code
The REST API exposes the same 20 tools as the LitCommerce MCP server, as JSON over HTTPS with one bearer token. Read freely, and approve every change before it applies.
Free 7-day trial 20 tool endpoints, one token
Get Started in Three Steps
Get your token
Open API/MCP in your LitCommerce account and click Get API Token. Each token is bound to one store and a set of scopes, so you do not need to pass a store_id on each call.
Make your first call
Every tool is a POST to /api/v1/tools/<name> with a JSON body. Start with a read call to confirm the token works.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/get_stores \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Read, then write
Write tools run in two calls. The first returns a plan and a confirmation_token, valid for 10 minutes. Nothing changes until you send the second call with the same plan, the token and an idempotency_key.
# 1. Dry run (default): returns a plan and a confirmation_token
curl -X POST https://mcp.litcommerce.com/api/v1/tools/adjust_price \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"items":[{"product_id":"64f0a1b2c3d4e5f607182930","price":33.00}],"dry_run":true}'
# 2. Apply after the user confirms
curl -X POST https://mcp.litcommerce.com/api/v1/tools/adjust_price \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"items":[{"product_id":"64f0a1b2c3d4e5f607182930","price":33.00}],"dry_run":false,"confirmation_token":"<token from step 1>","idempotency_key":"price-2026-11-18-0001"}'Check Your Account With One Request
get_account_status is a read call. It returns your account and store status, so you can confirm the token works before you try anything else.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/get_account_status \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'One Token per Store, With Only the Scopes You Need
Send your token as a bearer header on every call. A token is bound to one store, so a call does not need a store ID. Only MCP connections granted several stores pass store_id.
API/MCP page
Send the token
Add Authorization: Bearer <token> and Content-Type: application/json to every call. Tokens start with lc_live_. Keep them in an environment variable, never in source code.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/get_stores \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Scopes
Choose the scopes when you create a token. A call to a tool outside the token’s scopes returns insufficient_scope.
| Scope | Lets the token | Tools |
|---|---|---|
catalog:read | Read products, listings, stores, channel health and imports | find_products, find_listings, find_library_images, get_stores, get_account_status, get_channel_health, get_import_status, get_operation |
catalog:write | Create and edit products, prices, drafts and imports | create_products, update_product_content, adjust_price, create_channel_drafts, import_from_mainstore, trigger_mainstore_refresh, upload_product_images |
inventory:write | Change stock quantities | update_inventory |
orders:read | Read orders | get_orders, get_order |
orders:write | Add tracking to orders | add_order_tracking |
ai:credits | Generate product content, which uses AI credits | generate_product_content |
20 Tools, Each a POST Endpoint
Every tool is a POST to /api/v1/tools/<name> with a JSON body. Helper endpoints sit alongside them. The full request and response schemas are in the API reference.
| Endpoint | Type | Scope | What it does |
|---|---|---|---|
get_stores | Read | catalog:read | Shows your store and its channels, with counts per tab. |
get_account_status | Read | catalog:read | Shows account and store status. |
get_channel_health | Read | catalog:read | Shows a channel’s connection, sync settings, last import or refresh, and running processes. |
get_import_status | Read | catalog:read | Shows import and sync progress for a channel. Filter by product, order, inventory, refresh or category. |
get_operation | Read | catalog:read | Shows the status of a write job: queued, running, done, failed or sent. |
find_products | Read | catalog:read | Lists main-store products, with variants excluded. Requires status and in_stock. |
find_listings | Read | catalog:read | Lists a channel’s listings. Requires channel_id, status and link_status. |
find_library_images | Read | catalog:read | Searches your Image Library. Requires folder and a name of at least two characters. |
get_orders | Read | orders:read | Lists orders for one day or one month, newest first. Requires date or month. |
get_order | Read | orders:read | Shows one order with its lines and status. Buyer information is not returned. |
create_products | Write | catalog:write | Creates up to 50 simple products in your main store. Images must come from the Image Library. |
update_product_content | Write | catalog:write | Edits name, description, brand or SKU for up to 50 products. Changes push to active channel listings. |
update_inventory | Write | inventory:write | Sets stock quantity for up to 100 products or variants. |
adjust_price | Write | catalog:write | Sets new selling prices for up to 100 products or variants. |
create_channel_drafts | Write | catalog:write | Creates unpublished drafts on a channel for up to 50 products. Products already on the channel are skipped. |
import_from_mainstore | Write | catalog:write | Imports products from your main store as a background job. Adds only products not yet in LitCommerce. |
trigger_mainstore_refresh | Write | catalog:write | Overwrites up to 50 products with the data from the main store. Each store has a 30-minute cooldown. |
add_order_tracking | Write | orders:write | Adds a tracking number to an order, then pushes it to the channel. |
generate_product_content | Write | ai:credits | Generates a title, description, tags and attributes from one to four images. Returns text only. |
upload_product_images | Write | catalog:write | Uploads one to five images to the Image Library from public https URLs. |
Helper endpoints
GET /api/v1/toolslists the tools available for your store type and token scopes.GET /api/v1/operations/{op_id}returns the status of a write job, the same as theget_operationtool.GET /api/v1/openapi.jsonreturns the OpenAPI specification for generating a client.
Every Change Is Previewed Before It Runs
Write tools run in two calls. The first call returns a plan with the current values. Your code sends the second call only after the user approves that plan.
Step 1: preview
dry_run defaults to true. The response holds the plan and a confirmation_token. The token is valid for 10 minutes and works once.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/adjust_price \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"items":[{"product_id":"<product id>","price":33.00}],"dry_run":true}'Step 2: apply
Send the same items with dry_run set to false, the token and an idempotency_key of 8 to 100 characters. Use a new key for each write intent.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/adjust_price \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"items":[{"product_id":"<product id>","price":33.00}],"dry_run":false,"confirmation_token":"<token from step 1>","idempotency_key":"price-2026-11-18-0001"}'| Rule | What happens |
|---|---|
| Data changed in between | If the data changes between preview and apply, the apply returns plan_changed. Run the dry run again. |
| Safe retries | The same key with the same parameters returns the earlier result with idempotent_replay: true, and nothing is written twice. Reusing a key with different parameters returns idempotency_key_reused. |
| Price limit | Each price can change by at most ±50% from the current price. |
| Failed midway | The response returns previous_attempt_failed or outcome_unknown. Check with a read tool, then dry run again with a new key. |
| Partial failure | If some items fail in create_products, do not repeat the whole call. Fix and resend only the failed items. |
| No undo | create_products has no undo. Check the preview carefully before you apply. |
| Shipping tracking | Do not call add_order_tracking again after tracking_saved_push_failed. |
| Drafts | create_channel_drafts creates unpublished drafts. Products already on the channel are skipped. |
Six Calls Every Integration Uses
Each example uses a real tool with its required fields. Replace the placeholder values with your own.
List products by status
find_products requires status and in_stock. Each page holds up to 50 rows. Pass the next_cursor from the response to get the next page.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/find_products \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"active","in_stock":true}'List orders for one day
get_orders needs a date (YYYY-MM-DD) or a month (YYYY-MM). Results are newest first, and created_at is in UTC.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/get_orders \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"date":"2026-11-18"}'Add tracking to an order
add_order_tracking needs the order ID, a carrier and a tracking number. Set fulfill_all to true, or pass line_items.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/add_order_tracking \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"order_id":"<24-character order id>","carrier":"<carrier>","tracking_number":"123","fulfill_all":true,"dry_run":true}'Create drafts on a channel
create_channel_drafts takes a channel_id and up to 50 product_ids. The drafts are not published.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/create_channel_drafts \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"channel_id":"<channel id>","product_ids":["<product id>"],"dry_run":true}'Upload images to a product
upload_product_images takes one to five public https URLs. Images must be JPG, PNG or WEBP, up to 10 MB each. Redirects are not followed.
curl -X POST https://mcp.litcommerce.com/api/v1/tools/upload_product_images \
-H "Authorization: Bearer $LITC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"urls":["https://example.com/images/front.jpg"]}'Track a background job
Some writes run in the background and return an operation ID. Poll the status, and wait the next_check_after number of seconds between checks. A status of sent does not mean done.
curl https://mcp.litcommerce.com/api/v1/operations/<op_id> \
-H "Authorization: Bearer $LITC_TOKEN"Read Large Catalogs One Page at a Time
List tools need a filter, and they return a page of up to 50 rows with a cursor for the next page.
Pages and limits
- Each page holds up to 50 rows.
- A single browse reads up to 10 pages. Narrow the filter to read more.
- A search that is too heavy returns
query_too_heavy. Add a filter. find_listingsreturns rows in the system index order, not newest first.- While a sync runs, a browse can show duplicates or gaps. Read from the start once the sync finishes.
| Batch limit | Maximum items | Tools |
|---|---|---|
| 100 items | 100 | adjust_price, update_inventory, add_order_tracking line items |
| 50 items | 50 | create_products, update_product_content, create_channel_drafts, trigger_mainstore_refresh |
| 5 images | 5 | upload_product_images |
| 4 images | 4 | generate_product_content |
| 8 image URLs per item | 8 | create_products, per item |
One Error Format for Every Tool
Every error body has the same shape, so one handler covers all 20 tools.
{"error": "plan_changed", "message": "The data changed after the preview. Run the dry run again."}| HTTP status | Error codes |
|---|---|
| 400 | invalid_confirmation_token, invalid_cursor, invalid_input |
| 401 | unauthenticated |
| 402 | insufficient_ai_credits |
| 403 | account_unavailable, insufficient_scope, store_not_granted |
| 404 | not_found, unknown_tool |
| 409 | busy, channel_disconnected, confirmation_token_used, idempotency_key_reused, in_progress, not_ready, nothing_applied, order_not_editable, outcome_unknown, partial_failure, plan_changed, previous_attempt_failed, store_not_selected, tracking_saved_push_failed, unsupported_main_store, wrong_main_store |
| 410 | confirmation_token_expired |
| 422 | apply_rejected, cannot_verify_price, image_not_in_library, invalid_line_item, not_linked, nothing_to_change, nothing_to_create, nothing_to_ship, order_has_no_lines, page_limit_reached, plan_limit_exceeded, price_change_too_large, qty_exceeds_remaining, query_too_heavy, too_many_items |
| 428 | confirm_count_required, confirmation_required, idempotency_key_required |
| 429 | cooldown_active, quota_exceeded, too_many_requests |
| 500, 502, 503 | internal_error, apply_failed, store_failed, data_unavailable, service_busy, unavailable |
The spec attaches codes per response, so a tool may return only some of the codes listed for its status. Check the API reference for each tool.
Each Tool Has Its Own Limit, Scaled by Your Plan
Limits are set per tool, per minute and per day. The base values below are for a plan with up to 2,000 listings. Your plan’s multiplier scales them.
Your plan’s multiplier
| Listings on your plan | Multiplier |
|---|---|
| Up to 20 | ×0.5 |
| Up to 2,000 | ×1 |
| Up to 10,000 | ×2 |
| Up to 50,000 | ×3 |
| Over 50,000 | ×4 |
Each tool scales in one of three ways. full tools scale fully, write tools scale but stop at ×2, and none tools stay fixed.
| Tool | Scale type | Per minute | Per day |
|---|---|---|---|
find_library_images | full | 30 | 3,000 |
get_account_status, get_stores, get_channel_health, get_import_status, get_operation, get_order | full | 30 | 3,000 |
find_products, find_listings, get_orders | full | 10 | 500 |
generate_product_content | full | 3 | 50 |
create_channel_drafts, adjust_price, update_inventory, update_product_content, add_order_tracking | write | 10 | 300 |
create_products | write | 3 | 30 |
upload_product_images | write | 3 | 40 |
import_from_mainstore | none | 2 | 10 |
trigger_mainstore_refresh | none | 3 | 20 |
Over the limit
The API returns HTTP 429 with a Retry-After header and {"error": "quota_exceeded"}. Wait for the number of seconds in Retry-After, then retry. Some error bodies also include a retry_after value.
Refresh cooldown
trigger_mainstore_refresh has a 30-minute cooldown per store. The cooldown stays the same whatever your plan. A refresh during the cooldown returns cooldown_active.
Read your exact numbers with GET /api/mcp/rate-limits. Per-minute limits reset every 60 seconds, and per-day limits reset at 00:00 UTC.
See Every Call, Job and Import
Check what ran, when, and whether it worked, without building your own logs.
Request log
Every REST and MCP call is recorded with its time, source, tool, status and any error. Filter by token, source, status or date.
Background jobs
Poll GET /api/v1/operations/{op_id} to see whether a write job is queued, running, done, failed or sent.
Imports and sync
Use get_import_status for import progress and errors, and get_channel_health for connection and sync status.
What Teams Build on the API
Each example uses only the tools listed above.
Stock feed from your warehouse
Send counts with update_inventory in batches of up to 100. Preview each batch, apply it after review, and track the job with get_operation.
Order sync into your back office
List one day of orders with get_orders, then read each order with get_order. Buyer information is not returned, so store only what your process needs.
Shipment tracking
Save tracking numbers with add_order_tracking when parcels leave your warehouse. The tracking is pushed to the channel after it is saved.
Catalog clean-up
List products with find_products, edit names, brands and SKUs with update_product_content, and draft missing copy with generate_product_content. Content changes push to active channel listings.
Channel launch checklist
Check the channel with get_channel_health, then create drafts with create_channel_drafts. Drafts are not published, so a person reviews them first.
Price rules from your system
Send new prices with adjust_price in batches of up to 100. Each price is capped at ±50%, so one bad input cannot move a price too far at once.
Which One Should You Use?
Use the REST API when you write the code
Call the endpoints from your scripts, back office or integration. Every response is JSON, and every error has the form {"error": "...", "message": "..."}.
Use the MCP server when an AI assistant does the work
Connect Claude, ChatGPT or another AI assistant to the same 20 tools. The assistant shows you each preview before it confirms a write.
Reference and Specification
API reference
The interactive reference lists every endpoint with its request fields, response fields and error codes.
OpenAPI specification
Download the machine-readable spec to generate a client in your language, or to import into your API tool.
Frequently Asked Questions
No. The API and the MCP server share the same 20 tools and the same rate limits, which depend on the number of listings on your plan.
No. You connect your channels inside LitCommerce, so you do not need a developer account for each one.
Open API/MCP in your LitCommerce account and click Get API Token.
No. A token is bound to one store. MCP connections that are granted several stores pass store_id on each call.
Yes. Choose only read scopes, such as catalog:read and orders:read, when you create the token.
Write tools default to dry_run set to true. Nothing changes until you send a second call with dry_run set to false, the confirmation_token and an idempotency_key.
The apply returns plan_changed and changes nothing. Run the dry run again to get a new plan.
Send the same key with the same parameters. The API returns the earlier result with idempotent_replay: true and writes nothing twice.
The response returns previous_attempt_failed or outcome_unknown. Check the result with a read tool, then dry run again with a new key.
Each page holds up to 50 rows, and one browse reads up to 10 pages. Follow next_cursor to read further.
Poll get_operation or GET /api/v1/operations/{op_id}, waiting the next_check_after seconds between checks. A status of sent is not the same as done.
Read tools return them. Use find_products for product IDs, get_orders for order IDs, and get_stores to see your channels. get_order accepts either an order_id or a main_store_order_id. The API reference lists the exact response field names.
It depends on your main store type, either a shopping cart or LitCommerce. Price, stock, product creation and image tools work with LitCommerce main stores. Import and refresh tools work with cart main stores. Some tools, such as listing and order reads, work with both. Your token only sees the tools that match its store, and GET /api/v1/tools lists them.
Start Your 7-Day Free Trial and Get Your API Token
Every feature included. Cancel before the trial ends and pay nothing.