API · Inventory
Inventory API
Inventory items are the individual sellable units in your catalog. Each item belongs to a product and can have assets (photos), condition grades, pricing, and marketplace listings.
List inventory items
GET List inventory
Returns a paginated list of the authenticated user's inventory items with nested product, assets, and computed fields.
Query parameters
| Parameter | Type | Description |
|---|---|---|
search | string | Search across name, manual description, manual SKU, product title, artist name, catalog number |
status | string | Filter by status — repeated or comma-separated. Validated against status choices. |
ordering | string | Sort field (see below) |
page | integer | Page number (default: 1) |
page_size | integer | Results per page (default: 10, max: 100) |
Ordering options
| Value | Description |
|---|---|
created / -created | Date created (default: -created) |
updated / -updated | Date last modified |
name / title | Alphabetical by name (title is an alias) |
price_total_usd | By price |
status | By status code |
condition_item | By condition grade |
manual_sku | By SKU |
days_in_inventory | By age (computed) |
curl "https://app.instica.com/api/v1/inventory/\
?status=ready-to-sell\
&ordering=-created\
&page_size=25" \
-H "Authorization: Bearer YOUR_TOKEN" {
"count": 156,
"next": ".../api/v1/inventory/?page=2",
"previous": null,
"results": [
{
"uid": "inv_d4e5f6",
"title": "Abbey Road - VG+",
"name": null,
"product": {
"uid": "prod_a1b2c3",
"title": "Abbey Road",
"type": "physical",
"artist": {
"uid": "art_x1y2",
"name": "The Beatles"
},
"catalog_number": "PCS 7088"
},
"organization": {
"uid": "org_abc",
"display_name": "My Store",
"slug": "my-store",
"default_barcode_type": "code128"
},
"condition_item": "vg_plus",
"condition_item_display": "VG+",
"condition_container": "vg",
"condition_container_display": "VG",
"status": "ready-to-sell",
"status_display": "Ready to Sell",
"price_total_usd": "34.99",
"price_item_usd": "29.99",
"price_shipping_usd": "5.00",
"price_expected_usd": "35.00",
"assets": [ ... ],
"days_in_inventory": 14.2,
"days_listed": 0,
"listed_at": null,
"is_deletable": true,
"created": "2025-01-15T10:30:00Z",
"updated": "2025-02-10T14:22:00Z"
}
]
} Create an inventory item
POST Create inventory item
Create a new inventory item. Link to an existing product via product_uid, or auto-create a product using product_title.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
product_uid | string | No* | Link to existing product by UID |
product_title | string | No* | Auto-create product with this title |
name | string | No* | Required if no product_uid is specified |
condition_item | string | No | Condition grade code (normalized via grading system) |
condition_container | string | No | Container condition. Auto-mirrors item condition unless manually set. |
condition_container_manually_set | boolean | No | Prevent auto-mirroring of container condition |
condition_comments | string | No | Free-text condition notes |
price_total_usd | decimal | No | Total listing price |
price_item_usd | decimal | No | Item-only price |
price_shipping_usd | decimal | No | Shipping price |
price_expected_usd | decimal | No | Expected/target price |
price_purchased_item | decimal | No | Cost basis (max 7 digits, 2 decimals) |
price_for_purchases_shipping | decimal | No | Purchase shipping cost |
status | string | No | Default: draft |
inventory_item_type_uid | string | No | Item type by UID (write-only) |
manual_description | string | No | Custom description |
manual_sku | string | No | Custom SKU |
condition_seller_description | string | No | Seller-facing condition notes |
listing_current_price | decimal | No | Current marketplace listing price |
product_catalog_number | string | No | Catalog number for auto-created product (write-only) |
product_sku | string | No | SKU for auto-created product (write-only) |
product_upc | string | No | UPC for auto-created product (write-only) |
product_year | date | No | Release year for auto-created product (write-only) |
product_metadata | object | No | Must include external_id key (write-only) |
Tip: Use GET /api/v1/inventory/choices/conditions/ to retrieve valid condition values.
curl -X POST https://app.instica.com/api/v1/inventory/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_uid": "prod_a1b2c3",
"condition_item": "vg_plus",
"condition_container": "vg",
"price_total_usd": "34.99",
"price_shipping_usd": "5.00",
"price_purchased_item": "12.00",
"status": "ready-to-sell",
"manual_description": "Original 1969 UK pressing."
}' curl -X POST https://app.instica.com/api/v1/inventory/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_title": "Abbey Road",
"name": "Abbey Road LP - VG+",
"product_catalog_number": "PCS 7088",
"product_year": "1969",
"condition_item": "vg_plus",
"price_total_usd": "34.99",
"inventory_item_type_uid": "type_vinyl"
}' {
"uid": "inv_new789",
"title": "Abbey Road - VG+",
"product": {
"uid": "prod_a1b2c3",
"title": "Abbey Road"
},
"condition_item": "vg_plus",
"condition_item_display": "VG+",
"status": "ready-to-sell",
"status_display": "Ready to Sell",
"price_total_usd": "34.99",
"is_deletable": true,
"created": "2025-03-01T09:00:00Z"
} Get a single item
GET Inventory item detail
Returns the full inventory item with all assets, listing states, and computed fields. The detail view adds two extra fields beyond the list response:
Additional detail fields
| Field | Type | Description |
|---|---|---|
is_sold | boolean | Whether this item has been sold |
platform_listability | array | Per-platform listing eligibility with blocking reasons |
curl https://app.instica.com/api/v1/inventory/inv_d4e5f6/ \
-H "Authorization: Bearer YOUR_TOKEN" {
"platform": {
"uid": "plat_ebay",
"name": "eBay",
"display_name": "eBay",
"slug": "ebay",
"platform_type": "marketplace",
"supports_digital": false,
"supports_api_connection": true,
"connection_type": "oauth"
},
"can_be_listed": true,
"blocking_code": null,
"blocking_reason": null
} Update an item
PATCH Update inventory item
Partially update an inventory item. Same writable fields as the create endpoint.
curl -X PATCH \
https://app.instica.com/api/v1/inventory/inv_d4e5f6/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"price_total_usd": "39.99",
"condition_item": "nm",
"condition_comments": "Upgraded after re-inspection."
}' Delete an item
DELETE Delete inventory item
Soft-deletes the item. Returns 204 No Content if is_deletable is true, or 400 Bad Request if the item has active listings or orders.
Warning: Check the is_deletable field before attempting to delete. Items with active orders cannot be deleted. Use bulk restore to recover soft-deleted items.
curl -X DELETE \
https://app.instica.com/api/v1/inventory/inv_d4e5f6/ \
-H "Authorization: Bearer YOUR_TOKEN" Upload assets (photos)
Assets are images attached to inventory items — typically photos used in marketplace listings.
POST Upload asset
Upload one or more images. Use multipart/form-data.
Upload fields
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes* | Single file upload |
files | file[] | Yes* | Multiple files (up to 10 per request) |
type | string | Yes | Asset type (from asset type choices) |
description | string | No | Asset description |
is_identifying_asset | boolean | No | Mark as identifying/primary asset |
Supported MIME types
image/jpeg, image/png, image/webp, image/heic, image/heif, image/gif
Photo limit per item is enforced by your subscription's photos_per_item_limit.
| Endpoint | Method | Description |
|---|---|---|
.../assets/batch/ | POST | Batch upload (always multi-file mode) |
.../assets/{asset_uid}/ | DELETE | Delete a specific asset |
curl -X POST \
https://app.instica.com/api/v1/inventory/inv_d4e5f6/assets/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/photo.jpg" \
-F "type=photo" \
-F "is_identifying_asset=true" {
"uid": "ast_g7h8i9",
"type": "photo",
"description": "",
"file_url": "https://cdn.instica.com/assets/...",
"thumbnail_url": "https://cdn.instica.com/...",
"file_size": 2847392,
"file_name": "photo.jpg",
"is_identifying_asset": true,
"listing_assets": [],
"created": "2025-03-01T09:00:00Z",
"updated": "2025-03-01T09:00:00Z"
} {
"created": [ ... ],
"errors": [],
"created_count": 3,
"failed_count": 0,
"associated_inventory_items_count": 1
} Manage listings
GET List all listings
Returns all marketplace listings for an inventory item.
Listing fields
| Field | Type | Description |
|---|---|---|
uid | string | Listing identifier |
status | string | Listing status code |
status_display | string | Human-readable status |
platform | object | Platform details (uid, name, slug, type) |
listing_id | string | External marketplace listing ID |
listing_price_usd | decimal | Listing price in USD |
marketplace_url | URL | Link to marketplace listing (when listed) |
marketplace_description | string | Listing description |
ml_generated_title | string | AI-generated title |
ml_generated_description | string | AI-generated description |
marketplace_details | object | Platform-specific data (shallow merge on update) |
permissions | object | can_list, can_delist, can_update_price, can_retry_listing, can_retry_delisting |
action_reasons | object | Explanations for disabled actions |
last_error_code | object | { uid, slug, message, description } (nullable) |
[
{
"uid": "lst_abc123",
"status": "listed",
"status_display": "Listed",
"platform": {
"uid": "plat_ebay",
"name": "eBay",
"display_name": "eBay",
"slug": "ebay",
"platform_type": "marketplace"
},
"listing_id": "394857201",
"listing_price_usd": "34.99",
"marketplace_url": "https://ebay.com/itm/...",
"is_sold": false,
"permissions": {
"can_list": false,
"can_delist": true,
"can_update_price": true,
"can_retry_listing": false,
"can_retry_delisting": false
},
"action_reasons": {},
"last_error_code": null
}
] Platform list & delist
Control per-item, per-platform listing state. All endpoints accept an optional is_draft parameter (default: true).
| Endpoint | Method | Description |
|---|---|---|
.../platforms/ | GET | List platforms for item |
.../platforms/{slug}/ | GET | Platform detail |
.../platforms/{slug}/list/ | POST | List on platform |
.../platforms/{slug}/delist/ | POST | Delist from platform |
.../platform/{slug}/list/all/ | POST | List on all connected platforms |
.../platform/{slug}/delist/all/ | POST | Delist from all platforms |
.../platforms/bulk/list/ | POST | List on multiple platforms |
.../platforms/bulk/delist/ | POST | Delist from multiple platforms |
Base path: /api/v1/inventory/{uid}/
Business logic: Price validation occurs before listing. Items without a listing price receive status listing_failed with error code price_not_set.
curl -X POST \
https://app.instica.com/api/v1/inventory/\
inv_d4e5f6/platforms/ebay/list/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "is_draft": false }' {
"platform": "ebay",
"listing_uid": "lst_abc123",
"status": "in_progress",
"message": "Listing submitted to eBay."
} curl -X POST \
https://app.instica.com/api/v1/inventory/\
inv_d4e5f6/platform/ebay/delist/all/ \
-H "Authorization: Bearer YOUR_TOKEN" Bulk operations
Perform actions on up to 100 items per request. All endpoints accept an items array of UIDs.
POST Bulk price update
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | Yes | 1–100 UIDs |
value | decimal | Yes | Price value (max 10 digits, 2 decimals) |
mode | string | No | set (default), increase, decrease, percentage |
POST Bulk status change
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | Yes | 1–100 UIDs |
status | string | Yes | draft, purchased, received, ready-to-sell, cancelled |
POST Bulk field update
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | Yes | 1–100 UIDs |
updates | object | Yes | Allowed keys: condition_item, condition_container, notes, location, price_total_usd, price_shipping_usd |
POST Bulk delete
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | Yes | 1–100 UIDs |
hard_delete | boolean | No | Default: false (soft delete/archive) |
POST Bulk restore
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | Yes | UIDs of deleted items |
target_status | string | No | Default: draft. Options: draft, purchased, received, ready-to-sell |
POST Bulk list / delist
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | Yes | 1–100 UIDs |
platforms | string[] | List: Yes / Delist: No | Platform slugs. Omit on delist for all platforms. |
is_draft | boolean | No | Default: true (list endpoint only) |
curl -X POST \
https://app.instica.com/api/v1/inventory/bulk/price/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": ["inv_001", "inv_002", "inv_003"],
"value": "10",
"mode": "percentage"
}' curl -X POST \
https://app.instica.com/api/v1/inventory/bulk/status/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": ["inv_001", "inv_002"],
"status": "ready-to-sell"
}' {
"success_count": 3,
"failure_count": 0,
"total_count": 3,
"errors": [],
"updated_uids": [
"inv_001", "inv_002", "inv_003"
]
} curl -X POST \
https://app.instica.com/api/v1/inventory/bulk/list/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": ["inv_001", "inv_002"],
"platforms": ["ebay", "discogs"],
"is_draft": false
}' {
"max_items_per_batch": 100,
"is_pro": true,
"allowed_bulk_statuses": [
"draft", "purchased", "received",
"ready-to-sell", "cancelled"
]
} Inventory analytics
GET Analytics summary
Returns aggregated inventory metrics including counts, financials, sell-through rate, and status breakdown.
Summary response fields
| Field | Type | Description |
|---|---|---|
total_items | integer | Total inventory items |
sellable_items | integer | Items available for sale |
listed_items | integer | Currently listed items |
sold_items | integer | Items sold |
total_cost_basis | decimal | Total purchase cost |
expected_value | decimal | Total expected value |
listed_value | decimal | Total value of listed items |
sold_revenue | decimal | Total revenue from sales |
sold_profit | decimal | Total profit from sales |
sell_through_rate | float | Percentage of items sold |
average_days_to_sell | float | Average time to sell (nullable) |
status_breakdown | array | Count per status |
updated_at | datetime | When last computed |
GET Analytics trends
Time-series data for purchases, listings, and sales over a date range.
Trends response fields
| Field | Type | Description |
|---|---|---|
range_days | integer | Number of days in the range |
range_start | date | Start of the date range |
range_end | date | End of the date range |
purchases | array | Daily purchase data: { date, count, value } |
listings | array | Daily listing data: { date, count, value } |
sales | array | Daily sales data: { date, count, value } |
{
"total_items": 245,
"sellable_items": 180,
"listed_items": 120,
"sold_items": 65,
"total_cost_basis": "3250.00",
"expected_value": "8500.00",
"listed_value": "5600.00",
"sold_revenue": "4200.00",
"sold_profit": "1850.00",
"sell_through_rate": 0.265,
"average_days_to_sell": 18.3,
"status_breakdown": [
{ "status": "ready-to-sell", "label": "Ready", "count": 60 },
{ "status": "listed", "label": "Listed", "count": 120 },
{ "status": "sold", "label": "Sold", "count": 65 }
],
"updated_at": "2025-03-01T12:00:00Z"
} {
"range_days": 30,
"range_start": "2025-02-01",
"range_end": "2025-03-01",
"purchases": [
{ "date": "2025-02-01", "count": 5, "value": "120.00" },
{ "date": "2025-02-02", "count": 3, "value": "75.00" }
],
"listings": [
{ "date": "2025-02-01", "count": 8, "value": "320.00" },
{ "date": "2025-02-02", "count": 6, "value": "180.00" }
]
} CSV import & export
Import inventory from CSV files or export your current inventory for offline analysis.
| Endpoint | Method | Description |
|---|---|---|
/api/v1/inventory/export/csv/ | GET | Download inventory as CSV |
/api/v1/inventory/import/csv/ | POST | Upload and import a CSV file |
Export jobs run asynchronously. The API returns a job ID that can be polled for completion.
curl https://app.instica.com/api/v1/inventory/export/csv/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-o inventory_export.csv curl -X POST \
https://app.instica.com/api/v1/inventory/import/csv/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/inventory.csv" Reference data
Use these endpoints to retrieve valid values for dropdowns and form fields.
| Endpoint | Returns |
|---|---|
GET /api/v1/inventory/types/ | All item types (vinyl, CD, cassette, etc.) |
GET /api/v1/inventory/types/search/?q=vinyl | Search item types |
GET /api/v1/inventory/types/platform/{slug}/search/?q=vinyl | Search platform-specific item types |
GET /api/v1/inventory/choices/conditions/ | Condition grade options (Mint, NM, VG+, etc.) |
GET /api/v1/inventory/choices/statuses/ | Inventory status options |
GET /api/v1/inventory/choices/shipment-carriers/ | Shipping carrier list |
GET /api/v1/inventory/choices/asset-types/ | Asset type options |
[
{ "value": "mint", "label": "Mint (M)" },
{ "value": "nm", "label": "Near Mint (NM)" },
{ "value": "vg_plus", "label": "VG+" },
{ "value": "vg", "label": "VG" },
{ "value": "good_plus", "label": "G+" },
{ "value": "good", "label": "Good (G)" },
{ "value": "fair", "label": "Fair (F)" },
{ "value": "poor", "label": "Poor (P)" }
] Audit logs
GET Item audit logs
Returns a chronological audit trail of listing actions for an inventory item — including listings, delistings, price changes, and errors.
Audit log fields
| Field | Type | Description |
|---|---|---|
uid | string | Audit log entry identifier |
action | string | Action performed (e.g., list, delist, price_update) |
source | string | Action source (api, web, system, extension) |
actor_uid | string | UID of the user who performed the action |
organization_uid | string | Organization UID |
listing_uid | string | Associated listing UID |
inventory_item_uid | string | Inventory item UID |
inventory_item_title | string | Item title at time of action |
platform_slug | string | Target platform |
status_before | string | Listing status before action |
status_after | string | Listing status after action |
message | string | Human-readable description |
metadata | object | Additional data (prices, errors, etc.) |
request_id | string | Request correlation ID |
ip_address | string | Client IP address |
user_agent | string | Client user agent |
severity | string | Log severity level |
created | datetime | When the action occurred |
curl https://app.instica.com/api/v1/inventory/\
inv_d4e5f6/audit-logs/ \
-H "Authorization: Bearer YOUR_TOKEN" {
"uid": "log_abc123",
"action": "list",
"source": "api",
"actor_uid": "usr_xyz",
"platform_slug": "ebay",
"status_before": "draft",
"status_after": "listed",
"message": "Listed on eBay at $34.99",
"metadata": {
"listing_price": "34.99"
},
"severity": "info",
"created": "2025-03-01T09:00:00Z"
} Export jobs
Large exports run asynchronously. Create an export job and poll for completion.
| Endpoint | Method | Description |
|---|---|---|
/api/v1/exports/ | GET | List export jobs |
/api/v1/exports/inventory/csv/ | POST | Create inventory CSV export |
/api/v1/exports/{uid}/ | GET | Check status / download file |
Tip: Poll the job detail endpoint until status changes to completed, then download the file from the response URL.
curl -X POST \
https://app.instica.com/api/v1/exports/inventory/csv/ \
-H "Authorization: Bearer YOUR_TOKEN" curl https://app.instica.com/api/v1/exports/exp_abc/ \
-H "Authorization: Bearer YOUR_TOKEN"
# {
# "uid": "exp_abc",
# "status": "completed",
# "file_url": "https://cdn.instica.com/...",
# "created_at": "2025-03-01T09:00:00Z"
# } Response schema
Complete field reference for the inventory item object.
| Field | Type | Description |
|---|---|---|
uid | string | Unique identifier (read-only) |
title | string | Computed display title (read-only) |
name | string | Manual name (overrides computed title) |
user | object | { uid, username, email } (read-only) |
organization | object | { uid, display_name, slug, default_barcode_type } (read-only) |
product | object | Parent product summary (read-only) |
inventory_item_type | object | { uid, name, slug } (read-only) |
condition_item | string | Item condition grade code |
condition_item_display | string | Human-readable condition (read-only) |
condition_container | string | Container/sleeve condition code |
condition_container_display | string | Human-readable container condition (read-only) |
condition_comments | string | Free-text condition notes |
condition_seller_description | string | Seller-facing condition notes |
grade_tier_code | string | Grade tier code (read-only) |
grade_tier_label | string | Grade tier display label (read-only) |
status | string | Current status code |
status_display | string | Human-readable status (read-only) |
price_total_usd | decimal | Total listing price |
price_item_usd | decimal | Item-only price |
price_shipping_usd | decimal | Shipping price |
price_expected_usd | decimal | Expected/target price |
price_purchased_item | decimal | Purchase cost basis |
price_for_purchases_shipping | decimal | Purchase shipping cost |
listing_current_price | decimal | Current marketplace price |
default_pricing_model | object | { uid, type, type_display } (read-only) |
manual_description | string | Custom description |
manual_sku | string | Custom SKU |
resolved_sku | string | Best resolved SKU (read-only) |
resolved_sku_source | string | SKU source (read-only) |
assets | array | Attached images and files (read-only) |
days_in_inventory | float | Days since receipt/purchase/creation (read-only) |
days_listed | float | Days since first listed (read-only) |
listed_at | datetime | When first listed (read-only) |
is_deletable | boolean | Whether item can be deleted (read-only) |
created | datetime | Creation timestamp (read-only) |
updated | datetime | Last update timestamp (read-only) |
{
"uid": "ast_g7h8i9",
"type": "photo",
"description": "",
"file_url": "https://cdn.instica.com/assets/...",
"thumbnail_url": "https://cdn.instica.com/...",
"file_size": 2847392,
"file_name": "front-cover.jpg",
"is_identifying_asset": true,
"listing_assets": [],
"created": "2025-01-15T10:30:00Z",
"updated": "2025-01-15T10:30:00Z"
}