API reference · 2026-09-29

Automate your catalog end to end.

147 endpoints for products, listings, images, generation, and marketplace offers, plus signed webhooks. The same OpenAPI 3.1 document powers this page.

Download OpenAPI 3.1 Create an API key

Base URL: https://listing.techma.io
Authentication: Bearer lp_live_…
Format: JSON over HTTPS
Standard limit: 100 requests / minute

Start here

Authentication

Workspace owners and admins create API keys in Settings → API keys. A key starts with lp_live_, is shown once, and can be revoked or rotated at any time. Send it as a bearer token on every request.

A key's scopes are clamped to what its creator can currently do, so demoting the creator immediately narrows the key. The workspace plan must include API access. Keys never work on account, billing, team, connection, or admin endpoints (/api/v1/admin, /api/v1/account, /api/v1/auth, /api/v1/billing, /api/v1/catalog, /api/v1/compliance, /api/v1/connections, /api/v1/notifications, /api/v1/team, /api/v1/tenant) or on browser pages.

Keep keys server-side. Never embed a key in a browser app, mobile app, or support message.

shell

curl 'https://listing.techma.io/api/v1/products?limit=20' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Least privilege

Scopes

Give each integration only the scopes it needs. A request without the required scope returns 403 FORBIDDEN.

Scope	Allows	Endpoints
`products:read`Catalog read	Read products, intakes, images, bulk jobs, and catalog exports.	31
`products:write`Catalog write	Create and edit products, listing content, imports, and remediation fixes.	28
`listings:read`Listings read	Read listings and approvals.	17
`listings:validate`Listing validation	Validate payloads, recalculate health, and read marketplace schemas.	8
`listings:publish`Marketplace publishing	Push listings, update offers, manage images, templates, and approvals.	37
`ai:use`Generation	Run paid AI generation, image processing, keyword research, and memory.	30
`analytics:read`Analytics	Read marketplace metrics and listing performance correlation.	5
`webhooks:receive`Webhooks	Read webhook endpoint configuration and the delivery log.	1

Paid work

Credits and quotes

Generation, image processing, keyword research, and marketplace pushes spend workspace credits. First create a quote with POST /api/v1/credit-quotes, then pass its id as quoteId. A quote is single-use, expires after 10 minutes, and shows the exact cost and your projected balance before anything is charged. Too few credits returns 402 INSUFFICIENT_CREDITS.

shell

curl -X POST 'https://listing.techma.io/api/v1/credit-quotes' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"action":"listing_push","units":1}]}'

Safe retries

Idempotency

Send an Idempotency-Key header (1–128 characters of letters, digits,., _, :, or -; a UUID is ideal) on every write. It is required on 14 endpoints that talk to a marketplace or spend credits, and recommended on the rest.

Retrying with the same key and body returns the original result instead of repeating the work, even after a timeout. Reusing a key with a different body, or while the first request is still running, returns 409 CONFLICT. Some endpoints mark replays with x-idempotency-replayed: true. When a marketplace outcome is unknown, ListingPilot reports it as unknown and never re-sends it under the same key.

Fair use

Rate limits

Each endpoint allows 100 requests per 60 seconds per client, counted separately for each path. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). Over the limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After; wait that long, then retry with exponential backoff and jitter.

Marketplace calls also respect each seller's Amazon and Flipkart quotas. When a provider budget is exhausted the request is refused with 429 and retry-after before anything is sent.

Endpoint	Limit
GET /api/v1/products/bulk-import/template	5 / 60s
POST /api/v1/products/bulk-import/preview	5 / 60s
POST /api/v1/products/bulk-import	5 / 60s
POST /api/v1/products/import	5 / 60s
POST /api/v1/images/upload	60 / 60s
POST /api/v1/images/upload-url	60 / 60s
PUT /api/v1/images/upload/file	60 / 60s
POST /api/v1/images/upload/complete	60 / 60s
POST /api/v1/marketplace-exports/templates/parse	30 / 60s
GET /api/v1/marketplace-exports/mappings	30 / 60s
PUT /api/v1/marketplace-exports/mappings	30 / 60s
POST /api/v1/marketplace-exports/mappings/suggest	30 / 60s
POST /api/v1/marketplace-exports/validate	30 / 60s
POST /api/v1/marketplace-exports/download	30 / 60s
POST /api/v1/marketplace-exports/images	30 / 60s
GET /api/v1/pricing/batches	60 / 60s
POST /api/v1/pricing/batches	60 / 60s
GET /api/v1/pricing/batches/{batchId}	60 / 60s
POST /api/v1/pricing/batches/{batchId}/items/{itemId}/check	60 / 60s
POST /api/v1/pricing/fees	30 / 60s
GET /api/v1/reports/sales/export	10 / 60s
POST /api/v1/reports/sync	6 / 60s

When things go wrong

Errors

Errors share one envelope. Branch on the HTTP status and error.code, show error.message to people, and log error.requestId (also sent as x-request-id) when you contact support.

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided listing data is invalid.",
    "details": {
      "productId": "Invalid uuid"
    },
    "requestId": "req_7c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
  }
}

Status	Meaning
400	The request is malformed or failed validation. `error.details` names each field.
401	The API key is missing, malformed, revoked, expired, or the plan has no API access.
402	The workspace does not have enough credits for this quote.
403	The key lacks a required scope, or the plan or feature does not allow this operation.
404	The resource does not exist in this workspace (or the feature is disabled).
409	A conflict: the quote expired or was used, the idempotency key was reused with a different body or is still in progress, or the record changed.
413	The request body or file is too large.
422	The request is well-formed but was refused by a marketplace or image preflight.
429	Too many requests. Wait for `Retry-After` seconds before retrying.
500	An unexpected error. Quote `error.requestId` to support.
502	The marketplace provider returned an error.
503	Temporarily unavailable (queue, credit gate, provider, or feature). Retry later with the same idempotency key.

Large catalogs

Pagination

List endpoints return data and meta. Pass meta.nextCursor back as cursor until meta.hasNextPage is false. Cursors work with the default newest-first order; for other sorts use offset instead (never both). limit is 1–100 (default 20). The images list uses page numbers: pass meta.nextCursor as page.

json

{
  "data": [
    {
      "id": "3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192",
      "sku": "KURTA-BLUE-M",
      "title": "Cotton straight kurta, blue, medium",
      "status": "active",
      "price": 499,
      "currency": "INR",
      "createdAt": "2026-09-29T10:00:00.000Z"
    }
  ],
  "meta": {
    "nextCursor": "eyJjcmVhdGVkQXQiOi…",
    "hasNextPage": true,
    "totalCount": 1248
  }
}

Events

Webhooks

Admins register up to 5 HTTPS endpoints in Settings → Webhooks and receive a whsec_ signing secret once. Payloads carry identifiers and statuses only: fetch the full record through the API after verifying the signature.

Each delivery is a POST with x-listingpilot-signature (t=<unix>,v1=<hex>), x-listingpilot-timestamp, x-listingpilot-event, and x-listingpilot-delivery. The signature is HMAC-SHA256 of <t>.<raw body>. Reject timestamps older than 5 minutes.

Respond with any 2xx within 10 seconds. Timeouts, network errors, 408, 425, 429, and 5xx are retried with exponential backoff, up to 8 attempts; other 4xx responses and redirects are final. Retries reuse the same event id, so deduplicate on it.

Event	`data` fields
`listing.published`Listing published	`listingId`, `platform`
`listing.rejected`Listing rejected	`listingId`, `platform`
`job.completed`Job completed	`jobId`, `queue`, `resourceId`, `status`
`job.failed`Job failed	`jobId`, `queue`, `resourceId`, `status`
`payment.captured`Payment captured	`paymentEventId`
`webhook.test`Test delivery	`message`

json

{
  "id": "evt_5a1f0c3e9b2d4f6a8c7e1b3d5f7a9c2e",
  "type": "listing.published",
  "createdAt": "2026-09-29T10:00:00.000Z",
  "workspaceId": "0b6f2c1e-4d3a-4e5f-8a7b-9c0d1e2f3a4b",
  "data": {
    "listingId": "3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192",
    "platform": "amazon"
  }
}

node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody must be the exact bytes received, before JSON parsing.
export function verifyListingPilotSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = header.split(',').map((part) => part.trim().split('='));
  const timestamp = Number(parts.find(([key]) => key === 't')?.[1]);
  if (!Number.isSafeInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = Buffer.from(
    createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex'),
  );
  return parts
    .filter(([key]) => key === 'v1')
    .some(([, value]) => {
      const actual = Buffer.from(value ?? '');
      return actual.length === expected.length && timingSafeEqual(actual, expected);
    });
}

python

import hashlib
import hmac
import time


def verify_listingpilot_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    pairs = [part.strip().split("=", 1) for part in header.split(",") if "=" in part]
    timestamp = next((value for key, value in pairs if key == "t"), "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return any(hmac.compare_digest(expected, value) for key, value in pairs if key == "v1")

Reference

Endpoints

Products

Canonical catalog products: the facts every listing uses.

GET/api/v1/products

List products

Archived products are excluded unless status=archived. Use cursor (newest-first only) or offset, not both.

Scope: products:read
Rate limit: 100 / 60s

Parameters (11)

Name	In	Type	Notes
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page.
`offset`	query	integer	Offset pagination, 0–1,000,000. 0–1000000
`limit`	query	integer	Page size, 1–100. 1–100; default 20
`sort`	query	newest \| oldest \| name \| last_activity	Sort order.
`status`	query	draft \| active \| archived	Product status.
`platform`	query	amazon \| flipkart	Only products with a live listing on this platform. Platform as stored on catalog records: `amazon` or `flipkart`.
`search`	query	string	Substring match on title, SKU, brand, or category. at most 255 chars
`title`	query	string	Substring match on title. at most 255 chars
`sku`	query	string	Substring match on SKU. at most 255 chars
`brand`	query	string	Substring match on brand. at most 255 chars
`category`	query	string	Substring match on category ID. at most 255 chars

Responses

200A page of products.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/products' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/products

Create a product

Scope: products:write
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`sku`required	string	3–50 chars
`title`required	string	1–500 chars
`description`	string	at most 100000 chars
`brand`	string	1–255 chars
`brandId`	uuid	—
`price`required	number	at most 99999999.99
`currency`	string	exactly 3 chars; default "INR"
`attributes`	object	default {}
`categoryId`	string	1–255 chars
`inventory`	integer	0–2147483647

Responses

201The created product.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sku":"KURTA-BLUE-M","title":"Cotton straight kurta, blue, medium","price":499}'

GET/api/v1/products/{id}

Get a product with its images and listings

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Product ID.

Responses

200The product.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PATCH/api/v1/products/{id}

Update a product

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Product ID.

Request body · application/json

Name	Type	Notes
`sku`	string	3–50 chars
`title`	string	1–500 chars
`description`	string \| null	at most 100000 chars
`brand`	string \| null	1–255 chars
`brandId`	uuid \| null	—
`price`	number \| null	at most 99999999.99
`currency`	string	exactly 3 chars
`attributes`	object	—
`categoryId`	string \| null	1–255 chars
`status`	draft \| active \| archived	—
`inventory`	integer	0–2147483647

Responses

200The updated product.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sku":"KURTA-BLUE-M"}'

DELETE/api/v1/products/{id}

Archive a product

A soft delete: the product is archived and can be restored by setting status.

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Product ID.

Responses

204Done. No response body.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X DELETE 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/products/{id}/variations

Get the variation family of a product

Returns the family (parent, theme and child products with their variation values) the product belongs to, or null.

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Product ID (parent or child).

Responses

200The variation family, or null.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/variations' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/products/{id}/variations

Create a variation family or add children

Operations: create a family on a parent with a variation theme, add existing products as children, or create a child from the parent. Themes are validated against the Amazon product type definition. Send an Idempotency-Key header to make retries safe.

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Parent product ID.

Request body · application/json

Name	Type	Notes
`operation`required	"create_family"	—
`variationTheme`required	string	1–64 chars
`name`	string	1–255 chars
`productType`	string	—

Responses

200The updated family.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/variations' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operation":"create_family","variationTheme":"example"}'

PATCH/api/v1/products/{id}/variations

Update variation values or the family name

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Parent product ID.

Request body · application/json

Name	Type	Notes
`name`	string	1–255 chars
`variationTheme`	string	1–64 chars
`productType`	string	—
`children`	array of object	at most 200 items

Responses

200The updated family.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/variations' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Launch drafts"}'

DELETE/api/v1/products/{id}/variations

Remove a child from its family, or dissolve the family

With childId, detaches that child; without it, dissolves the family. Relationships already live on Amazon are not deleted there.

Scope: products:write
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`id`required	path	uuid	Parent product ID.
`childId`	query	uuid	Child product to detach.

Responses

200The updated family, or null when dissolved.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X DELETE 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/variations' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/variation-themes

List allowed variation themes

With productType, the themes allowed by that Amazon product type definition; with platform=flipkart&categoryId=, from stored Flipkart category rules; otherwise the defaults.

Scope: products:read
Rate limit: 100 / 60s

Parameters (3)

Name	In	Type	Notes
`productType`	query	string	Amazon product type, for example SHIRT. at most 100 chars
`platform`	query	amazon_in \| flipkart	Marketplace.
`categoryId`	query	string	Flipkart category ID (with platform=flipkart). at most 255 chars

Responses

200Variation themes.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/variation-themes' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/products/bulk-archive

Archive up to 100 products

Scope: products:write
Rate limit: 100 / 60s
Plan: bulk_operations

Request body · application/json

Name	Type	Notes
`productIds`required	array of uuid	1–100 items

Responses

200Archived.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/bulk-archive' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"productIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"]}'

GET/api/v1/products/{id}/assignment

Get the team assignment for a product

Scope: products:read
Rate limit: 100 / 60s
Plan: team_approvals

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Product ID.

Responses

200The assignment and possible assignees.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/products/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/assignment' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Brands

Workspace brands: voice, phrase rules, defaults, and marketplace approval status.

GET/api/v1/brands

List brands

Active brands first, the workspace default first, then by name; each brand carries one approval status per marketplace. The first call seeds brands from the workspace settings and the catalog brand names. Creating, editing and archiving brands needs a workspace owner or admin session.

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`includeArchived`	query	true \| false	Include archived brands (default `true`); `false` for a brand picker.

Responses

200Brands.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/brands' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/brands/{id}

Get a brand

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Brand ID.

Responses

200The brand.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/brands/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Catalog import

CSV and XLSX catalog import.

GET/api/v1/products/bulk-import/template

Download a blank import template

Scope: products:write
Rate limit: 5 / 60s
Plan: bulk_operations

Parameters (2)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart \| canonical	Template columns. default "amazon_in"
`format`	query	xlsx \| csv	File format. default "xlsx"

Responses

200The template file.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/products/bulk-import/template' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/products/bulk-import/preview

Preview a CSV or XLSX import without writing

Returns the first 25 rows, the detected headers, a suggested column mapping, and SKUs that already exist.

Scope: products:write
Rate limit: 5 / 60s
Plan: bulk_operations

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	CSV or XLSX file (binary), at most 10 MB, 25,000 rows, 50 columns.
`platform`	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.; default "amazon_in"
`mapping`	string	JSON object mapping ListingPilot fields (sku, title, price, …) to header names.
`duplicateStrategy`	skip \| update_existing_draft \| new_sku	default "skip"

Responses

200The preview.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/bulk-import/preview' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -F 'file=@./upload-file'

POST/api/v1/products/bulk-import

Import products from CSV or XLSX

Creates draft products and queues a catalog-import job. Reusing an Idempotency-Key with a different file returns 409.

Scope: products:write
Rate limit: 5 / 60s
Plan: bulk_operations
Idempotency-Key: Recommended

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	CSV or XLSX file (binary), at most 10 MB, 25,000 rows, 50 columns.
`platform`	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.; default "amazon_in"
`mapping`	string	JSON object mapping ListingPilot fields (sku, title, price, …) to header names.
`duplicateStrategy`	skip \| update_existing_draft \| new_sku	default "skip"

Responses

200Nothing new to create.
202Import accepted; the job finishes asynchronously.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/bulk-import' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'file=@./upload-file'

POST/api/v1/products/importAlias

Import products (alias)

Alias of POST /api/v1/products/bulk-import. Prefer the canonical path.

Scope: products:write
Rate limit: 5 / 60s
Plan: bulk_operations
Idempotency-Key: Recommended

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	CSV or XLSX file (binary), at most 10 MB, 25,000 rows, 50 columns.
`platform`	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.; default "amazon_in"
`mapping`	string	JSON object mapping ListingPilot fields (sku, title, price, …) to header names.
`duplicateStrategy`	skip \| update_existing_draft \| new_sku	default "skip"

Responses

200Nothing new to create.
202Import accepted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/import' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'file=@./upload-file'

Product intakes

Guided product creation from details or a photo.

POST/api/v1/product-intakes

Create a product intake draft

Use mode: detailed for a typed draft or mode: image_only with an owned image. Reference URLs use POST /api/v1/reference-sources/analyze.

Scope: products:write
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`mode`required	"detailed"	—
`platform`required	amazon_in \| flipkart	—
`productName`	string	at most 500 chars
`sku`	string	at most 50 chars
`brand`	string	at most 255 chars
`category`	string	at most 255 chars
`price`	number	at most 99999999.99
`inventory`	integer	0–2147483647
`keyFeatures`	string	at most 5000 chars
`additionalInstructions`	string	at most 10000 chars
`selectedPlatforms`	object	—

Responses

201The intake.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/product-intakes' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"detailed","platform":"amazon_in"}'

POST/api/v1/product-intakes/image-upload

Start an image-first intake

Stages a seller-owned photo. No credits are used until analysis.

Scope: ai:use
Rate limit: 100 / 60s

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	JPEG, PNG, or WebP image (binary), at most 10 MB.
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`productName`	string	at most 500 chars
`brand`	string	at most 255 chars
`category`	string	at most 255 chars
`ownedImageConfirmed`required	"true"	Confirms the seller owns the image.

Responses

201The image-first intake.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/product-intakes/image-upload' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -F 'file=@./upload-file' \
  -F 'platform=amazon_in' \
  -F 'ownedImageConfirmed=true'

GET/api/v1/product-intakes/{id}

Get a product intake

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Intake ID.

Responses

200The intake record.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/product-intakes/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PATCH/api/v1/product-intakes/{id}

Save a detailed intake draft

Only the member (or API key creator) who created the draft can update it.

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Intake ID.

Request body · application/json

Name	Type	Notes
`mode`required	"detailed"	—
`platform`required	amazon_in \| flipkart	—
`productName`	string	at most 500 chars
`sku`	string	at most 50 chars
`brand`	string	at most 255 chars
`category`	string	at most 255 chars
`price`	number	at most 99999999.99
`inventory`	integer	0–2147483647
`keyFeatures`	string	at most 5000 chars
`additionalInstructions`	string	at most 10000 chars
`selectedPlatforms`	object	—

Responses

200Saved.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/product-intakes/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"detailed","platform":"amazon_in"}'

POST/api/v1/product-intakes/{id}/generate

Analyze an image-first intake

Scope: ai:use
Rate limit: 100 / 60s
Idempotency-Key: Recommended
Credits: Quote action content_generation, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (1 unit, textAction image_intake). GET /api/v1/ai/text-pricing lists the current prices.

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Intake ID.

Request body · application/json

Name	Type	Notes
`quoteId`	uuid	—

Responses

202Analysis accepted; poll the job.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/product-intakes/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/generate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/product-intakes/{id}/convert

Convert an intake into a product

Scope: listings:publish
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Intake ID.

Request body · application/json

Name	Type	Notes
`sku`required	string	3–50 chars
`title`	string	1–500 chars
`brand`	string \| null	1–255 chars
`category`required	string	1–255 chars
`price`required	number	at most 99999999.99
`inventory`required	integer	0–2147483647

Responses

201The new product.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/product-intakes/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/convert' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sku":"KURTA-BLUE-M","category":"apparel","price":499,"inventory":1}'

POST/api/v1/reference-sources/analyze

Analyze a marketplace reference URL

Extracts factual signals from a supported marketplace page into an intake. Generated content stays original.

Scope: ai:use
Rate limit: 100 / 60s
Plan: reference_analysis
Idempotency-Key: Required
Credits: Quote action reference_analysis: 1 credit per unit (1 unit).

Request body · application/json

Name	Type	Notes
`mode`required	detailed \| image_only \| reference_url	—
`productName`	string	at most 500 chars
`sku`	string	3–50 chars
`brand`	string	at most 255 chars
`category`	string	at most 255 chars
`platform`required	amazon_in \| flipkart	—
`referenceUrl`	uri	at most 2048 chars
`imageId`	uuid	—
`imageUrl`	uri	at most 2048 chars
`ownedImageConfirmed`	boolean	—
`referenceNotes`	string	at most 10000 chars
`hints`	string	at most 10000 chars
`quoteId`	uuid	—

Responses

200Replay of a completed request.
201The analyzed intake.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/reference-sources/analyze' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"detailed","platform":"amazon_in"}'

Listings

Marketplace listings, versions, approvals, and pushes.

GET/api/v1/listings

List listings

Use cursor (newest-first only) or offset, not both. productIds is comma-separated.

Scope: listings:read
Rate limit: 100 / 60s

Parameters (16)

Name	In	Type	Notes
`cursor`	query	string	Filter or pagination parameter `cursor`. at least 1 chars
`offset`	query	integer	Filter or pagination parameter `offset`. 0–1000000
`limit`	query	integer	Filter or pagination parameter `limit`. 1–100; default 20
`platform`	query	amazon_in \| flipkart	Filter or pagination parameter `platform`.
`status`	query	pending \| synced \| error	Filter or pagination parameter `status`.
`listingStatus`	query	live \| draft \| processing \| attention	Filter or pagination parameter `listingStatus`.
`q`	query	string	Filter or pagination parameter `q`. 1–200 chars
`brand`	query	string	Filter or pagination parameter `brand`. 1–255 chars
`category`	query	string	Filter or pagination parameter `category`. 1–255 chars
`completeness`	query	complete \| incomplete	Filter or pagination parameter `completeness`.
`health`	query	healthy \| attention \| unscored	Filter or pagination parameter `health`.
`reviewSeverity`	query	high \| medium \| low	Filter or pagination parameter `reviewSeverity`.
`imageCompliance`	query	ready \| attention \| missing	Filter or pagination parameter `imageCompliance`.
`sort`	query	newest \| oldest \| name \| last_activity	Filter or pagination parameter `sort`.
`productIds`	query	string	Comma-separated product IDs (1–100).
`product`	query	uuid	A single product ID.

Responses

200A page of listings.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/listings/{id}

Get a listing

Scope: listings:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

200The listing.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PATCH/api/v1/listings/{id}

Edit listing content

Saves a new listing version. A live, rejected, or inactive listing moves to correcting until it is pushed again.

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Request body · application/json

Name	Type	Notes
`title`required	string	at most 500 chars
`description`required	string	at most 100000 chars
`bullets`required	array of string	at most 10 items
`searchTerms`required	array of string	at most 50 items
`itemHighlight`	string	Amazon item highlights (Listings API title_differentiation), comma-separated phrases that do not repeat the title; an empty string clears it. Sent only with a title of 75 characters or fewer and when the product type offers it.; at most 125 chars
`expectedVersion`	integer	Optimistic concurrency guard: the version you edited.; at least 0
`changeSummary`	string	at most 500 chars

Responses

200The saved version.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Cotton straight kurta, blue, medium","description":"example","bullets":["example"],"searchTerms":["example"]}'

GET/api/v1/listings/{id}/versions

List versions and compare two

Scope: listings:read
Rate limit: 100 / 60s

Parameters (3)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.
`from`	query	uuid	Older version ID (default: second newest).
`to`	query	uuid	Newer version ID (default: newest).

Responses

200Versions and the comparison.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/versions' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/listings/{id}/versions/{versionId}/restore

Restore an earlier version

Scope: products:write
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.
`versionId`required	path	uuid	Version to restore.

Responses

200Restored as a new version.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/versions/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/restore' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/listings/validate

Validate a listing payload before publishing

Failures are returned in the 200 body (isValid: false). Amazon validation also runs the SP-API validation preview when a connection is active.

Scope: listings:validate
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`required	amazon_in \| flipkart	—
`payload`required	object	—

Responses

200The validation result.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/validate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","platform":"amazon_in","payload":{}}'

POST/api/v1/listings/push

Push one product to a marketplace

Queues a marketplace push. A listing is live only after the marketplace confirms it; watch the listing.published webhook.

Scope: listings:publish
Rate limit: 100 / 60s
Plan: marketplace_publish
Idempotency-Key: Required
Credits: Quote action listing_push: 2 credits per unit (1 unit).

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`marketplaceConnectionId`	uuid	—
`payload`	object	Required for `amazon_in`: the reviewed SP-API listing payload.
`quoteId`	uuid	Required. Quote action `listing_push`, 1 unit.

Responses

202Push queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/push' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","platform":"amazon_in"}'

POST/api/v1/listings/bulk-push

Push many products to a marketplace

Amazon sends one listings feed; Flipkart queues one job per product.

Scope: listings:publish
Rate limit: 100 / 60s
Plan: marketplace_publish
Idempotency-Key: Required
Credits: Quote action listing_push: 2 credits per unit (1 unit per product).

Request body · application/json

Name	Type	Notes
`productIds`required	array of uuid	1–25000 items
`platform`required	amazon_in \| flipkart	—
`quoteId`	uuid	—

Responses

202Push queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/bulk-push' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"],"platform":"amazon_in"}'

POST/api/v1/listings/{id}/retry

Retry a draft, rejected, or stalled push

Scope: listings:publish
Rate limit: 100 / 60s
Plan: marketplace_publish
Credits: Quote action listing_push: 2 credits per unit (1 unit).

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Request body · application/json

Name	Type	Notes
`quoteId`required	uuid	—

Responses

202Retry queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/retry' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/listings/{id}/offer

Update Amazon price or stock

Synchronous and free. A 422 response carries the marketplace issues in data.issues.

Scope: listings:publish
Rate limit: 100 / 60s
Plan: marketplace_publish
Idempotency-Key: Required

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID (Amazon, live or recently rejected).

Request body · application/json

Name	Type	Notes
`price`	number	Selling price in INR.; at most 10000000
`quantity`	integer	0–2000000000

Responses

200Accepted by Amazon.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/offer' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"price":499}'

GET/api/v1/listings/{id}/health

Get the latest health snapshot

Scope: listings:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

200The latest snapshot, or null.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/health' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/listings/{id}/health

Recalculate listing health

Scope: listings:validate
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

200The new snapshot.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/health' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/listings/{id}/approval

List approval requests

Scope: listings:read
Rate limit: 100 / 60s
Plan: team_approvals

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

200Approval requests, newest first.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/approval' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/listings/{id}/approval

Request a team review

Approving or rejecting requires a workspace admin in the browser.

Scope: listings:publish
Rate limit: 100 / 60s
Plan: team_approvals

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Request body · application/json

Name	Type	Notes
`reviewerId`	uuid \| null	—
`requestComment`	string \| null	at most 4000 chars

Responses

201The approval request.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/approval' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reviewerId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

GET/api/v1/listings/{id}/aplus

Get the A+ content draft

The saved A+ (Enhanced Brand Content) draft of an Amazon listing, its validation issues, the product images that can be used, and whether SP-API publishing is enabled.

Scope: listings:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

200The A+ state.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/aplus' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PUT/api/v1/listings/{id}/aplus

Save the A+ content draft

Saves seller edits. expectedRevision must be the revision you read; a newer save returns 409.

Scope: products:write
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Request body · application/json

Name	Type	Notes
`expectedRevision`required	integer	at least 0
`draft`required	object	—

Responses

200The saved A+ state.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PUT 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/aplus' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision":1,"draft":{"name":"Launch drafts","modules":[{"id":"example","moduleType":"STANDARD_HEADER_IMAGE_TEXT"}]}}'

POST/api/v1/listings/{id}/aplus/validate

Validate an A+ draft

Checks Amazon's documented module limits, image sizes and types, ASINs, and marketplace claim rules (English, Hindi and Hinglish). No provider call.

Scope: listings:validate
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Request body · application/json

Name	Type	Notes
`draft`required	object	—

Responses

200Validation result.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/aplus/validate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"draft":{"name":"Launch drafts","modules":[{"id":"example","moduleType":"STANDARD_HEADER_IMAGE_TEXT"}]}}'

GET/api/v1/listings/{id}/aplus/export

Export the A+ draft

Download the saved draft as text to paste into Seller Central's A+ Content Manager, or as JSON. Available whether or not publishing is enabled.

Scope: listings:read
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.
`format`	query	text \| json	`text` (default) or `json`. default "text"

Responses

200The A+ draft.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/aplus/export' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/listings/{id}/aplus/publish

Publish A+ content to Amazon

Queues a durable SP-API publish of the saved draft revision (upload images, validate, create the content document, relate ASINs, submit for approval). When the listing already has an Amazon A+ document on the same seller connection, the revision updates that document (updateContentDocument), re-relates its ASINs and resubmits it instead of creating a new one (mode is update). A create or update Amazon does not acknowledge is confirmed from Amazon records before anything else is sent. Requires Brand Registry on the seller account. The Amazon review status is then read at most once an hour and shown as approved or rejected (with reasons) in the draft state. Returns 403 until the amazon_aplus_publish feature is enabled; the same revision always maps to the same job.

Scope: listings:publish
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

202Publish accepted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/aplus/publish' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Remediation

Deterministic fixes for listings a marketplace rejected.

POST/api/v1/listings/remediation/preview

Preview a safe fix

A dry run with before/after content and the credit estimate. Nothing changes.

Scope: products:write
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`listingIds`required	array of uuid	1–50 items
`fix`required	normalize_title \| deduplicate_bullets \| shorten_title	—

Responses

200The preview.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/remediation/preview' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"listingIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"],"fix":"normalize_title"}'

POST/api/v1/listings/remediation/apply

Apply a safe fix to up to 50 listings

Replays return the first response with x-idempotency-replayed: true.

Scope: products:write
Rate limit: 100 / 60s
Idempotency-Key: Required
Credits: Quote action remediation_batch_fix: 1 credit per unit (1 unit per changed listing).

Request body · application/json

Name	Type	Notes
`listingIds`required	array of uuid	1–50 items
`fix`required	normalize_title \| deduplicate_bullets \| shorten_title	—
`quoteId`required	uuid	—

Responses

200Nothing would change.
202Fix queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/remediation/apply' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"listingIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"],"fix":"normalize_title","quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

GET/api/v1/listings/remediation/jobs/{id}

Get remediation batch progress

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Remediation job ID.

Responses

200Progress.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/remediation/jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/listings/remediation/jobs/{id}/cancel

Cancel pending fixes and refund them

Scope: products:write
Rate limit: 100 / 60s
Idempotency-Key: Required

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Remediation job ID.

Responses

202Cancellation recorded.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/remediation/jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/cancel' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Generation

Paid AI listing generation (durable, asynchronous jobs).

POST/api/v1/listings/{id}/aplus/generate

Generate A+ module text

Accepted as a durable job and charged like one content generation. The job saves the generated modules on the listing; a seller edit made in the meantime is kept and the new text is offered instead.

Scope: ai:use
Rate limit: 100 / 60s
Idempotency-Key: Recommended
Credits: Quote action content_generation, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (1 unit, textAction aplus_draft). GET /api/v1/ai/text-pricing lists the current prices.

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Request body · application/json

Name	Type	Notes
`quoteId`required	uuid	—
`language`	en \| hi \| hinglish	default "en"
`modules`	array of STANDARD_HEADER_IMAGE_TEXT \| STANDARD_SINGLE_SIDE_IMAGE \| STANDARD_THREE_IMAGE_TEXT \| STANDARD_FOUR_IMAGE_TEXT \| STANDARD_TEXT \| STANDARD_PRODUCT_DESCRIPTION \| …	1–7 items; default ["STANDARD_HEADER_IMAGE_TEXT","STANDARD_THREE_IMAGE_TEXT","STANDARD_TEXT","STANDARD_TECH_SPECS"]
`guidelines`	string	at most 10000 chars

Responses

202Generation accepted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/aplus/generate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/listings/generate

Generate listing content (1–4 variants)

Accepted as a durable job. Without an Idempotency-Key the quote ID identifies the request.

Scope: ai:use
Rate limit: 100 / 60s
Idempotency-Key: Recommended
Credits: Quote action content_generation, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (1 unit per variant, textAction listing_generation (1) or listing_variants (2-4)). GET /api/v1/ai/text-pricing lists the current prices.

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`required	amazon_in \| flipkart	—
`language`	en \| hi \| hinglish	—
`guidelines`	string	1–10000 chars
`templateId`	uuid	—
`quoteId`	uuid	—
`variantCount`	integer	1–4
`variantFocus`	balanced \| keyword_coverage \| benefit_led \| concise	—

Responses

202Generation accepted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/listings/generate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","platform":"amazon_in"}'

POST/api/v1/ai/generate

Generate content for one marketplace

Scope: ai:use
Rate limit: 100 / 60s
Idempotency-Key: Recommended
Credits: Quote action content_generation, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (1 unit, textAction listing_generation or listing_rewrite). GET /api/v1/ai/text-pricing lists the current prices.

Request body · application/json

Name	Type	Notes
`productId`required	string	1–255 chars
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`templateId`	uuid	—
`language`	en \| hi \| hinglish	default "en"
`guidelines`	string	at most 10000 chars
`sellerPreferences`	string	at most 6000 chars
`ragExamples`	array of string	at most 5 items
`maxRefinements`	integer	0–2
`quoteId`	uuid	Required. Create it with POST /api/v1/credit-quotes.

Responses

202Generation accepted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/ai/generate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"example","platform":"amazon_in"}'

POST/api/v1/ai/generate/batch

Generate content for Amazon and Flipkart together

Scope: ai:use
Rate limit: 100 / 60s
Idempotency-Key: Recommended
Credits: Quote action content_generation, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (2 units, textAction wizard_marketplaces). GET /api/v1/ai/text-pricing lists the current prices.

Request body · application/json

Name	Type	Notes
`productId`required	string	1–255 chars
`platforms`required	array of amazon_in \| flipkart	exactly 2 items
`templateIds`	object	—
`language`	en \| hi \| hinglish	default "en"
`guidelines`	string	at most 10000 chars
`sellerPreferences`	string	at most 6000 chars
`ragExamples`	array of string	at most 5 items
`maxRefinements`	integer	0–2
`quoteId`	uuid	Required. Create it with POST /api/v1/credit-quotes.

Responses

202Generation accepted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/ai/generate/batch' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"example","platforms":["amazon_in"]}'

GET/api/v1/ai/generate/jobs/{id}

Get a generation job

Scope: ai:use
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Job ID from the accepted response.

Responses

200The job.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/ai/generate/jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/ai/text-pricing

Listing text prices

Credits one unit of each listing-text action costs now, priced from its estimated AI cost (at least 1). Pass textAction (and productId for product actions) on the content_generation, keyword_research or bulk_generate credit-quote line to be quoted this price; a submission whose quote was priced at older rates is refused with 409. With productId, product actions are priced for that product's photos; without it, with the photo reading.

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`productId`	query	uuid	Price product actions for this product.

Responses

200Current prices.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/ai/text-pricing' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

AI memory

Workspace writing preferences the AI learns and reuses.

GET/api/v1/ai/memory

Search workspace memories

Scope: ai:use
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`limit`	query	integer	Page size, 1–100. 1–100; default 20
`q`	query	string	Search text.

Responses

200Matching memories.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/ai/memory' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/ai/memory

Add seller feedback as a memory

Provide feedbackText, explicitInstruction, or both originalText and editedText.

Scope: ai:use
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`feedbackText`	string	1–8000 chars
`explicitInstruction`	string	1–4000 chars
`originalText`	string	at most 4000 chars
`editedText`	string	at most 4000 chars

Responses

201Stored.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/ai/memory' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"feedbackText":"example"}'

GET/api/v1/ai/memory/{id}

List workspace memories

Scope: ai:use
Rate limit: 100 / 60s

Parameters (3)

Name	In	Type	Notes
`id`required	path	uuid	Your workspace ID (the tenant ID).
`limit`	query	integer	Page size, 1–100. 1–100; default 20
`q`	query	string	Search text.

Responses

200Memories.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/ai/memory/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PATCH/api/v1/ai/memory/{id}

Replace a memory

Scope: ai:use
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Memory ID.

Request body · application/json

Name	Type	Notes
`feedbackText`required	string	1–8000 chars

Responses

200Updated.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/ai/memory/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"feedbackText":"example"}'

DELETE/api/v1/ai/memory/{id}

Delete a memory

Scope: ai:use
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Memory ID.

Responses

200Deleted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X DELETE 'https://listing.techma.io/api/v1/ai/memory/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/ai/memory/learn

Learn preferences from an edited draft

Scope: ai:use + products:write
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`source`required	"wizard"	—
`productId`required	uuid	—
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`generated`required	object	—
`edited`required	object	—

Responses

200Nothing new was learned.
201New memories stored.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/ai/memory/learn' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"source":"wizard","productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","platform":"amazon_in","generated":{"title":"Cotton straight kurta, blue, medium","bullets":["example"],"description":"example"},"edited":{"title":"Cotton straight kurta, blue, medium","bullets":["example"],"description":"example"}}'

GET/api/v1/ai/rag/health

Get catalog embedding health

Scope: ai:use
Rate limit: 100 / 60s

Responses

200Embedding consistency and coverage.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/ai/rag/health' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Keywords

Keyword research, AI suggestions, and search terms.

GET/api/v1/keywords

Read stored keyword research

With productId the response is one result; otherwise a list.

Scope: products:read
Rate limit: 100 / 60s
Plan: keyword_intelligence

Parameters (3)

Name	In	Type	Notes
`productId`	query	uuid	Product ID.
`platform`	query	amazon_in \| flipkart	Marketplace. Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`limit`	query	integer	Page size, 1–100. 1–100; default 50

Responses

200Keyword research.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/keywords' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/keywords

Run keyword research for a product

Scope: ai:use
Rate limit: 100 / 60s
Plan: keyword_intelligence
Idempotency-Key: Required
Credits: Quote action keyword_research: 1 credit per unit (1 unit).

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`quoteId`required	uuid	—

Responses

200Replay of a completed request.
201The research.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/keywords' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/keywords/researchAlias

Run keyword research (alias)

Alias of POST /api/v1/keywords. Prefer the canonical path.

Scope: ai:use
Rate limit: 100 / 60s
Plan: keyword_intelligence
Idempotency-Key: Required
Credits: Quote action keyword_research: 1 credit per unit (1 unit).

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`quoteId`required	uuid	—

Responses

201The research.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/keywords/research' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/keywords/expand

Suggest related and long-tail keywords

AI suggestions only; there is no search-volume data.

Scope: ai:use
Rate limit: 100 / 60s
Plan: keyword_intelligence
Idempotency-Key: Required
Credits: Quote action keyword_research, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (1 unit, textAction keyword_ideas). GET /api/v1/ai/text-pricing lists the current prices.

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`languages`	array of en \| hi \| hinglish	1–3 items; default ["en"]
`quoteId`required	uuid	—

Responses

200Replay of a completed request.
201Suggestions.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/keywords/expand' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","platform":"amazon_in","quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/keywords/search-terms

Add a reviewed keyword to a listing

Scope: products:write
Rate limit: 100 / 60s
Plan: keyword_intelligence

Request body · application/json

Name	Type	Notes
`productId`required	uuid	—
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`term`required	string	2–120 chars
`expectedVersion`	integer	at least 0

Responses

200The listing search terms.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/keywords/search-terms' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","platform":"amazon_in","term":"cotton kurta for women"}'

Images

Upload, process, version, and export product images.

GET/api/v1/images

List product images

Page-number pagination: pass meta.nextCursor back as page.

Scope: products:read
Rate limit: 100 / 60s

Parameters (9)

Name	In	Type	Notes
`productId`	query	uuid	Product ID.
`limit`	query	integer	Page size, 1–100. 1–100; default 50
`page`	query	integer	Page number, 1–10,000. 1–10000; default 1
`status`	query	uploaded \| processing \| processed \| failed	Image status.
`type`	query	main \| lifestyle \| infographic \| swatch	Image type.
`operation`	query	process \| generate_lifestyle	Processing kind.
`marketplace`	query	amazon_in \| flipkart	Products listed on this marketplace. Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`createdFrom`	query	date	UTC day, YYYY-MM-DD.
`createdTo`	query	date	UTC day, YYYY-MM-DD.

Responses

200A page of images.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/images/pricing

Image quality tiers and prices

Quality tiers available for paid image edits and the credits one edit costs at each. Each tier says whether the caller's plan includes it; a tier outside the plan is answered with 403 PLAN_UPGRADE_REQUIRED (details.requiredPlan) by the quote and every image route. Pass qualityTier to the credit quote and to image processing, lifestyle generation and CSV generation; omitted means defaultTier, the admin default or, when the plan does not include it, the best tier the plan allows.

Scope: products:read
Rate limit: 100 / 60s

Responses

200Available tiers.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images/pricing' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/images/upload

Upload an image (single request)

Scope: listings:publish
Rate limit: 60 / 60s

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	JPEG, PNG, or WebP image (binary), at most 10 MB and 25 MP.
`productId`required	uuid	—
`type`	main \| lifestyle \| infographic \| swatch	default "main"
`bulkJobId`	uuid	Bulk intake batch; send together with bulkChildId.
`bulkChildId`	uuid	—

Responses

201Uploaded.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/upload' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -F 'file=@./upload-file' \
  -F 'productId=3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192'

POST/api/v1/images/upload-url

Start a direct upload

Step 1 of 3: create an intent, PUT the bytes to uploadUrl, then call POST /api/v1/images/upload/complete. Intents expire after 15 minutes.

Scope: listings:publish
Rate limit: 60 / 60s

Request body · application/json

Name	Type	Notes
`productId`required	string	1–100 chars
`filename`required	string	1–160 chars
`type`required	main \| lifestyle \| infographic \| swatch	—
`mimeType`required	image/jpeg \| image/png \| image/webp	—
`fileSizeBytes`required	integer	at most 10485760
`width`required	integer	500–50000
`height`required	integer	500–50000

Responses

201The upload intent.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/upload-url' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"example","filename":"example","type":"main","mimeType":"image/jpeg","fileSizeBytes":1,"width":500,"height":500}'

PUT/api/v1/images/upload/file

Send the bytes for a direct upload

Step 2 of 3. Content-Type must equal the declared MIME type. Each intent can be used once.

Scope: listings:publish
Rate limit: 60 / 60s

Parameters (1)

Name	In	Type	Notes
`token`required	query	string	Token from the `uploadUrl`. at least 1 chars

Request body · image/jpeg, image/png, or image/webp

Name	Type	Notes
`(body)`required	file	Raw JPEG, PNG, or WebP bytes.

Responses

204Done. No response body.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PUT 'https://listing.techma.io/api/v1/images/upload/file?token=example' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: image/jpeg' \
  --data-binary '@./photo.jpg'

POST/api/v1/images/upload/complete

Finish a direct upload

Step 3 of 3: verifies the stored object and creates the image record.

Scope: listings:publish
Rate limit: 60 / 60s

Request body · application/json

Name	Type	Notes
`productId`required	string	1–100 chars
`filename`required	string	1–160 chars
`type`required	main \| lifestyle \| infographic \| swatch	—
`mimeType`required	image/jpeg \| image/png \| image/webp	—
`fileSizeBytes`required	integer	at most 10485760
`width`required	integer	500–50000
`height`required	integer	500–50000
`imageId`required	uuid	—
`objectKey`required	string	1–512 chars

Responses

201Uploaded.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/upload/complete' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"productId":"example","filename":"example","type":"main","mimeType":"image/jpeg","fileSizeBytes":1,"width":500,"height":500,"imageId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","objectKey":"example"}'

POST/api/v1/images/{id}/process

Process an image

Background removal, upscale, and cleanup are metered; formatting operations are free and need no quote.

Scope: ai:use
Rate limit: 100 / 60s
Plan: advanced_image_studio
Idempotency-Key: Recommended
Credits: Metered image operations (remove_background 1, upscale 1, cleanup 1 credit each, per image); formatting operations are free.

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Image ID.

Request body · application/json

Name	Type	Notes
`operations`required	array of remove_background \| white_background \| crop \| resize_2000x2000 \| upscale \| cleanup \| …	1–8 items
`quoteId`	uuid	—
`qualityTier`	low \| high \| premium	—

Responses

202Processing queued; poll the job.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/process' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"operations":["remove_background"]}'

POST/api/v1/images/bulk-process

Process up to 50 images

Scope: ai:use
Rate limit: 100 / 60s
Plan: bulk_operations, advanced_image_studio
Idempotency-Key: Recommended
Credits: Metered image operations (remove_background 1, upscale 1, cleanup 1 credit each, per image); formatting operations are free.

Request body · application/json

Name	Type	Notes
`operations`required	array of remove_background \| white_background \| crop \| resize_2000x2000 \| upscale \| cleanup \| …	1–8 items
`quoteId`	uuid	—
`qualityTier`	low \| high \| premium	—
`imageIds`required	array of uuid	1–50 items
`speed`	standard \| economy	`economy` sends each image through the OpenAI Batch API: fewer credits, results within 24 hours per AI step (each paid edit is one step, so two edits take up to 48 hours). Allowed only while the admin offers it and when each image has one to three paid edits (otherwise 400); the quote must be priced at the same speed (otherwise 409). Economy jobs wait for the next batch instead of the image queue and can be cancelled until they join one.; default "standard"

Responses

202Jobs queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/bulk-process' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"operations":["remove_background"],"imageIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"]}'

POST/api/v1/images/{id}/generate-lifestyle

Generate lifestyle images (1–4 variants)

Scope: ai:use
Rate limit: 100 / 60s
Plan: advanced_image_studio
Idempotency-Key: Recommended
Credits: Quote action lifestyle_generation: 3 credits per unit (1 unit per variant).

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Source image ID.

Request body · application/json

Name	Type	Notes
`prompt`required	string	1–2000 chars
`negativePrompt`	string	1–1000 chars
`seed`	integer	at least 0
`variantCount`	integer	1–4; default 1
`quoteId`	uuid	—
`qualityTier`	low \| high \| premium	—

Responses

202Generation queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/generate-lifestyle' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Model wearing the kurta in a sunlit courtyard"}'

GET/api/v1/images/jobs/{jobId}

Get an image job

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`jobId`required	path	uuid	Image job ID.

Responses

200The job.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images/jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/images/jobs/{jobId}/cancel

Cancel a waiting economy image job

Cancels an economy job that is still waiting for its batch (economy.cancellable on the job) and releases its credits. A job that already joined a batch, or finished, answers 409.

Scope: ai:use
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`jobId`required	path	uuid	Image job ID.

Responses

200Cancelled.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/cancel' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/images/{id}/versions

List output versions of an image

Scope: ai:use
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Image ID.

Responses

200Versions, newest first.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/versions' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/images/{id}/versions/{versionId}/approve

Approve an output version for marketplace use

Scope: listings:publish
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`id`required	path	uuid	Image ID.
`versionId`required	path	uuid	Version ID.

Responses

200The approved version.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/versions/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/approve' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/images/{id}/preview

Preview an image through ListingPilot

Scope: products:read
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`id`required	path	uuid	Image ID.
`variant`	query	original \| processed \| thumbnail	Which rendition. default "original"

Responses

200The image bytes.
307Redirect to the private object URL.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/preview' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/images/file/{objectKey}

Download a private stored image

The object key may contain /; send each segment URL-encoded.

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`objectKey`required	path	string	Object key within your workspace storage. 1–255 chars

Responses

200The image bytes.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images/file/tenant_WORKSPACE_ID/raw/IMAGE_ID_photo.jpg' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/images/pack

Download approved images as a ZIP

Scope: products:read
Rate limit: 100 / 60s
Plan: advanced_image_studio

Parameters (2)

Name	In	Type	Notes
`marketplace`required	query	amazon_in \| flipkart	Marketplace naming rules. Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`imageIds`	query	string	Comma-separated image IDs (1–50).

Responses

200ZIP with MANIFEST.csv and README.txt.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/images/pack?marketplace=amazon_in' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

DELETE/api/v1/images/{id}

Delete an image (restorable for 30 days)

Scope: listings:publish
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Image ID.

Responses

200Deleted.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X DELETE 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/images/{id}/restore

Restore a deleted image

Scope: listings:publish
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Image ID.

Responses

200Restored.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/images/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/restore' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Bulk generation

Generate content for many products at once.

POST/api/v1/products/bulk-generate

Generate content for up to 25,000 products

Quote it with context.bulkGeneration so the server counts content and image units.

Scope: ai:use
Rate limit: 100 / 60s
Plan: bulk_operations
Credits: Quote action bulk_generate, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (server-counted units). GET /api/v1/ai/text-pricing lists the current prices.

Request body · application/json

Name	Type	Notes
`productIds`required	array of uuid	1–25000 items
`platform`required	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`language`	en \| hi \| hinglish	default "en"
`processImages`	boolean	default true
`qualityTier`	low \| high \| premium	—
`speed`	standard \| economy	`economy` batches the product photos through the OpenAI Batch API: fewer credits, results within 24 hours. Needs photo processing, the admin switch, and a quote priced at the same speed (otherwise 409).; default "standard"
`quoteId`	uuid	Required outside demo workspaces.

Responses

202Batch queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/bulk-generate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"productIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"],"platform":"amazon_in"}'

GET/api/v1/products/bulk-generate/{jobId}

Get bulk generation progress

Scope: products:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`jobId`required	path	uuid	Bulk job ID.

Responses

200Progress.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/products/bulk-generate/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/bulk-jobs

List bulk generation jobs

Scope: products:read
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`limit`	query	integer	Page size, 1–50. 1–50; default 20

Responses

200Recent jobs.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/bulk-jobs' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/bulk-jobs/{id}

Get a bulk generation job

Scope: products:read
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Bulk job ID.

Responses

200Progress.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/bulk-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/bulk-jobs/{id}/export

Download bulk generation results as CSV

Scope: products:read
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Bulk job ID.

Responses

200CSV, at most 1,000 products.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/bulk-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/export' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/bulk-jobs/{id}/retry

Retry failed units

Quote it with context.bulkGenerationRetry.

Scope: ai:use
Rate limit: 100 / 60s
Plan: bulk_operations
Idempotency-Key: Recommended
Credits: Quote action bulk_generate, priced per unit from the estimated AI cost of its listing-text action, at least 1 credit (retryable units). GET /api/v1/ai/text-pricing lists the current prices.

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Bulk job ID.

Request body · application/json

Name	Type	Notes
`quoteId`required	uuid	—
`productIds`	array of uuid	1–25000 items

Responses

202Retry queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/bulk-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/retry' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/bulk-jobs/{id}/cancel

Cancel a bulk generation job

Unstarted units are refunded; large refunds finish in the background.

Scope: ai:use
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Bulk job ID.

Responses

200Cancelled.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/bulk-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/cancel' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/products/bulk-image-match

Match one photo against candidate products

The image is analyzed and discarded; it is never stored.

Scope: ai:use
Rate limit: 100 / 60s
Plan: bulk_operations
Idempotency-Key: Required
Credits: Quote action bulk_image_match: 1 credit per unit (1 unit).

Request body · application/json

Name	Type	Notes
`imageBase64`required	string	Base64-encoded image, at most 10 MB decoded.; at least 1 chars
`mimeType`required	image/jpeg \| image/png \| image/webp	—
`productIds`required	array of uuid	1–100 items
`quoteId`required	uuid	—

Responses

200Ranked matches.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/products/bulk-image-match' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"imageBase64":"example","mimeType":"image/jpeg","productIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"],"quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

Bulk images

Image-first intake and bulk image processing batches.

GET/api/v1/bulk-image-jobs

List bulk image batches

Scope: products:read
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`limit`	query	integer	Page size, 1–50. 1–50; default 20

Responses

200Recent batches.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/bulk-image-jobs' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/bulk-image-jobs

Create an image-first upload batch

Declares up to 50 files; upload each with POST /api/v1/images/upload using bulkJobId and bulkChildId.

Scope: listings:publish
Rate limit: 100 / 60s
Plan: bulk_operations

Request body · application/json

Name	Type	Notes
`items`required	array of object	1–50 items

Responses

202Batch created.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/bulk-image-jobs' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"clientItemId":"example","fileName":"example","productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","type":"main"}]}'

GET/api/v1/bulk-image-jobs/{id}

Get bulk image batch progress

Scope: products:read
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Batch ID.

Responses

200Progress.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/bulk-image-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/bulk-image-jobs/{id}/process

Process every image in an upload batch

Quote it with context.bulkImageProcess.

Scope: ai:use
Rate limit: 100 / 60s
Plan: bulk_operations, advanced_image_studio
Credits: Metered image operations (remove_background 1, upscale 1, cleanup 1 credit each, per uploaded image); formatting operations are free.

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Upload batch ID.

Request body · application/json

Name	Type	Notes
`operations`required	array of remove_background \| white_background \| crop \| resize_2000x2000 \| upscale \| cleanup \| …	1–8 items
`quoteId`	uuid	—
`qualityTier`	low \| high \| premium	—

Responses

202Processing queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/bulk-image-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/process' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":["remove_background"]}'

POST/api/v1/bulk-image-jobs/{id}/retry

Retry failed batch items

Send {} to retry everything. Processing retries need a quote (context.bulkImageProcessRetry).

Scope: listings:publish
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Batch ID.

Request body · application/json

Name	Type	Notes
`childIds`	array of uuid	at most 50 items
`quoteId`	uuid	Required when a metered image operation is retried.

Responses

200Upload items retried.
202Processing retry queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/bulk-image-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/retry' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"childIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"]}'

POST/api/v1/bulk-image-jobs/{id}/cancel

Cancel a bulk image batch

Scope: listings:publish
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Batch ID.

Responses

200Cancelled; reserved credits are refunded.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/bulk-image-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/cancel' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/bulk-image-jobs/{id}/export

Download batch results as CSV

Scope: products:read
Rate limit: 100 / 60s
Plan: bulk_operations

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Batch ID.

Responses

200CSV of batch items.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/bulk-image-jobs/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/export' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Credits

Credit quotes that authorize paid operations.

POST/api/v1/credit-quotes

Quote a paid operation

Returns a single-use quote valid for 10 minutes. Pass its id as quoteId to the paid call. listing_push needs listings:publish; other actions need ai:use.

Scope: ai:use or listings:publish
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`operations`required	array of object	1–20 items
`context`	object	—

Responses

200The quote.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/credit-quotes' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"action":"example","units":1}]}'

Amazon

Amazon India product types and publish context.

GET/api/v1/categories/amazon

Search Amazon product types or get one definition

Scope: listings:validate
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`productType`	query	string	Return this product type definition.
`keywords`	query	string	Search keywords. 1–250 chars

Responses

200SP-API product types or a definition.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/categories/amazon' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/listings/amazon/product-types

Get the Amazon publish review context

Saved and suggested product type, identity, and barcode catalog match.

Scope: listings:validate
Rate limit: 100 / 60s

Parameters (3)

Name	In	Type	Notes
`productId`required	query	uuid	Product ID.
`keywords`	query	string	Product type search keywords. 2–200 chars
`marketplaceConnectionId`	query	uuid	Amazon connection ID.

Responses

200Publish context.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/amazon/product-types?productId=3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Flipkart

Flipkart offers, listing status, and category schemas.

POST/api/v1/flipkart/listings/validate

Validate a Flipkart listing batch

Nothing is sent to Flipkart. Prices must be whole rupees.

Scope: listings:validate
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`payload`required	array of object	Flipkart Listing API v3 items with unique `sku` values.; 1–10 items
`categoryId`	string	at most 255 chars
`connectionId`	uuid	—

Responses

200The validation result.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/flipkart/listings/validate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"payload":[{}]}'

GET/api/v1/flipkart/listings/status

Look up one SKU on Flipkart

Scope: listings:read
Rate limit: 100 / 60s

Parameters (2)

Name	In	Type	Notes
`sku`required	query	string	Seller SKU. 1–255 chars
`connectionId`	query	uuid	Flipkart connection ID (required with several sellers).

Responses

200Live listing status.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/flipkart/listings/status?sku=KURTA-BLUE-M' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/flipkart/listings/offer

Update price or stock for up to 10 listings

Synchronous and free. A 200 does not mean every SKU was accepted: read results[].price.outcome. An unknown outcome is never re-sent under the same key.

Scope: listings:publish
Rate limit: 100 / 60s
Idempotency-Key: Required

Request body · application/json

Name	Type	Notes
`connectionId`	uuid	—
`items`required	array of object	1–10 items

Responses

200Per-SKU outcomes.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/flipkart/listings/offer' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"listingId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}]}'

POST/api/v1/flipkart/listings/offer/bulk

Queue price or stock updates for up to 500 listings

Scope: listings:publish
Rate limit: 100 / 60s
Idempotency-Key: Required

Request body · application/json

Name	Type	Notes
`connectionId`	uuid	—
`items`required	array of object	1–500 items

Responses

200Replay: the existing job.
202Job queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/flipkart/listings/offer/bulk' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"listingId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}]}'

GET/api/v1/flipkart/listings/offer/bulk/{jobId}

Get a bulk offer job

Scope: listings:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`jobId`required	path	uuid	Bulk offer job ID.

Responses

200The job and per-SKU results.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/flipkart/listings/offer/bulk/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/flipkart/taxonomy/{categoryId}

Get a Flipkart category attribute schema

Scope: listings:validate
Rate limit: 100 / 60s

Parameters (3)

Name	In	Type	Notes
`categoryId`required	path	string	Flipkart category (vertical) ID. 1–255 chars
`refresh`	query	true \| false	Bypass the 24-hour cache.
`connectionId`	query	uuid	Flipkart connection ID.

Responses

200Live, stored, or unavailable schema.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/flipkart/taxonomy/kurta' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Templates

Reusable content rules and attribute defaults.

GET/api/v1/templates

List templates

Scope: Any valid API key
Rate limit: 100 / 60s
Plan: templates

Parameters (1)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart	Marketplace. Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.

Responses

200Templates.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/templates' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/templates

Create a template

Scope: listings:publish
Rate limit: 100 / 60s
Plan: templates

Request body · application/json

Name	Type	Notes
`name`required	string	1–120 chars
`description`	string	at most 4000 chars
`categoryId`	string	at most 255 chars
`brand`	string	at most 255 chars
`platform`required	amazon_in \| flipkart	—
`contentRules`	object	default {}
`attributes`	object	default {}
`visibility`	private \| workspace	default "workspace"

Responses

201The template.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/templates' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Launch drafts","platform":"amazon_in"}'

PATCH/api/v1/templates/{id}

Update a template

Scope: listings:publish
Rate limit: 100 / 60s
Plan: templates

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Template ID.

Request body · application/json

Name	Type	Notes
`name`	string	1–120 chars
`description`	string	at most 4000 chars
`categoryId`	string	at most 255 chars
`brand`	string	at most 255 chars
`platform`	amazon_in \| flipkart	—
`contentRules`	object	default {}
`attributes`	object	default {}
`visibility`	private \| workspace	default "workspace"

Responses

200The template.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/templates/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Launch drafts"}'

DELETE/api/v1/templates/{id}

Delete a template

Scope: listings:publish
Rate limit: 100 / 60s
Plan: templates

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Template ID.

Responses

204Done. No response body.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X DELETE 'https://listing.techma.io/api/v1/templates/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Saved views

Shared filters for the catalog and listing tables.

GET/api/v1/views

List saved views

products needs products:read; listings needs listings:read.

Scope: products:read or listings:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`resource`required	query	products \| listings	Library.

Responses

200Saved views.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/views?resource=products' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/views

Create a saved view

products needs products:write; listings needs listings:publish.

Scope: products:write or listings:publish
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`name`required	string	1–80 chars
`resource`required	products \| listings	—
`config`required	object	—

Responses

201The view.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/views' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Launch drafts","resource":"products","config":{"q":"example"}}'

PATCH/api/v1/views/{id}

Update a saved view

Scope: products:write or listings:publish
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	View ID.

Request body · application/json

Name	Type	Notes
`name`	string	1–80 chars
`resource`	products \| listings	—
`config`	object	—

Responses

200The view.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/views/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Launch drafts"}'

DELETE/api/v1/views/{id}

Delete a saved view

Scope: products:write or listings:publish
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	View ID.

Responses

204Done. No response body.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X DELETE 'https://listing.techma.io/api/v1/views/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Orders

Marketplace orders synced from Amazon India and Flipkart.

GET/api/v1/orders

List marketplace orders

Newest purchase first, with an opaque keyset cursor. Orders carry no buyer personal data beyond the ship-to state and postal code.

Scope: listings:read
Rate limit: 100 / 60s

Parameters (7)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart	`platform` filter or pagination parameter.
`status`	query	pending \| unshipped \| partially_shipped \| shipped \| delivered \| return_requested \| …	`status` filter or pagination parameter.
`from`	query	string	First purchase day, YYYY-MM-DD.
`to`	query	string	Last purchase day, YYYY-MM-DD.
`q`	query	string	Search order IDs and SKUs. 1–128 chars
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page. 1–512 chars
`limit`	query	integer	Page size, 1–100. 1–100; default 25

Responses

200A page of orders with sync state and status counts.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/orders' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/orders/{id}

Get an order with its lines

Scope: listings:read
Rate limit: 100 / 60s

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Order ID.

Responses

200The order, its lines, and the stock they moved.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/orders/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/orders/sync

Sync marketplace orders now

Free. An empty body syncs every active connection; a sync already queued or running for a connection is reused. Synced orders can move shared stock, so this needs publish permission.

Scope: listings:publish
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`connectionId`	uuid	—

Responses

202Sync queued or reused per connection.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/orders/sync' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"connectionId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

Inventory

Shared stock on hand and channel stock sync.

GET/api/v1/inventory

List stock and channel sync state

Scope: products:read
Rate limit: 100 / 60s

Parameters (4)

Name	In	Type	Notes
`q`	query	string	Search products by title or SKU. 1–128 chars
`filter`	query	all \| tracked \| untracked \| sync_on \| out_of_sync \| out_of_stock	Stock position filter. default "all"
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page. 1–512 chars
`limit`	query	integer	Page size, 1–100. 1–100; default 25

Responses

200A page of products with stock and a workspace summary.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/inventory' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PATCH/api/v1/inventory

Set stock on hand, safety stock, or sync for up to 50 products

An on-hand change is recorded as an adjustment, and a change to the available quantity of a synced product is pushed to its channels. Send expectedOnHand to refuse the write (409) if stock changed since you read it. Send { productId, restockReturnId } alone to put a received, seller-inspected sellable return back into stock: the quantity comes from the return (capped at what its order line sold), each return restocks once, and a return that is not restockable is refused with 409.

Scope: products:write + listings:publish
Rate limit: 100 / 60s
Plan: marketplace_publish

Request body · application/json

Name	Type	Notes
`items`required	array of object	1–50 items

Responses

200Per-product results.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/inventory' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}]}'

GET/api/v1/inventory/{productId}/adjustments

List stock movements for a product

Scope: products:read
Rate limit: 100 / 60s

Parameters (3)

Name	In	Type	Notes
`productId`required	path	uuid	Product ID.
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page. 1–512 chars
`limit`	query	integer	Page size, 1–100. 1–100; default 50

Responses

200Newest-first adjustments.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/inventory/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/adjustments' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Pricing

Bulk price and stock changes, fee estimates, and unit costs for margins.

GET/api/v1/pricing/listings

List published listings with price, stock, and unit cost

Live and inactive Amazon India and Flipkart listings (variation parents excluded) with the values ListingPilot last sent: price, MRP, sale price and dates, Amazon Business price when enabled, quantity (the shared available stock when stock sync is on), unit cost, and the newest price change row.

Scope: listings:read
Rate limit: 100 / 60s

Parameters (4)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart	Only listings on this marketplace.
`q`	query	string	Search by listing name or seller SKU. 1–128 chars
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page. 1–512 chars
`limit`	query	integer	Page size, 1–100. 1–100; default 50

Responses

200A page of listings.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/pricing/listings' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/pricing/batches

List recent price change batches

Scope: listings:read
Rate limit: 60 / 60s

Parameters (1)

Name	In	Type	Notes
`limit`	query	integer	Batches, 1–50. 1–50; default 10

Responses

200Newest batches with per-status row counts.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/pricing/batches' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/pricing/batches

Change price and stock for up to 500 listings

Free. Every row is validated before anything is queued (Flipkart prices in whole rupees, price not above MRP, sale price below the price with a valid date window, Amazon Business tiers). Each row becomes a durable job: Amazon through patchListingsItem, Flipkart through the price and inventory update endpoints, and a stock change for a product with stock sync on through the shared stock ledger. A price below the product unit cost needs confirmBelowCost: true. Rows report pending, sending, applied, rejected (with the marketplace reason) or ambiguous; an ambiguous row is never resent automatically. The same Idempotency-Key and body return the same batch (200).

Scope: listings:publish + products:write
Rate limit: 60 / 60s
Plan: marketplace_publish
Idempotency-Key: Required

Request body · application/json

Name	Type	Notes
`items`required	array of object	1–500 items
`source`	manual \| csv	default "manual"
`confirmBelowCost`	boolean	default false

Responses

200The batch this Idempotency-Key already created.
202Batch queued.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/pricing/batches' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"listingId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","changes":{"price":499}}]}'

GET/api/v1/pricing/batches/{batchId}

Read a price change batch and every row result

Scope: listings:read
Rate limit: 60 / 60s

Parameters (1)

Name	In	Type	Notes
`batchId`required	path	uuid	Price change batch ID.

Responses

200The batch with its rows.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/pricing/batches/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/pricing/batches/{batchId}/items/{itemId}/check

Check an unconfirmed change against the live listing

Only for a row in ambiguous state. Reads the live listing (nothing is resent) and settles the row as applied, not applied, or still unconfirmed. A 429 means the marketplace is limiting this seller; nothing was changed.

Scope: listings:publish
Rate limit: 60 / 60s

Parameters (2)

Name	In	Type	Notes
`batchId`required	path	uuid	Price change batch ID.
`itemId`required	path	uuid	Price change row ID.

Responses

200The updated batch and the decision for the row.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/pricing/batches/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/items/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/check' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/pricing/fees

Estimate marketplace fees for candidate prices

Free. Amazon rows use the Product Fees API (referral, closing and fulfilment fees; an estimate, not a guarantee) and are cached for ten minutes. A throttled row is throttled with retryAfterSeconds (nothing was processed). Flipkart rows are unavailable: Flipkart publishes no fee estimate API.

Scope: listings:validate
Rate limit: 30 / 60s

Request body · application/json

Name	Type	Notes
`items`required	array of object	1–20 items

Responses

200One estimate per requested row.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/pricing/fees' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"listingId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","price":499}]}'

PATCH/api/v1/pricing/costs

Save or clear unit costs for up to 100 products

The landed cost per unit (and an optional GST rate) used for margin maths and the below-cost guard. unitCost: null removes it. Nothing is sent to a marketplace.

Scope: products:write
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`items`required	array of object	1–100 items

Responses

200The saved costs.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PATCH 'https://listing.techma.io/api/v1/pricing/costs' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192","unitCost":1}]}'

Finance

Marketplace returns, settlement payouts, and the sales and payout report.

GET/api/v1/returns

List marketplace returns

Newest request first, with an opaque keyset cursor. Amazon returns come from the seller-fulfilled and FBA returns reports; Flipkart returns only when the Flipkart returns import is enabled. Each row carries its restock offer (available with a quantity, restocked, or unavailable with a reason); restock through PATCH /api/v1/inventory with restockReturnId. No buyer data is stored.

Scope: listings:read
Rate limit: 100 / 60s

Parameters (7)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart	`platform` filter or pagination parameter.
`status`	query	requested \| in_transit \| received \| refunded \| rejected \| cancelled \| …	`status` filter or pagination parameter.
`from`	query	string	First request day (IST), YYYY-MM-DD.
`to`	query	string	Last request day (IST), YYYY-MM-DD.
`q`	query	string	Search order IDs and SKUs. 1–128 chars
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page. 1–512 chars
`limit`	query	integer	Page size, 1–100. 1–100; default 25

Responses

200A page of returns with status counts and import state.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/returns' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/settlements

List marketplace settlements

Amazon India settlement groups (Finances API financial event groups), newest first, with sales, fee, refund, other and net totals in integer paise from the imported events, and unexplainedPaise when a closed payout differs from its beginning balance plus imported events. Flipkart publishes no settlement API, so none are imported.

Scope: analytics:read
Rate limit: 100 / 60s

Parameters (5)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart	`platform` filter or pagination parameter.
`from`	query	string	First group start day (IST), YYYY-MM-DD.
`to`	query	string	Last group start day (IST), YYYY-MM-DD.
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page. 1–512 chars
`limit`	query	integer	Page size, 1–100. 1–100; default 25

Responses

200A page of settlement groups with import state.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/settlements' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/reports/sales

Sales and payout report

Orders, units, revenue, returned units and return rate (basis points), marketplace fees and refunds (positive paise), and net payout (signed paise) by day, ISO week or month, by channel and by SKU (top 100; skuCount has the total), for an IST date range (at most 186 days daily, 731 weekly, 1,096 monthly). estimatedProfit (and each SKU's estimatedProfitPaise) is net payout minus unit cost (Prices) × units sold, only for SKUs whose every sold unit has a cost; otherwise null. flags lists shipped Amazon orders with no settlement after 14 days, orders whose fees exceed the seller's median fee rate, and closed payouts that differ from their imported events. dataAsOf is the oldest last successful sync of the orders, returns and settlement imports.

Scope: analytics:read
Rate limit: 100 / 60s

Parameters (5)

Name	In	Type	Notes
`from`	query	string	First day (IST), YYYY-MM-DD.
`to`	query	string	Last day (IST), YYYY-MM-DD.
`granularity`	query	day \| week \| month	Period grouping. default "day"
`platform`	query	amazon_in \| flipkart	Only this channel.
`sku`	query	string	Only this seller SKU (case-insensitive). 1–255 chars

Responses

200The report, per-import sync state, and the data-as-of time.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/reports/sales' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/reports/sales/export

Export the sales and payout report

CSV of the same report. view=detail (default) writes one row per period, channel and SKU; period, channel and sku write the rollups. Money columns are exact rupees, including the unit cost total and the estimated profit (blank unless every unit of the SKU has a cost); at most 20,000 rows (422 beyond). Rate limited to 10 exports a minute.

Scope: analytics:read
Rate limit: 10 / 60s

Parameters (6)

Name	In	Type	Notes
`from`	query	string	First day (IST), YYYY-MM-DD.
`to`	query	string	Last day (IST), YYYY-MM-DD.
`granularity`	query	day \| week \| month	Period grouping. default "day"
`platform`	query	amazon_in \| flipkart	Only this channel.
`sku`	query	string	Only this seller SKU (case-insensitive). 1–255 chars
`view`	query	period \| channel \| sku \| detail	Rows to export. default "detail"

Responses

200CSV of the report.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/reports/sales/export' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

POST/api/v1/reports/sync

Import returns and settlements now

Free. Queues the returns and settlement imports for every active connection (or connectionId). An import already queued or running is reused and a connection imported in the last ten minutes is skipped (recently_synced); Flipkart settlements are not_supported. Rate limited to 6 requests a minute.

Scope: listings:publish
Rate limit: 6 / 60s

Request body · application/json

Name	Type	Notes
`connectionId`	uuid	—

Responses

202Import queued, reused or skipped per connection and kind.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/reports/sync' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"connectionId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

Analytics

Marketplace metrics from authorized provider data.

GET/api/v1/marketplace-metrics

Daily marketplace metrics

Scope: analytics:read
Rate limit: 100 / 60s
Plan: advanced_analytics

Parameters (6)

Name	In	Type	Notes
`platform`	query	amazon_in \| flipkart	Marketplace. Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.
`productId`	query	uuid	Product ID.
`listingId`	query	uuid	Listing ID.
`from`	query	date	First day, YYYY-MM-DD.
`to`	query	date	Last day, YYYY-MM-DD.
`limit`	query	integer	Page size, 1–500. 1–500; default 100

Responses

200Metrics and availability.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/marketplace-metrics' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

GET/api/v1/listings/{id}/performance-correlation

Metrics grouped by listing version

Descriptive only: it does not claim a version caused a change.

Scope: analytics:read
Rate limit: 100 / 60s
Plan: advanced_analytics

Parameters (1)

Name	In	Type	Notes
`id`required	path	uuid	Listing ID.

Responses

200Version periods and metrics.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/listings/3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192/performance-correlation' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Exports

Catalog exports.

GET/api/v1/exports/catalog

Export the catalog

Scope: products:read
Rate limit: 100 / 60s
Plan: api_access

Parameters (2)

Name	In	Type	Notes
`format`	query	xlsx \| csv \| pdf	File format. default "xlsx"
`productIds`	query	string	Comma-separated product IDs (at most 500).

Responses

200The export file (XLSX, CSV, or PDF).
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/exports/catalog' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

Marketplace exports

Fill Meesho, Myntra and JioMart bulk-upload sheets from the seller's own marketplace template.

POST/api/v1/marketplace-exports/templates/parse

Parse a marketplace bulk-upload template

Detects the header row, required-column markers, dropdown lists, length rules and example rows, and proposes a column mapping (the saved mapping for this template fingerprint first, then synonyms). Nothing is stored.

Scope: listings:publish
Rate limit: 30 / 60s
Plan: marketplace_publish

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	The marketplace template (binary .xlsx or UTF-8 .csv), at most 8 MB. The format is detected from the bytes.
`marketplace`required	meesho \| myntra \| jiomart	Marketplace whose own bulk-upload template is being filled.
`sheetName`	string	Worksheet to use; detected when omitted.; at most 64 chars

Responses

200Template analysis and proposed mapping.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/marketplace-exports/templates/parse' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -F 'file=@./upload-file' \
  -F 'marketplace=meesho'

GET/api/v1/marketplace-exports/mappings

Load the saved mapping for a template

Scope: listings:read
Rate limit: 30 / 60s
Plan: marketplace_publish

Parameters (2)

Name	In	Type	Notes
`marketplace`required	query	meesho \| myntra \| jiomart	Marketplace code.
`fingerprint`required	query	string	Template fingerprint from the parse step.

Responses

200The saved mapping, or null.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/marketplace-exports/mappings?marketplace=meesho&fingerprint=example' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"

PUT/api/v1/marketplace-exports/mappings

Save a reusable mapping for a template

Saved per workspace, marketplace and template fingerprint; the next upload of the same template maps automatically.

Scope: listings:publish
Rate limit: 30 / 60s
Plan: marketplace_publish

Request body · application/json

Name	Type	Notes
`marketplace`required	meesho \| myntra \| jiomart	—
`fingerprint`required	string	—
`sheetName`required	string	1–64 chars
`mapping`required	object	—

Responses

200The saved mapping.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X PUT 'https://listing.techma.io/api/v1/marketplace-exports/mappings' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"marketplace":"meesho","fingerprint":"example","sheetName":"example","mapping":{"dataStartRow":2,"columns":{}}}'

POST/api/v1/marketplace-exports/mappings/suggest

Suggest mappings for unmapped columns with AI

Sends only header text, instructions, examples and a few dropdown values (no product data). Results are suggestions to review.

Scope: listings:publish + ai:use
Rate limit: 30 / 60s
Plan: marketplace_publish
Idempotency-Key: Required
Credits: Quote action sheet_column_mapping: 1 credit per unit (1 unit).

Request body · application/json

Name	Type	Notes
`marketplace`required	meesho \| myntra \| jiomart	—
`fingerprint`required	string	—
`columns`required	array of object	1–120 items
`quoteId`required	uuid	—

Responses

201AI column suggestions.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/marketplace-exports/mappings/suggest' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"marketplace":"meesho","fingerprint":"example","columns":[{"letter":"example","label":"example"}],"quoteId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

POST/api/v1/marketplace-exports/validate

Fill the template in memory and validate every row

Checks required columns, dropdown values, length and number rules, and India rules (MRP at or above selling price, HSN digits, GST rate, legal metrology declarations).

Scope: listings:publish + products:read
Rate limit: 30 / 60s
Plan: marketplace_publish

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	The marketplace template (binary .xlsx or UTF-8 .csv), at most 8 MB. The format is detected from the bytes.
`marketplace`required	meesho \| myntra \| jiomart	Marketplace whose own bulk-upload template is being filled.
`sheetName`	string	Worksheet to use; detected when omitted.; at most 64 chars
`fingerprint`required	string	Fingerprint returned by the parse step.
`mapping`required	string	JSON-encoded mapping (`dataStartRow`, `columns`).
`productIds`required	string	JSON array of up to 200 product ids; a variation parent expands to one row per child.
`acceptErrors`	true \| false	Download only: write rows that still have validation errors.

Responses

200Row-level validation results.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/marketplace-exports/validate' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -F 'file=@./upload-file' \
  -F 'marketplace=meesho' \
  -F 'fingerprint=example' \
  -F 'mapping=example' \
  -F 'productIds=example'

POST/api/v1/marketplace-exports/download

Download the filled template

Returns the uploaded template with the selected rows written below its header and example rows; every other part of the workbook is unchanged. Rows with errors require acceptErrors=true.

Scope: listings:publish + products:read
Rate limit: 30 / 60s
Plan: marketplace_publish

Request body · multipart/form-data

Name	Type	Notes
`file`required	file	The marketplace template (binary .xlsx or UTF-8 .csv), at most 8 MB. The format is detected from the bytes.
`marketplace`required	meesho \| myntra \| jiomart	Marketplace whose own bulk-upload template is being filled.
`sheetName`	string	Worksheet to use; detected when omitted.; at most 64 chars
`fingerprint`required	string	Fingerprint returned by the parse step.
`mapping`required	string	JSON-encoded mapping (`dataStartRow`, `columns`).
`productIds`required	string	JSON array of up to 200 product ids; a variation parent expands to one row per child.
`acceptErrors`	true \| false	Download only: write rows that still have validation errors.

Responses

200The filled template (.xlsx or .csv, matching the upload).
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/marketplace-exports/download' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -F 'file=@./upload-file' \
  -F 'marketplace=meesho' \
  -F 'fingerprint=example' \
  -F 'mapping=example' \
  -F 'productIds=example'

POST/api/v1/marketplace-exports/images

Download the rows’ images as a zip

File names are <SKU>_<position>, matching the filled sheet. Only images stored in ListingPilot are included; MANIFEST.csv lists the rest.

Scope: listings:publish + products:read
Rate limit: 30 / 60s
Plan: marketplace_publish

Request body · application/json

Name	Type	Notes
`marketplace`required	meesho \| myntra \| jiomart	—
`productIds`required	array of uuid	1–200 items

Responses

200ZIP with MANIFEST.csv and README.txt.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/marketplace-exports/images' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"marketplace":"meesho","productIds":["3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"]}'

Tools

Deterministic content tools applied to a product.

POST/api/v1/tools/convert

Apply a deterministic tool result to a product

No AI and no credits. Writes the tool output into the listing content.

Scope: products:write
Rate limit: 100 / 60s

Request body · application/json

Name	Type	Notes
`slug`required	title-generator \| bullet-point-generator \| product-description-generator \| keyword-finder	—
`productId`required	uuid	—
`platform`	amazon_in \| flipkart	Marketplace code used in requests: `amazon_in` (Amazon India) or `flipkart`.; default "amazon_in"
`productName`	string	at most 500 chars
`brand`	string	at most 255 chars
`category`	string	at most 255 chars
`description`	string	at most 4000 chars
`features`	string	at most 8000 chars
`keywords`	string	at most 4000 chars

Responses

200Applied fields and the preview.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X POST 'https://listing.techma.io/api/v1/tools/convert' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"slug":"title-generator","productId":"3f1c2b4e-8a6d-4c1e-9b7a-2d5e6f708192"}'

Webhooks

Outbound webhook configuration (read-only for API keys).

GET/api/v1/webhooks/endpoints

List webhook endpoints and recent deliveries

Endpoints are created, rotated, and tested by workspace admins in Settings. Secrets are never returned here.

Scope: webhooks:receive
Rate limit: 100 / 60s
Plan: api_access

Responses

200Endpoints, deliveries, and limits.
4xxErrors use the shared error envelope. See Errors.

Example request

shell

curl -X GET 'https://listing.techma.io/api/v1/webhooks/endpoints' \
  -H "Authorization: Bearer $LISTINGPILOT_API_KEY"