Skip to main content
LITCOMMERCE REST API

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

LitCommerce dashboard alongside the LitCommerce API logo, with connected marketplace icons for Shopify, Walmart, Amazon, eBay, Etsy, TikTok and 10 more
Get started

Get Started in Three Steps

Step 1

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.

Step 2

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 '{}'
Step 3

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"}'
First call

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 '{}'
Authentication

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 with the Connect options for Claude, LitCommerce API and ChatGPT, and the Get API Token button

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.

ScopeLets the tokenTools
catalog:readRead products, listings, stores, channel health and importsfind_products, find_listings, find_library_images, get_stores, get_account_status, get_channel_health, get_import_status, get_operation
catalog:writeCreate and edit products, prices, drafts and importscreate_products, update_product_content, adjust_price, create_channel_drafts, import_from_mainstore, trigger_mainstore_refresh, upload_product_images
inventory:writeChange stock quantitiesupdate_inventory
orders:readRead ordersget_orders, get_order
orders:writeAdd tracking to ordersadd_order_tracking
ai:creditsGenerate product content, which uses AI creditsgenerate_product_content
Endpoints

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.

EndpointTypeScopeWhat it does
get_storesReadcatalog:readShows your store and its channels, with counts per tab.
get_account_statusReadcatalog:readShows account and store status.
get_channel_healthReadcatalog:readShows a channel’s connection, sync settings, last import or refresh, and running processes.
get_import_statusReadcatalog:readShows import and sync progress for a channel. Filter by product, order, inventory, refresh or category.
get_operationReadcatalog:readShows the status of a write job: queued, running, done, failed or sent.
find_productsReadcatalog:readLists main-store products, with variants excluded. Requires status and in_stock.
find_listingsReadcatalog:readLists a channel’s listings. Requires channel_id, status and link_status.
find_library_imagesReadcatalog:readSearches your Image Library. Requires folder and a name of at least two characters.
get_ordersReadorders:readLists orders for one day or one month, newest first. Requires date or month.
get_orderReadorders:readShows one order with its lines and status. Buyer information is not returned.
create_productsWritecatalog:writeCreates up to 50 simple products in your main store. Images must come from the Image Library.
update_product_contentWritecatalog:writeEdits name, description, brand or SKU for up to 50 products. Changes push to active channel listings.
update_inventoryWriteinventory:writeSets stock quantity for up to 100 products or variants.
adjust_priceWritecatalog:writeSets new selling prices for up to 100 products or variants.
create_channel_draftsWritecatalog:writeCreates unpublished drafts on a channel for up to 50 products. Products already on the channel are skipped.
import_from_mainstoreWritecatalog:writeImports products from your main store as a background job. Adds only products not yet in LitCommerce.
trigger_mainstore_refreshWritecatalog:writeOverwrites up to 50 products with the data from the main store. Each store has a 30-minute cooldown.
add_order_trackingWriteorders:writeAdds a tracking number to an order, then pushes it to the channel.
generate_product_contentWriteai:creditsGenerates a title, description, tags and attributes from one to four images. Returns text only.
upload_product_imagesWritecatalog:writeUploads one to five images to the Image Library from public https URLs.

Helper endpoints

  • GET /api/v1/tools lists 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 the get_operation tool.
  • GET /api/v1/openapi.json returns the OpenAPI specification for generating a client.
Write safety

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.

Three-step write flow: dry run returns a plan, the user approves in chat, then apply runs. A plan_changed result sends the flow back to dry run

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"}'
RuleWhat happens
Data changed in betweenIf the data changes between preview and apply, the apply returns plan_changed. Run the dry run again.
Safe retriesThe 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 limitEach price can change by at most ±50% from the current price.
Failed midwayThe response returns previous_attempt_failed or outcome_unknown. Check with a read tool, then dry run again with a new key.
Partial failureIf some items fail in create_products, do not repeat the whole call. Fix and resend only the failed items.
No undocreate_products has no undo. Check the preview carefully before you apply.
Shipping trackingDo not call add_order_tracking again after tracking_saved_push_failed.
Draftscreate_channel_drafts creates unpublished drafts. Products already on the channel are skipped.
Common calls

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"
Errors

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 statusError codes
400invalid_confirmation_token, invalid_cursor, invalid_input
401unauthenticated
402insufficient_ai_credits
403account_unavailable, insufficient_scope, store_not_granted
404not_found, unknown_tool
409busy, 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
410confirmation_token_expired
422apply_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
428confirm_count_required, confirmation_required, idempotency_key_required
429cooldown_active, quota_exceeded, too_many_requests
500, 502, 503internal_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.

Rate limits

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 planMultiplier
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.

Bar chart of base calls per minute grouped by full, write and none scale types
ToolScale typePer minutePer day
find_library_imagesfull303,000
get_account_status, get_stores, get_channel_health, get_import_status, get_operation, get_orderfull303,000
find_products, find_listings, get_ordersfull10500
generate_product_contentfull350
create_channel_drafts, adjust_price, update_inventory, update_product_content, add_order_trackingwrite10300
create_productswrite330
upload_product_imageswrite340
import_from_mainstorenone210
trigger_mainstore_refreshnone320

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.

Monitoring

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.

Request log with filters for token, tool and status, showing a 429 quota_exceeded row
Use cases

What Teams Build on the API

Each example uses only the tools listed above.

Use case 1

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.

Use case 2

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.

Use case 3

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.

Use case 4

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.

Use case 5

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.

Use case 6

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.

REST or MCP

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.

Documentation

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.

FAQ

Frequently Asked Questions

Does the API need a separate plan?

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.

Do I need a developer account on each channel?

No. You connect your channels inside LitCommerce, so you do not need a developer account for each one.

How do I get an API token?

Open API/MCP in your LitCommerce account and click Get API Token.

Can one token work with several stores?

No. A token is bound to one store. MCP connections that are granted several stores pass store_id on each call.

Can I make a token read-only?

Yes. Choose only read scopes, such as catalog:read and orders:read, when you create the token.

Why did my write call return a plan first?

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.

What if the data changes between preview and apply?

The apply returns plan_changed and changes nothing. Run the dry run again to get a new plan.

How do I retry a write safely?

Send the same key with the same parameters. The API returns the earlier result with idempotent_replay: true and writes nothing twice.

What if the connection drops during a write?

The response returns previous_attempt_failed or outcome_unknown. Check the result with a read tool, then dry run again with a new key.

How many rows can I read at once?

Each page holds up to 50 rows, and one browse reads up to 10 pages. Follow next_cursor to read further.

How do I know when a background job is done?

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.

Where do I get product_id, order_id and channel_id?

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.

Which tools work with my store?

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.