Instica API — Orders & Sales

List orders

GET List orders

/api/v1/orders/

Returns a paginated list of orders from all connected marketplaces.

Query parameters

Parameter	Type	Description
`search`	string	Search by order ID, tracking number, buyer name, or item title
`status`	string	`awaiting_shipment`, `shipped`, `completed`, or external status
`platform`	string	Filter by platform slug (e.g., `ebay`, `discogs`)
`ordering`	string	Sort field (prefix `-` for descending)
`page`	integer	Page number (default: 1)
`page_size`	integer	Results per page (default: 25, max: 100)

Response fields

Field	Type	Description
`uid`	string	Order identifier
`order_id`	string	External marketplace order ID (nullable)
`status`	string	Computed: `completed`, `shipped`, `awaiting_shipment`, or external status
`platform`	string	Platform slug
`platform_name`	string	Human-readable platform name
`buyer_name`	string	From shipping address (nullable)
`sale_price`	decimal	Sale amount (nullable)
`marketplace_fee`	decimal	Marketplace fee (nullable)
`platform_fee`	decimal	Platform processing fee (nullable)
`shipping_cost`	decimal	Shipping cost (nullable)
`net_revenue`	decimal	Net revenue after fees (nullable)
`sold_at`	datetime	When the order was placed
`inventory_item_listing`	object	Nested listing + inventory item (see below)
`shipment_tracking_number`	string	Tracking number (nullable)
`shipment_carrier`	string	Carrier code (nullable)
`shipment_status`	string	Shipment status (nullable)
`shipment_address`	object	Buyer address summary (nullable)

Request

curl "https://app.instica.com/api/v1/orders/\
?status=awaiting_shipment\
&platform=ebay\
&ordering=-created" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response — 200 OK

{
  "count": 23,
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "ord_m3n4o5",
      "order_id": "12-34567-89012",
      "status": "awaiting_shipment",
      "platform": "ebay",
      "platform_name": "eBay",
      "buyer_name": "John Doe",
      "sale_price": "34.99",
      "marketplace_fee": "3.50",
      "platform_fee": "1.07",
      "shipping_cost": "5.00",
      "net_revenue": "25.42",
      "sold_at": "2026-02-14T10:30:00Z",
      "inventory_item_listing": {
        "uid": "lst_abc123",
        "platform_slug": "ebay",
        "platform_name": "eBay",
        "status": "sold",
        "listing_url": "https://ebay.com/itm/...",
        "listing_id": "394857201",
        "price": "34.99",
        "inventory_item": {
          "uid": "inv_d4e5f6",
          "title": "Abbey Road - VG+",
          "sku": "PCS-7088-001",
          "condition": "vg_plus",
          "primary_image_url": "https://cdn..."
        }
      },
      "shipment_tracking_number": null,
      "shipment_carrier": null,
      "shipment_status": null,
      "shipment_address": {
        "uid": "addr_xyz",
        "full_name": "John Doe",
        "city": "Los Angeles",
        "postal_code": "90001",
        "country": "US"
      },
      "created": "2026-02-14T10:30:00Z",
      "updated": "2026-02-14T10:30:00Z"
    }
  ]
}

Order detail

GET Order detail

/api/v1/orders/{uid}/

Returns the full order record with complete financial breakdown, shipment details, and label information. The detail view includes all list fields plus the following additional fields:

Additional detail fields

Field	Type	Description
`order_created`	datetime	When the order was created on the marketplace (nullable)
`external_order_status`	string	Raw status from the marketplace platform (nullable)
`platform_order_id`	string	Marketplace-specific order ID (same as `order_id`)
`shipment_service_id`	string	Shipping service identifier (nullable)
`shipment_tracking_created`	datetime	When tracking was created (nullable)
`shipment_rate_detail`	object	Full rate quote data (nullable)
`shipment_rate_retrieval_tried`	boolean	Whether rate retrieval was attempted
`shipment_rate_cheapest_price`	decimal	Cheapest shipping rate found (nullable)
`shipment_rate_cheapest_carrier`	string	Carrier for the cheapest rate (nullable)
`shipment_rate_cheapest_product`	string	Product/service name for cheapest rate (nullable)
`shipment_rate_cheapest_service_id`	string	Service ID for the cheapest rate (nullable)
`label_detail`	object	Label generation details (nullable)
`label_last_updated`	datetime	When the shipping label was last updated (nullable)
`shipment_recipient_detail`	object	Raw recipient data from the marketplace (nullable)
`shipment_recipient_last_updated`	datetime	When recipient details were last synced (nullable)
`shipment_label_url`	URL	Shipping label download URL (nullable)
`shipment_packing_slip_url`	URL	Packing slip download URL (nullable)

Shipping address schema

The shipment_address object contains the full buyer address:

Field	Type	Description
`uid`	string	Address identifier
`name`	string	Recipient name
`email_address`	string	Recipient email (nullable)
`phone_number`	string	Recipient phone (nullable)
`street_number`	string	Street number (nullable)
`street_1`	string	Street address line 1
`street_2`	string	Street address line 2 (nullable)
`city`	string	City
`state_province`	string	State or province
`postal_code`	string	Postal/ZIP code
`country`	string	ISO 3166-1 alpha-2 country code
`raw_address`	string	Original unparsed address from marketplace
`raw_address_parsed`	object	Parsed address components (nullable)

Request

curl https://app.instica.com/api/v1/orders/ord_m3n4o5/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Detail response (shipment fields)

{
  "uid": "ord_m3n4o5",
  "order_id": "12-34567-89012",
  "order_created": "2026-02-14T10:30:00Z",
  "external_order_status": "PAID",
  "platform_order_id": "12-34567-89012",
  "shipment_rate_retrieval_tried": true,
  "shipment_rate_cheapest_price": "4.50",
  "shipment_rate_cheapest_carrier": "usps",
  "shipment_rate_cheapest_product": "Priority Mail",
  "shipment_rate_cheapest_service_id": "usps_priority",
  "label_last_updated": "2026-02-14T12:00:00Z",
  "shipment_label_url": "https://app.instica.com/...",
  "shipment_packing_slip_url": "https://app.instica.com/...",
  "shipment_address": {
    "uid": "addr_xyz",
    "name": "John Doe",
    "email_address": "john@example.com",
    "phone_number": "+15551234567",
    "street_1": "123 Main St",
    "street_2": "Apt 4B",
    "city": "Los Angeles",
    "state_province": "CA",
    "postal_code": "90001",
    "country": "US"
  }
}

Order statistics

GET Order stats

/api/v1/orders/stats/

Returns aggregate order counts and revenue totals across all platforms.

Response fields

Field	Type	Description
`awaiting_shipment`	integer	Orders awaiting shipment
`shipped`	integer	Orders shipped
`completed`	integer	Completed orders
`total`	integer	Total orders
`total_revenue`	decimal	Gross revenue
`total_fees`	decimal	Total marketplace + platform fees
`total_shipping`	decimal	Total shipping costs
`total_net`	decimal	Net revenue after fees & shipping

Request

curl https://app.instica.com/api/v1/orders/stats/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response — 200 OK

{
  "awaiting_shipment": 23,
  "shipped": 8,
  "completed": 412,
  "total": 443,
  "total_revenue": "14892.50",
  "total_fees": "1934.02",
  "total_shipping": "2210.00",
  "total_net": "10748.48"
}

Shipment management

POST Mark as shipped

/api/v1/inventory/{uid}/order/ship/

Updates the order status to shipped and records tracking details.

Request body

Field	Type	Required	Description
`tracking_number`	string	Yes	Carrier tracking number
`carrier`	string	Yes	Carrier code (e.g., `ups`, `usps`, `fedex`)

PUT PATCH Update order

/api/v1/inventory/{uid}/order/

Update shipment fields on an order. All fields are optional (allow_null, allow_blank).

Writable shipment fields

Field	Type	Description
`shipment_service_id`	string	Shipping service identifier
`shipment_tracking_number`	string	Carrier tracking number
`shipment_tracking_created`	datetime	When tracking was created
`shipment_carrier`	string	Carrier code
`shipment_status`	string	Shipment status
`shipment_rate_detail`	object	Full rate quote data
`shipment_rate_retrieval_tried`	boolean	Whether rate retrieval was attempted
`shipment_rate_cheapest_price`	decimal	Cheapest rate price
`shipment_rate_cheapest_carrier`	string	Carrier for cheapest rate
`shipment_rate_cheapest_product`	string	Product name for cheapest rate
`shipment_rate_cheapest_service_id`	string	Service ID for cheapest rate
`label_detail`	object	Label generation details
`label_last_updated`	datetime	Label last updated timestamp
`shipment_recipient_detail`	object	Raw recipient data
`shipment_recipient_last_updated`	datetime	Recipient details last synced
`shipment_address`	object	Nested address update (same schema as detail)

Tip: Use GET /api/v1/inventory/choices/shipment-carriers/ for valid carrier codes.

Mark as shipped

curl -X POST \
  https://app.instica.com/api/v1/inventory/\
inv_d4e5f6/order/ship/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups"
  }'

Update order shipment

curl -X PATCH \
  https://app.instica.com/api/v1/inventory/\
inv_d4e5f6/order/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_tracking_number": "1Z999AA10123456784",
    "shipment_carrier": "ups",
    "shipment_status": "shipped"
  }'

Sales analytics

GET Sales time series

/api/v1/analytics/sales/

Returns sales data as a time series with configurable period and range.

Query parameters

Parameter	Type	Default	Description
`period`	string	`day`	`day`, `week`, or `month`
`days`	integer	30	Range in days (1–365)

Request

curl "https://app.instica.com/api/v1/analytics/sales/\
?period=week&days=90" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": [
    {
      "date": "2025-02-03",
      "value": 12,
      "revenue": 489.50,
      "orders": 12
    },
    {
      "date": "2025-02-10",
      "value": 8,
      "revenue": 312.00,
      "orders": 8
    }
  ],
  "total": 48,
  "period": "week",
  "granularity": "day",
  "total_revenue": 2140.50
}

Platform analytics

GET Platform breakdown

/api/v1/analytics/platforms/

Revenue and order count broken down by selling platform.

Query parameters

Parameter	Type	Default	Description
`days`	integer	30	Range in days (1–365)

Response

{
  "data": [
    {
      "platform": "ebay",
      "platform_name": "eBay",
      "count": 35,
      "revenue": 1420.50
    },
    {
      "platform": "discogs",
      "platform_name": "Discogs",
      "count": 13,
      "revenue": 720.00
    }
  ],
  "platforms": [
    { "name": "eBay", "value": 35 },
    { "name": "Discogs", "value": 13 }
  ],
  "total_count": 48,
  "total_revenue": 2140.50
}

Inventory funnel

GET Inventory lifecycle funnel

/api/v1/analytics/funnel/

Snapshot of inventory items at each lifecycle stage.

Response

{
  "draft": 45,
  "ready_to_sell": 60,
  "listed": 120,
  "sold": 65,
  "total": 290,
  "stages": [
    { "stage": "draft", "count": 45 },
    { "stage": "ready_to_sell", "count": 60 },
    { "stage": "listed", "count": 120 },
    { "stage": "sold", "count": 65 }
  ]
}

Revenue analytics

GET Revenue summary

/api/v1/analytics/revenue/

Revenue totals with period-over-period comparison.

Query parameters

Parameter	Type	Default	Description
`days`	integer	30	Range in days (1–365)

Includes a previous_period object with the same metrics for the prior equivalent period, enabling trend analysis.

Response

{
  "total_revenue": 2140.50,
  "average_order_value": 44.59,
  "total_orders": 48,
  "previous_period": {
    "total_revenue": 1850.00,
    "average_order_value": 41.11,
    "total_orders": 45
  }
}

Inventory analytics

GET Inventory metrics

/api/v1/analytics/inventory/

Current inventory value and count broken down by status.

Response

{
  "total_items": 245,
  "total_value": 8500.00,
  "average_item_value": 34.69,
  "by_status": {
    "ready-to-sell": {
      "count": 60,
      "value": 2100.00
    },
    "listed": {
      "count": 120,
      "value": 5400.00
    },
    "sold": {
      "count": 65,
      "value": 1000.00
    }
  }
}

Top categories

GET Top categories

/api/v1/analytics/categories/top/

Best-performing product categories by revenue.

Query parameters

Parameter	Type	Default	Description
`days`	integer	30	Range in days
`limit`	integer	10	Number of categories (1–50)

Response

{
  "categories": [
    {
      "name": "Vinyl",
      "count": 28,
      "revenue": 1120.00
    },
    {
      "name": "CD",
      "count": 15,
      "revenue": 420.00
    }
  ]
}

Activity analytics

GET Activity time series

/api/v1/analytics/activity/

Returns activity events over time — listings created, items sold, imports completed, and other actions.

GET Activity heatmap

/api/v1/analytics/activity/heatmap/

Returns a heatmap of activity by day-of-week and hour, useful for identifying peak selling hours.

GET Recent activity feed

/api/v1/activity/recent/

Returns the most recent activity events (listings, sales, imports). Use /api/v1/activity/stats/ for aggregate activity counts.

Activity endpoints

# Time series
curl https://app.instica.com/api/v1/analytics/activity/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Heatmap
curl https://app.instica.com/api/v1/analytics/activity/heatmap/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Recent feed
curl https://app.instica.com/api/v1/activity/recent/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Activity stats
curl https://app.instica.com/api/v1/activity/stats/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Reports

Generate and download business reports for inventory analysis, valuation, and profit tracking. Most reports support json and pdf output via the format query parameter.

Endpoint	Description	Parameters
`GET /api/v1/reports/`	List available report types	—
`GET .../inventory-summary/`	Inventory summary with financials	`start_date`, `end_date`, `format`
`GET .../inventory-valuation/`	Full valuation by status & category	`include_sold`, `format`
`GET .../profit-loss/`	Profit & loss with monthly breakdown	`start_date`, `end_date`, `format`
`GET .../aging/`	Inventory aging with time buckets	`format`
`GET .../export/csv/`	CSV export with field selection	`status`, `fields`

Base path: /api/v1/reports/

Inventory summary — financials sub-object

The /api/v1/reports/inventory-summary/ endpoint returns a financials block with:

Field	Type	Description
`total_purchase_cost`	decimal	Sum of all purchase costs
`total_listed_value`	decimal	Sum of current listing values
`average_purchase_cost`	decimal	Mean purchase cost per item
`average_listed_price`	decimal	Mean listing price per item
`potential_profit`	decimal	Estimated unrealized profit

Export jobs

Large exports run asynchronously and are tracked via export job endpoints:

Endpoint	Method	Description
`/api/v1/exports/`	GET	List export jobs
`/api/v1/exports/inventory/csv/`	POST	Create CSV export job
`/api/v1/exports/{uid}/`	GET	Download or check export status

Profit & loss response

{
  "metadata": {
    "report_type": "profit_loss",
    "generated_at": "2025-03-01T12:00:00Z",
    "date_range_start": "2025-01-01",
    "date_range_end": "2025-03-01"
  },
  "summary": {
    "items_sold": 65,
    "total_sales": "4200.00",
    "total_cost": "1850.00",
    "total_shipping": "520.00",
    "total_profit": "1830.00",
    "average_profit_per_item": "28.15",
    "profit_margin": 0.436
  },
  "top_profitable": [
    {
      "uid": "inv_001",
      "title": "Abbey Road - NM",
      "sale_price": "89.99",
      "cost": "12.00",
      "profit": "77.99"
    }
  ],
  "monthly_breakdown": [
    {
      "month": "2025-01",
      "sales": "1400.00",
      "cost": "620.00",
      "shipping": "175.00",
      "profit": "605.00",
      "count": 22
    }
  ]
}

Inventory valuation response

{
  "totals": {
    "item_count": 245,
    "total_cost": "3250.00",
    "total_value": "8500.00",
    "unrealized_gain": "5250.00"
  },
  "by_status": [
    {
      "status": "listed",
      "count": 120,
      "total_cost": "1800.00",
      "total_value": "5400.00"
    }
  ],
  "top_items": [
    {
      "uid": "inv_001",
      "title": "Abbey Road - NM",
      "value": "89.99",
      "cost": "12.00",
      "status": "listed"
    }
  ]
}

Aging report response

{
  "summary": {
    "total_items": 180,
    "total_value": "6500.00",
    "average_age_days": 42.5
  },
  "buckets": [
    {
      "bucket": "0-30 days",
      "min_days": 0,
      "max_days": 30,
      "count": 80,
      "total_value": "3200.00",
      "total_cost": "1200.00"
    },
    {
      "bucket": "31-60 days",
      "min_days": 31,
      "max_days": 60,
      "count": 50,
      "total_value": "1800.00",
      "total_cost": "700.00"
    }
  ],
  "oldest_items": [
    {
      "uid": "inv_old001",
      "title": "Rare Jazz LP",
      "created_at": "2024-06-15T...",
      "age_days": 258,
      "value": "120.00",
      "status": "listed"
    }
  ]
}

Previous Inventory API Next Marketplace & Import →

Orders & Sales API

List orders

GET List orders

Query parameters

Response fields

Order detail

GET Order detail

Additional detail fields

Shipping address schema

Order statistics

GET Order stats

Response fields

Shipment management

POST Mark as shipped

Request body

PUT PATCH Update order

Writable shipment fields

Sales analytics

GET Sales time series

Query parameters

Platform analytics

GET Platform breakdown

Query parameters

Inventory funnel

GET Inventory lifecycle funnel

Revenue analytics

GET Revenue summary

Query parameters

Inventory analytics

GET Inventory metrics

Top categories

GET Top categories

Query parameters

Activity analytics

GET Activity time series

GET Activity heatmap

GET Recent activity feed

Reports

Inventory summary — financials sub-object

Export jobs