API · Products
Products API
Products represent catalog items in your account (e.g., an album title). Each product can own multiple inventory items and marketplace presences.
List products
GET List products
/api/v1/products/
Returns a paginated list of the authenticated user's products with nested inventory summaries and marketplace presences.
Query parameters
| Parameter | Type | Description |
|---|---|---|
search | string | Full-text search across title, catalog number, tags, marketplace description, license type, license notes, artist name, label name, and digital asset filenames |
has_inventory | boolean | Filter to products that have (or lack) any inventory items |
has_available_inventory | boolean | Filter to products with available (received/ready) inventory |
status | string | Filter by inventory item status (comma-separated or repeated) |
type | string | Product type: physical, digital, digital-report, nft |
tags | string | Comma-separated, OR logic, case-insensitive partial match |
uploadable_to_redbubble | boolean | Digital products with Redbubble eligibility |
ordering | string | Sort field — see ordering options below |
page | integer | Page number (default: 1) |
page_size | integer | Results per page (default: 15, max: 100) |
Ordering options
| Value | Description |
|---|---|
title / -title | Alphabetical by title |
created / -created | Date created (default: -created) |
updated / -updated | Date last modified |
artist__name | Alphabetical by artist name |
listed_first | Products with active listings first |
unlisted_first | Products without listings first |
price_high_low | Sort by price descending |
price_low_high | Sort by price ascending |
most_inventory | Most inventory items first |
least_inventory | Fewest inventory items first |
Request
curl "https://app.instica.com/api/v1/products/\
?search=beatles\
&has_inventory=true\
&ordering=-updated\
&page_size=10" \
-H "Authorization: Bearer YOUR_TOKEN"Response — 200 OK
{
"count": 12,
"next": ".../api/v1/products/?page=2",
"previous": null,
"results": [
{
"uid": "prod_a1b2c3",
"title": "Abbey Road",
"type": "physical",
"type_display": "Physical",
"artist": {
"uid": "art_x1y2",
"name": "The Beatles"
},
"music_label": {
"uid": "lbl_m1n2",
"name": "Apple Records"
},
"catalog_number": "PCS 7088",
"sku": null,
"upc": "0077774644020",
"formats": ["Vinyl"],
"year": "1969",
"tags": ["classic-rock", "uk-pressing"],
"product_image": "https://cdn...",
"total_inventory_count": 3,
"listed_inventory_count": 1,
"available_inventory_count": 2,
"price_computed_usd": "29.99",
"price_override_usd": null,
"has_primary_asset": false,
"inventory_items": [ ... ],
"available_platforms": [ ... ],
"marketplace_presences": [],
"redbubble_presence": {
"exists": false,
"external_url": null,
"external_listing_id": null,
"status": null
},
"created": "2025-01-15T10:30:00Z",
"updated": "2025-02-10T14:22:00Z"
}
]
}Create a product
POST Create product
/api/v1/products/
Create a new product. Only title is required — all other fields are optional.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Product title (validated non-empty) |
type | string | No | Default: digital. Options: physical, digital, digital-report, nft |
marketplace_description | string | No | Description for marketplace listings |
tags | string[] | No | Array of tags (max 100 chars each). Default: [] |
license_type | string | No | License type (from product license choices) |
license_notes | string | No | License details text |
price_override_usd | decimal | No | Manual price override |
media_type | string | No | Media type classification |
is_mature_content | boolean | No | Flag for mature content |
default_visibility | string | No | Default listing visibility |
default_shop_product | boolean | No | Show in shop by default |
background_color | string | No | Product display background color |
enabled_product_types | object | No | Enabled product type configuration (JSON) |
collections | object | No | Collection assignments (JSON) |
Request
curl -X POST https://app.instica.com/api/v1/products/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Abbey Road",
"type": "physical",
"marketplace_description": "Original 1969 UK pressing.",
"tags": ["classic-rock", "uk-pressing"],
"price_override_usd": "29.99"
}'Response — 201 Created
{
"uid": "prod_new123",
"title": "Abbey Road",
"type": "physical",
"type_display": "Physical",
"artist": null,
"music_label": null,
"catalog_number": null,
"tags": ["classic-rock", "uk-pressing"],
"price_override_usd": "29.99",
"total_inventory_count": 0,
"listed_inventory_count": 0,
"available_inventory_count": 0,
"inventory_items": [],
"marketplace_presences": [],
"created": "2025-03-01T09:00:00Z",
"updated": "2025-03-01T09:00:00Z"
}Get a single product
GET Product detail
/api/v1/products/{uid}/
Returns the full product object including all inventory items, marketplace presences, metadata, and computed fields. Same schema as the list response.
Scope: Products are user-scoped. You can only access products that belong to your organization. Requesting another user's product returns 404 Not Found, not 403.
Request
curl https://app.instica.com/api/v1/products/prod_a1b2c3/ \
-H "Authorization: Bearer YOUR_TOKEN"Update a product
PATCH Update product
/api/v1/products/{uid}/
Partially update a product. Only include the fields you want to change.
Writable fields
| Field | Type | Notes |
|---|---|---|
title | string | Allow blank/null |
catalog_number | string | Allow blank/null |
year | date | Accepts YYYY or YYYY-MM-DD. Nullable. |
music_label_name | string | Write-only. Get-or-create a music label by name. |
price_override_usd | decimal | Must be positive or null |
marketplace_description | string | Description for listings |
tags | string[] | Array of tags (max 100 chars each). Allow empty. |
license_type | string | Allow blank/null |
license_notes | string | Allow blank/null |
media_type | string | Media type classification |
is_mature_content | boolean | Mature content flag |
default_visibility | string | Default listing visibility |
default_shop_product | boolean | Show in shop |
background_color | string | Display background color |
enabled_product_types | object | JSON configuration |
collections | object | JSON collection assignments |
Note: The music_label_name field is write-only. It performs a get-or-create — if a label with that name already exists, the product is linked to it. Otherwise, a new label is created.
Request
curl -X PATCH \
https://app.instica.com/api/v1/products/prod_a1b2c3/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Abbey Road (Remastered)",
"year": "1969",
"music_label_name": "Apple Records",
"catalog_number": "PCS 7088",
"marketplace_description": "Original UK pressing.",
"tags": ["classic-rock", "remastered"],
"price_override_usd": "34.99"
}'Response — 200 OK
{
"uid": "prod_a1b2c3",
"title": "Abbey Road (Remastered)",
"music_label": {
"uid": "lbl_m1n2",
"name": "Apple Records"
},
"catalog_number": "PCS 7088",
"year": "1969",
"tags": ["classic-rock", "remastered"],
"price_override_usd": "34.99",
"updated": "2025-03-01T10:15:00Z"
}Delete a product
DELETE Delete product
/api/v1/products/{uid}/
Permanently delete a product. Associated inventory items and marketplace presences are also removed.
Returns 204 No Content on success.
Request
curl -X DELETE \
https://app.instica.com/api/v1/products/prod_a1b2c3/ \
-H "Authorization: Bearer YOUR_TOKEN"Upload product image
POST Upload image
/api/v1/products/{uid}/image/
Upload or replace the primary product image. Send as multipart/form-data.
The product_image field in the response is resolved with priority: uploaded image → first inventory asset → marketplace presence image.
Request
curl -X POST \
https://app.instica.com/api/v1/products/prod_a1b2c3/image/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "image=@/path/to/album-cover.jpg"Marketplace presences
Marketplace presences track where a product is represented on connected selling platforms (eBay, Discogs, etc.).
| Endpoint | Method | Description |
|---|---|---|
.../marketplace-presences/ | GET | List all presences for a product |
.../marketplace-presences/ | POST | Create a presence record |
.../marketplace-presences/{id}/ | PATCH | Update a presence record |
.../marketplace-presences/{id}/ | DELETE | Remove a presence record |
Base path: /api/v1/products/{uid}/marketplace-presences/
Create/update fields
| Field | Type | Notes |
|---|---|---|
platform_uid | string | Write-only. Set platform by UID. |
external_listing_id | string | Marketplace listing identifier |
external_url | URL | Link to the marketplace listing |
status | string | Listing status on platform |
listing_price | decimal | Price in listing currency |
listing_currency | string | Currency code (e.g., USD) |
listing_price_usd | decimal | Price in USD |
is_selling_enabled | boolean | Whether selling is active |
Create presence
curl -X POST \
https://app.instica.com/api/v1/products/prod_a1b2c3/\
marketplace-presences/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"platform_uid": "plat_ebay",
"external_listing_id": "394857201",
"external_url": "https://ebay.com/itm/394857201",
"listing_price_usd": "34.99",
"listing_currency": "USD",
"status": "active",
"is_selling_enabled": true
}'List presences response
[
{
"id": 1,
"platform": {
"uid": "plat_ebay",
"name": "eBay",
"slug": "ebay"
},
"external_listing_id": "394857201",
"external_url": "https://ebay.com/itm/...",
"status": "active",
"listing_price": "34.99",
"listing_currency": "USD",
"listing_price_usd": "34.99",
"is_selling_enabled": true,
"price_last_updated": "2025-02-10T14:22:00Z",
"created_at": "2025-01-20T08:00:00Z",
"updated_at": "2025-02-10T14:22:00Z"
}
]Digital assets
Digital products can have downloadable assets (files) attached. These are used for digital fulfillment — when a customer purchases, they receive a download link.
| Endpoint | Method | Description |
|---|---|---|
/api/v1/products/{uid}/digital-assets/ | GET | List digital assets for a product |
/api/v1/products/{uid}/digital-assets/ | POST | Upload a digital asset |
/api/v1/digital/assets/{uid}/ | GET | Get asset details |
/api/v1/digital/assets/{uid}/ | PATCH | Update asset metadata |
/api/v1/digital/assets/{uid}/ | DELETE | Delete a digital asset |
Digital fulfillment
| Endpoint | Method | Description |
|---|---|---|
/api/v1/digital/fulfill/ | POST | Fulfill a digital purchase (send download email) |
/api/v1/digital/purchases/ | GET | List digital purchases |
/api/v1/digital/purchases/{uid}/ | GET | Purchase detail |
/api/v1/digital/purchases/{uid}/resend-email/ | POST | Resend download email |
/api/v1/digital/purchases/{uid}/download-logs/ | GET | View download history |
Public download (no auth required)
| Endpoint | Method | Description |
|---|---|---|
/api/v1/digital/download/{token}/ | GET | Public download page |
/api/v1/digital/download/{token}/{asset_uid}/ | GET | Download a specific asset file |
Upload digital asset
curl -X POST \
https://app.instica.com/api/v1/products/\
prod_a1b2c3/digital-assets/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/album.zip" \
-F "display_name=Full Album Download" \
-F "description=FLAC files, 24-bit"Fulfill a purchase
curl -X POST \
https://app.instica.com/api/v1/digital/fulfill/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_uid": "prod_a1b2c3",
"buyer_email": "buyer@example.com"
}'Product response schema
Complete field reference for the product object returned by list and detail endpoints.
| Field | Type | Description |
|---|---|---|
uid | string | Unique identifier (read-only) |
title | string | Product title |
type | string | physical, digital, digital-report, or nft |
type_display | string | Human-readable type label (read-only) |
artist | object | Nested { uid, name } (read-only) |
music_label | object | Nested { uid, name } (read-only) |
catalog_number | string | Catalog/release number (nullable) |
sku | string | Custom SKU (nullable) |
upc | string | Universal Product Code (nullable) |
formats | array | Media formats, e.g. ["Vinyl", "CD"] (nullable) |
year | date | Release year (nullable) |
marketplace_description | string | Description used for marketplace listings (nullable) |
license_type | string | License type code (nullable) |
license_notes | string | License detail text (nullable) |
tags | string[] | Array of tags |
media_type | string | Media type classification (nullable) |
is_mature_content | boolean | Mature content flag |
default_visibility | string | Default listing visibility (nullable) |
default_shop_product | boolean | Show in shop by default |
background_color | string | Display background color (nullable) |
enabled_product_types | object | Enabled product types config (nullable) |
collections | object | Collection assignments (nullable) |
price_computed_usd | decimal | System-computed price (nullable) |
price_override_usd | decimal | User-set price override (nullable) |
resolved_identifier | string | Best resolved identifier value (read-only, nullable) |
resolved_identifier_source | string | Source of the resolved identifier (read-only, nullable) |
product_image | URL | Primary product image URL (read-only, nullable) |
total_inventory_count | integer | Total inventory items (read-only, computed) |
listed_inventory_count | integer | Items currently listed (read-only, computed) |
available_inventory_count | integer | Items available for sale (read-only, computed) |
has_primary_asset | boolean | Whether product has a primary digital asset (read-only) |
inventory_items | array | Nested inventory item summaries (read-only) |
available_platforms | array | Platforms this product can be listed on (read-only) |
marketplace_presences | array | Active marketplace presence records (read-only) |
redbubble_presence | object | { exists, external_url, external_listing_id, status } (read-only) |
metadata | object | { external_id, external_id_title } (read-only, nullable) |
created | datetime | Creation timestamp (read-only) |
updated | datetime | Last update timestamp (read-only) |
available_platforms entry
{
"uid": "plat_ebay",
"name": "eBay",
"slug": "ebay",
"display_name": "eBay",
"platform_type": "marketplace",
"supports_digital": false,
"supports_api_connection": true,
"connection_type": "oauth"
}Nested inventory item schema
Each product's inventory_items array contains summary objects with these fields:
| Field | Type | Description |
|---|---|---|
uid | string | Inventory item identifier |
title | string | Computed title |
status | string | Current status code |
status_display | string | Human-readable status |
condition_item | string | Item condition grade code |
condition_item_display | string | Human-readable condition (e.g., "VG+") |
condition_container | string | Container/sleeve condition code |
condition_container_display | string | Human-readable container condition |
condition_comments | string | Free-text condition notes |
price_total_usd | decimal | Total price in USD |
listing_current_price | decimal | Current listing price |
price_expected_usd | decimal | Expected sale price |
resolved_sku | string | Best resolved SKU value |
resolved_sku_source | string | Source of the resolved SKU |
grade_tier_code | string | Grade tier code |
grade_tier_label | string | Grade tier display label |
created | datetime | Creation timestamp |
updated | datetime | Last update timestamp |
inventory_items entry
{
"uid": "inv_d4e5f6",
"title": "Abbey Road — VG+",
"status": "ready-to-sell",
"status_display": "Ready to Sell",
"condition_item": "vg_plus",
"condition_item_display": "VG+",
"condition_container": "vg",
"condition_container_display": "VG",
"condition_comments": "Light surface marks",
"price_total_usd": "34.99",
"listing_current_price": "34.99",
"price_expected_usd": "39.99",
"resolved_sku": "PCS-7088-001",
"resolved_sku_source": "manual",
"grade_tier_code": "good",
"grade_tier_label": "Good",
"created": "2025-01-15T10:30:00Z",
"updated": "2025-02-10T14:22:00Z"
}Nested marketplace presence schema
Each entry in marketplace_presences tracks a product's representation on a specific selling platform.
| Field | Type | Description |
|---|---|---|
id | integer | Presence record ID |
platform | object | Nested { uid, name, slug } |
external_listing_id | string | Marketplace listing identifier |
external_url | URL | Link to the marketplace listing |
status | string | Listing status |
listing_price | decimal | Price in listing currency |
listing_currency | string | Currency code |
listing_price_usd | decimal | Price in USD |
is_selling_enabled | boolean | Whether selling is active |
price_last_updated | datetime | When price was last synced |
last_checked_at | datetime | Last platform sync check |
created_at | datetime | Presence creation timestamp |
updated_at | datetime | Last update timestamp |
marketplace_presences entry
{
"id": 1,
"platform": {
"uid": "plat_discogs",
"name": "Discogs",
"slug": "discogs"
},
"external_listing_id": "28457123",
"external_url": "https://discogs.com/sell/...",
"status": "active",
"listing_price": "29.99",
"listing_currency": "USD",
"listing_price_usd": "29.99",
"is_selling_enabled": true,
"price_last_updated": "2025-02-10T14:22:00Z",
"last_checked_at": "2025-02-11T06:00:00Z",
"created_at": "2025-01-20T08:00:00Z",
"updated_at": "2025-02-10T14:22:00Z"
}