Seller Endpoints

These endpoints require the seller token ability and resolve team context from the X-Team-Id header.

Team context

Sellers on Bidyear operate within teams. Pass the team you want to act as via:

X-Team-Id: 42

Omit to use your personal/default team. Use GET /api/v1/me to find your current_team_id.

GET /api/v1/ad-campaigns seller ability

Returns ad campaigns owned by the authenticated user/team.

Query parameters

Param	Description
status	Filter: `draft`, `pending_payment`, `active`, `paused`, `ended`, `cancelled`

Response 200 (item)

{
  "id": 10,
  "name": "Summer Land Blast",
  "status": "active",
  "placement": "search",
  "pricing_model": "flat",
  "budget_cents": 5000,
  "spent_cents": 1200,
  "impressions": 3400,
  "clicks": 87,
  "start_date": "2026-07-01",
  "end_date": "2026-07-31"
}

GET /api/v1/subscriptions/current seller ability

Returns the team's current active subscription plan, or null if no active subscription exists.

Response 200

{
  "success": true,
  "data": {
    "id": 5,
    "plan": {
      "name": "Professional",
      "slug": "professional",
      "price_monthly": 149.00
    },
    "status": "active",
    "current_period_end": "2026-08-01T00:00:00Z",
    "cancel_at_period_end": false
  }
}

Seller auctions & lots

Manage your catalog programmatically. Requires seller ability and team context.

Method	Path	Description
GET	/v1/seller/auctions	List your auctions
POST	/v1/seller/auctions	Create auction
GET	/v1/seller/auctions/{id}	Auction detail
PATCH	/v1/seller/auctions/{id}	Update auction
GET	/v1/seller/lots	List your lots
POST	/v1/seller/lots	Create lot
GET	/v1/seller/lots/{id}	Lot detail
PATCH	/v1/seller/lots/{id}	Update lot

Inventory & settlements

Method	Path	Description
GET	/v1/inventory	List warehouse items
POST	/v1/inventory	Create inventory item
GET	/v1/inventory/aging-summary	Aging bucket summary
POST	/v1/inventory/convert-to-lots	Promote items to lots
GET	/v1/settlements	Seller settlement statements
POST	/v1/ad-campaigns	Create ad campaign
PATCH	/v1/ad-campaigns/{id}	Update ad campaign

Upload photos via POST /api/v1/media (multipart: file, model_type, model_id). See Media.

Webhook subscriptions

Seller accounts can subscribe to outbound webhook events. See the full CRUD and delivery log documentation on the Webhooks page.

Method	Path	Description
GET	/v1/webhook-subscriptions	List your subscriptions
POST	/v1/webhook-subscriptions	Create subscription (returns secret)
GET	/v1/webhook-subscriptions/{id}	Subscription detail
PATCH	/v1/webhook-subscriptions/{id}	Update url/events/is_active
DELETE	/v1/webhook-subscriptions/{id}	Delete subscription
GET	/v1/webhook-subscriptions/{id}/deliveries	Delivery log