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

/api/v1/inventory/

Returns a paginated list of the authenticated user's inventory items with nested product, assets, and computed fields.

Query parameters

ParameterTypeDescription
searchstringSearch across name, manual description, manual SKU, product title, artist name, catalog number
statusstringFilter by status — repeated or comma-separated. Validated against status choices.
orderingstringSort field (see below)
pageintegerPage number (default: 1)
page_sizeintegerResults per page (default: 10, max: 100)

Ordering options

ValueDescription
created / -createdDate created (default: -created)
updated / -updatedDate last modified
name / titleAlphabetical by name (title is an alias)
price_total_usdBy price
statusBy status code
condition_itemBy condition grade
manual_skuBy SKU
days_in_inventoryBy age (computed)
Request
curl "https://app.instica.com/api/v1/inventory/\
?status=ready-to-sell\
&ordering=-created\
&page_size=25" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response — 200 OK
{
  "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

/api/v1/inventory/

Create a new inventory item. Link to an existing product via product_uid, or auto-create a product using product_title.

Request body

FieldTypeRequiredDescription
product_uidstringNo*Link to existing product by UID
product_titlestringNo*Auto-create product with this title
namestringNo*Required if no product_uid is specified
condition_itemstringNoCondition grade code (normalized via grading system)
condition_containerstringNoContainer condition. Auto-mirrors item condition unless manually set.
condition_container_manually_setbooleanNoPrevent auto-mirroring of container condition
condition_commentsstringNoFree-text condition notes
price_total_usddecimalNoTotal listing price
price_item_usddecimalNoItem-only price
price_shipping_usddecimalNoShipping price
price_expected_usddecimalNoExpected/target price
price_purchased_itemdecimalNoCost basis (max 7 digits, 2 decimals)
price_for_purchases_shippingdecimalNoPurchase shipping cost
statusstringNoDefault: draft
inventory_item_type_uidstringNoItem type by UID (write-only)
manual_descriptionstringNoCustom description
manual_skustringNoCustom SKU
condition_seller_descriptionstringNoSeller-facing condition notes
listing_current_pricedecimalNoCurrent marketplace listing price
product_catalog_numberstringNoCatalog number for auto-created product (write-only)
product_skustringNoSKU for auto-created product (write-only)
product_upcstringNoUPC for auto-created product (write-only)
product_yeardateNoRelease year for auto-created product (write-only)
product_metadataobjectNoMust include external_id key (write-only)

Tip: Use GET /api/v1/inventory/choices/conditions/ to retrieve valid condition values.

Link to existing product
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."
  }'
Auto-create product
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"
  }'
Response — 201 Created
{
  "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

/api/v1/inventory/{uid}/

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

FieldTypeDescription
is_soldbooleanWhether this item has been sold
platform_listabilityarrayPer-platform listing eligibility with blocking reasons
Request
curl https://app.instica.com/api/v1/inventory/inv_d4e5f6/ \
  -H "Authorization: Bearer YOUR_TOKEN"
platform_listability entry
{
  "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

/api/v1/inventory/{uid}/

Partially update an inventory item. Same writable fields as the create endpoint.

Request
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

/api/v1/inventory/{uid}/

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.

Request
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

/api/v1/inventory/{uid}/assets/

Upload one or more images. Use multipart/form-data.

Upload fields

FieldTypeRequiredDescription
filefileYes*Single file upload
filesfile[]Yes*Multiple files (up to 10 per request)
typestringYesAsset type (from asset type choices)
descriptionstringNoAsset description
is_identifying_assetbooleanNoMark 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.

EndpointMethodDescription
.../assets/batch/POSTBatch upload (always multi-file mode)
.../assets/{asset_uid}/DELETEDelete a specific asset
Upload single photo
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"
Response — 201 Created
{
  "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"
}
Batch upload response — 207
{
  "created": [ ... ],
  "errors": [],
  "created_count": 3,
  "failed_count": 0,
  "associated_inventory_items_count": 1
}

Manage listings

GET List all listings

/api/v1/inventory/{uid}/listings/

Returns all marketplace listings for an inventory item.

Listing fields

FieldTypeDescription
uidstringListing identifier
statusstringListing status code
status_displaystringHuman-readable status
platformobjectPlatform details (uid, name, slug, type)
listing_idstringExternal marketplace listing ID
listing_price_usddecimalListing price in USD
marketplace_urlURLLink to marketplace listing (when listed)
marketplace_descriptionstringListing description
ml_generated_titlestringAI-generated title
ml_generated_descriptionstringAI-generated description
marketplace_detailsobjectPlatform-specific data (shallow merge on update)
permissionsobjectcan_list, can_delist, can_update_price, can_retry_listing, can_retry_delisting
action_reasonsobjectExplanations for disabled actions
last_error_codeobject{ uid, slug, message, description } (nullable)
Listing response
[
  {
    "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).

EndpointMethodDescription
.../platforms/GETList platforms for item
.../platforms/{slug}/GETPlatform detail
.../platforms/{slug}/list/POSTList on platform
.../platforms/{slug}/delist/POSTDelist from platform
.../platform/{slug}/list/all/POSTList on all connected platforms
.../platform/{slug}/delist/all/POSTDelist from all platforms
.../platforms/bulk/list/POSTList on multiple platforms
.../platforms/bulk/delist/POSTDelist 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.

List on eBay
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 }'
Response
{
  "platform": "ebay",
  "listing_uid": "lst_abc123",
  "status": "in_progress",
  "message": "Listing submitted to eBay."
}
Delist from all
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

/api/v1/inventory/bulk/price/
FieldTypeRequiredDescription
itemsstring[]Yes1–100 UIDs
valuedecimalYesPrice value (max 10 digits, 2 decimals)
modestringNoset (default), increase, decrease, percentage

POST Bulk status change

/api/v1/inventory/bulk/status/
FieldTypeRequiredDescription
itemsstring[]Yes1–100 UIDs
statusstringYesdraft, purchased, received, ready-to-sell, cancelled

POST Bulk field update

/api/v1/inventory/bulk/fields/
FieldTypeRequiredDescription
itemsstring[]Yes1–100 UIDs
updatesobjectYesAllowed keys: condition_item, condition_container, notes, location, price_total_usd, price_shipping_usd

POST Bulk delete

/api/v1/inventory/bulk/delete/
FieldTypeRequiredDescription
itemsstring[]Yes1–100 UIDs
hard_deletebooleanNoDefault: false (soft delete/archive)

POST Bulk restore

/api/v1/inventory/bulk/restore/
FieldTypeRequiredDescription
itemsstring[]YesUIDs of deleted items
target_statusstringNoDefault: draft. Options: draft, purchased, received, ready-to-sell

POST Bulk list / delist

/api/v1/inventory/bulk/list/
/api/v1/inventory/bulk/delist/
FieldTypeRequiredDescription
itemsstring[]Yes1–100 UIDs
platformsstring[]List: Yes / Delist: NoPlatform slugs. Omit on delist for all platforms.
is_draftbooleanNoDefault: true (list endpoint only)
Bulk price — increase 10%
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"
  }'
Bulk status change
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"
  }'
Bulk operation response
{
  "success_count": 3,
  "failure_count": 0,
  "total_count": 3,
  "errors": [],
  "updated_uids": [
    "inv_001", "inv_002", "inv_003"
  ]
}
Bulk list on eBay + Discogs
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
  }'
GET /inventory/bulk/stats/
{
  "max_items_per_batch": 100,
  "is_pro": true,
  "allowed_bulk_statuses": [
    "draft", "purchased", "received",
    "ready-to-sell", "cancelled"
  ]
}

Inventory analytics

GET Analytics summary

/api/v1/inventory/analytics/summary/

Returns aggregated inventory metrics including counts, financials, sell-through rate, and status breakdown.

Summary response fields

FieldTypeDescription
total_itemsintegerTotal inventory items
sellable_itemsintegerItems available for sale
listed_itemsintegerCurrently listed items
sold_itemsintegerItems sold
total_cost_basisdecimalTotal purchase cost
expected_valuedecimalTotal expected value
listed_valuedecimalTotal value of listed items
sold_revenuedecimalTotal revenue from sales
sold_profitdecimalTotal profit from sales
sell_through_ratefloatPercentage of items sold
average_days_to_sellfloatAverage time to sell (nullable)
status_breakdownarrayCount per status
updated_atdatetimeWhen last computed

GET Analytics trends

/api/v1/inventory/analytics/trends/

Time-series data for purchases, listings, and sales over a date range.

Trends response fields

FieldTypeDescription
range_daysintegerNumber of days in the range
range_startdateStart of the date range
range_enddateEnd of the date range
purchasesarrayDaily purchase data: { date, count, value }
listingsarrayDaily listing data: { date, count, value }
salesarrayDaily sales data: { date, count, value }
Summary response
{
  "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"
}
Trends response
{
  "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.

EndpointMethodDescription
/api/v1/inventory/export/csv/GETDownload inventory as CSV
/api/v1/inventory/import/csv/POSTUpload and import a CSV file

Export jobs run asynchronously. The API returns a job ID that can be polled for completion.

Export request
curl https://app.instica.com/api/v1/inventory/export/csv/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o inventory_export.csv
Import request
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.

EndpointReturns
GET /api/v1/inventory/types/All item types (vinyl, CD, cassette, etc.)
GET /api/v1/inventory/types/search/?q=vinylSearch item types
GET /api/v1/inventory/types/platform/{slug}/search/?q=vinylSearch 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
Conditions response
[
  { "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

/api/v1/inventory/{uid}/audit-logs/

Returns a chronological audit trail of listing actions for an inventory item — including listings, delistings, price changes, and errors.

Audit log fields

FieldTypeDescription
uidstringAudit log entry identifier
actionstringAction performed (e.g., list, delist, price_update)
sourcestringAction source (api, web, system, extension)
actor_uidstringUID of the user who performed the action
organization_uidstringOrganization UID
listing_uidstringAssociated listing UID
inventory_item_uidstringInventory item UID
inventory_item_titlestringItem title at time of action
platform_slugstringTarget platform
status_beforestringListing status before action
status_afterstringListing status after action
messagestringHuman-readable description
metadataobjectAdditional data (prices, errors, etc.)
request_idstringRequest correlation ID
ip_addressstringClient IP address
user_agentstringClient user agent
severitystringLog severity level
createddatetimeWhen the action occurred
Request
curl https://app.instica.com/api/v1/inventory/\
inv_d4e5f6/audit-logs/ \
  -H "Authorization: Bearer YOUR_TOKEN"
Audit log entry
{
  "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.

EndpointMethodDescription
/api/v1/exports/GETList export jobs
/api/v1/exports/inventory/csv/POSTCreate inventory CSV export
/api/v1/exports/{uid}/GETCheck status / download file

Tip: Poll the job detail endpoint until status changes to completed, then download the file from the response URL.

Create export job
curl -X POST \
  https://app.instica.com/api/v1/exports/inventory/csv/ \
  -H "Authorization: Bearer YOUR_TOKEN"
Check export status
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.

FieldTypeDescription
uidstringUnique identifier (read-only)
titlestringComputed display title (read-only)
namestringManual name (overrides computed title)
userobject{ uid, username, email } (read-only)
organizationobject{ uid, display_name, slug, default_barcode_type } (read-only)
productobjectParent product summary (read-only)
inventory_item_typeobject{ uid, name, slug } (read-only)
condition_itemstringItem condition grade code
condition_item_displaystringHuman-readable condition (read-only)
condition_containerstringContainer/sleeve condition code
condition_container_displaystringHuman-readable container condition (read-only)
condition_commentsstringFree-text condition notes
condition_seller_descriptionstringSeller-facing condition notes
grade_tier_codestringGrade tier code (read-only)
grade_tier_labelstringGrade tier display label (read-only)
statusstringCurrent status code
status_displaystringHuman-readable status (read-only)
price_total_usddecimalTotal listing price
price_item_usddecimalItem-only price
price_shipping_usddecimalShipping price
price_expected_usddecimalExpected/target price
price_purchased_itemdecimalPurchase cost basis
price_for_purchases_shippingdecimalPurchase shipping cost
listing_current_pricedecimalCurrent marketplace price
default_pricing_modelobject{ uid, type, type_display } (read-only)
manual_descriptionstringCustom description
manual_skustringCustom SKU
resolved_skustringBest resolved SKU (read-only)
resolved_sku_sourcestringSKU source (read-only)
assetsarrayAttached images and files (read-only)
days_in_inventoryfloatDays since receipt/purchase/creation (read-only)
days_listedfloatDays since first listed (read-only)
listed_atdatetimeWhen first listed (read-only)
is_deletablebooleanWhether item can be deleted (read-only)
createddatetimeCreation timestamp (read-only)
updateddatetimeLast update timestamp (read-only)
Asset object
{
  "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"
}