Instica API — Marketplace & Import

Supported platforms

Instica supports the following selling platforms for inventory sync and cross-channel listing:

Platform	Connection	Import	List / Delist	Order sync
eBay	OAuth	Yes	Yes	Yes
Discogs	OAuth	Yes	Yes	Yes
Etsy	OAuth	Yes	Yes	Yes
Shopify	OAuth	Yes	Yes	Yes
Redbubble	Extension	Scrape	Manual	No
TeePublic	Extension	Scrape	Manual	No
Society6	Extension	Scrape	Manual	No

OAuth-connected platforms support full two-way sync — listings, orders, and inventory levels stay in sync automatically.

Extension-based platforms (Redbubble, TeePublic, Society6) use the Instica browser extension to scrape listing data from the marketplace website.

List available platforms

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

Response

[
  {
    "uid": "plt_abc",
    "name": "eBay",
    "slug": "ebay",
    "url": "https://ebay.com",
    "is_selling_active": true,
    "connection_url": "/accounts/ebay/login/"
  },
  {
    "uid": "plt_def",
    "name": "Discogs",
    "slug": "discogs",
    "url": "https://discogs.com",
    "is_selling_active": true,
    "connection_url": "/accounts/discogs/login/"
  }
]

Connection flow (OAuth)

Marketplace connections use OAuth 2.0. The flow works as follows:

Initiate — Open a browser/webview to the provider's OAuth login URL.
Authorize — The user grants access on the marketplace's site.
Callback — The marketplace redirects back to Instica, which stores the connection tokens.
Verify — Confirm in the UI that the provider shows as connected.

iOS OAuth notes

On iOS, use ASWebAuthenticationSession for provider authorization and handle the app callback via your configured URL scheme.

OAuth flow (high-level)

1) Open provider OAuth page
2) User authorizes access
3) Provider redirects back to app
4) Confirm connection status in UI

Create import job

POST Create import job

/api/v1/marketplace/import/jobs/create/

Create an import job to pull inventory from a connected marketplace. Jobs run asynchronously.

Request body

Field	Type	Required	Description
`seller_account_uid`	string	Yes	UID of the connected marketplace account
`marketplace`	string	Yes	`discogs`, `ebay`, or `shopify`

POST Quick import

/api/v1/marketplace/{platform}/import/

Shorthand to trigger import for a specific platform. Automatically resolves the seller account.

Create import job

curl -X POST \
  https://app.instica.com/api/v1/marketplace/\
import/jobs/create/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seller_account_uid": "sa_abc123",
    "marketplace": "ebay"
  }'

Quick import (shorthand)

curl -X POST \
  https://app.instica.com/api/v1/marketplace/\
ebay/import/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Import lifecycle

After creating an import job, use these endpoints to manage its lifecycle:

GET List import jobs

/api/v1/marketplace/import/jobs/

Returns the last 50 import jobs. Filter by marketplace or status.

GET Job detail

/api/v1/marketplace/import/jobs/{uid}/

Poll this endpoint to track import progress via progress_percentage.

POST Preview import

/api/v1/marketplace/import/preview/

Preview what the import will produce before starting. Returns 202 (async).

Preview / start request body

Field	Type	Required	Description
`job_uid`	string	Yes	Import job UID
`status_filter`	string	No	Only process items with this status
`limit`	integer	No	Max items to process

POST Start import

/api/v1/marketplace/import/start/

Begin processing the import. Returns 202 (async).

Start request additional field

Field	Type	Default	Description
`skip_conflicts`	boolean	false	Auto-skip conflicting items

Check job progress

curl https://app.instica.com/api/v1/marketplace/\
import/jobs/job_p6q7r8/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Job response

{
  "id": "job_p6q7r8",
  "marketplace": "ebay",
  "status": "in_progress",
  "total_listings_found": 150,
  "items_imported": 82,
  "items_skipped": 0,
  "items_failed": 3,
  "items_conflicted": 2,
  "has_issues": true,
  "issue_summary": "3 failed, 2 conflicts",
  "progress_percentage": 58.0,
  "error_message": null,
  "created_at": "2026-02-15T09:00:00Z",
  "started_at": "2026-02-15T09:00:05Z",
  "completed_at": null
}

Start import

curl -X POST \
  https://app.instica.com/api/v1/marketplace/\
import/start/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_uid": "job_p6q7r8",
    "skip_conflicts": false
  }'

# 202 Accepted

Import issues & conflicts

GET List job issues

/api/v1/marketplace/import/jobs/{uid}/issues/

Paginated list of failed or conflicting items. Filter by status (failed or conflict). Default page size: 20, max: 100.

Import item fields

Field	Type	Description
`id`	string	Item UID
`external_listing_id`	string	Marketplace listing ID
`external_sku`	string	Marketplace SKU
`status`	string	`imported`, `failed`, `conflict`, `skipped`
`listing_title`	string	Title from the marketplace
`listing_price`	decimal	Listed price (nullable)
`conflict_type`	string	Type of conflict (nullable)
`conflict_details`	string	Conflict description (nullable)
`error_message`	string	Error details (nullable)
`error_code`	string	Error code (nullable)
`resolution`	string	How the conflict was resolved
`created_inventory_item_uid`	string	UID of created item (nullable)
`processed_at`	datetime	When the item was processed (nullable)

POST Resolve conflict

/api/v1/marketplace/import/jobs/{uid}/items/{item_uid}/resolve/

Resolve a specific conflict item.

POST Retry failed items

/api/v1/marketplace/import/jobs/{uid}/retry-failed/

Retry all failed items in the job.

POST Skip all conflicts

/api/v1/marketplace/import/jobs/{uid}/skip-all-conflicts/

Bulk skip all remaining conflicted items.

List issues

curl "https://app.instica.com/api/v1/marketplace/\
import/jobs/job_p6q7r8/issues/\
?status=conflict" \
  -H "Authorization: Bearer YOUR_TOKEN"

Issue item response

{
  "count": 2,
  "results": [
    {
      "id": "item_xyz",
      "external_listing_id": "394857201",
      "external_sku": "PCS-7088-001",
      "status": "conflict",
      "listing_title": "Abbey Road - VG+",
      "listing_price": "34.99",
      "conflict_type": "duplicate_sku",
      "conflict_details":
        "SKU matches existing item inv_d4e5f6",
      "error_message": null,
      "error_code": null,
      "resolution": "pending",
      "created_inventory_item_uid": null,
      "processed_at": "2026-02-15T09:05:00Z"
    }
  ]
}

Resolve conflict

curl -X POST \
  https://app.instica.com/api/v1/marketplace/\
import/jobs/job_p6q7r8/items/item_xyz/resolve/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Retry all failed

curl -X POST \
  https://app.instica.com/api/v1/marketplace/\
import/jobs/job_p6q7r8/retry-failed/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Import job response schema

All import job endpoints return this shape:

Field	Type	Description
`id`	string	Job UID
`marketplace`	string	Platform slug
`status`	string	`pending`, `in_progress`, `completed`, `failed`
`total_listings_found`	integer	Total listings discovered on the platform
`items_imported`	integer	Successfully imported count
`items_skipped`	integer	Skipped items count
`items_failed`	integer	Failed items count
`items_conflicted`	integer	Conflicting items count
`has_issues`	boolean	Whether any items failed or conflicted
`issue_summary`	string	Human-readable issue summary
`progress_percentage`	float	0.0 – 100.0
`error_message`	string	Job-level error (nullable)
`created_at`	datetime	When the job was created
`started_at`	datetime	When processing began (nullable)
`completed_at`	datetime	When the job finished (nullable)

Completed job

{
  "id": "job_p6q7r8",
  "marketplace": "ebay",
  "status": "completed",
  "total_listings_found": 150,
  "items_imported": 145,
  "items_skipped": 2,
  "items_failed": 3,
  "items_conflicted": 0,
  "has_issues": true,
  "issue_summary": "3 items failed",
  "progress_percentage": 100.0,
  "error_message": null,
  "created_at": "2026-02-15T09:00:00Z",
  "started_at": "2026-02-15T09:00:05Z",
  "completed_at": "2026-02-15T09:12:30Z"
}

Listing management

Once platforms are connected, list and delist inventory items programmatically. See the Inventory API — Listings section for full per-item listing documentation.

Endpoint	Method	Description
`.../{uid}/platforms/{slug}/list/`	POST	List on a platform
`.../{uid}/platforms/{slug}/delist/`	POST	Delist from a platform
`/api/v1/inventory/bulk/list/`	POST	Bulk list items
`/api/v1/inventory/bulk/delist/`	POST	Bulk delist items

Base path for per-item endpoints: /api/v1/inventory/

Prerequisites for listing: The user must have (1) an active subscription, (2) a primary address on file, and (3) a valid connection to the target marketplace. Missing any of these returns 402 or 400 with a descriptive error.

List an item 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 '{
    "price": "34.99"
  }'

Response

{
  "status": "success",
  "listing_url": "https://ebay.com/itm/394857201",
  "listing_id": "394857201"
}

Bulk delist

curl -X POST \
  https://app.instica.com/api/v1/inventory/\
bulk/delist/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uids": ["inv_001", "inv_002", "inv_003"],
    "platforms": ["ebay", "discogs"]
  }'

Previous Orders & Sales Next User & Account →

Marketplace & Import API

Supported platforms

Connection flow (OAuth)

iOS OAuth notes

Create import job

POST Create import job

Request body

POST Quick import

Import lifecycle

GET List import jobs

GET Job detail

POST Preview import

Preview / start request body

POST Start import

Start request additional field

Import issues & conflicts

GET List job issues

Import item fields

POST Resolve conflict

POST Retry failed items

POST Skip all conflicts

Import job response schema

Listing management