Pricing API

REST API endpoints for managing pricing rules, triggering repricing, and reading recommendations.

Overview

The Pricing API provides programmatic access to the NexusCommerce pricing engine: create and manage pricing rules, trigger repricing jobs, and read AI-generated price recommendations. All endpoints require the pricing:read or pricing:write scope.

Endpoints

List Pricing Rules

GET /api/pricing/rules

Example Response:

{
  "data": [
    {
      "id": "rule_01HX...",
      "name": "Global Floor Price",
      "type": "floor",
      "value": 9.99,
      "value_type": "fixed",
      "applies_to": "all",
      "marketplace": "all",
      "priority": 1,
      "is_active": true
    }
  ]
}

Create Pricing Rule

POST /api/pricing/rules

Required scope: pricing:write

Request Body:

{
  "name": "Electronics Floor Price",
  "type": "floor",
  "value": 19.99,
  "value_type": "fixed",
  "applies_to": "category",
  "category": "Electronics",
  "marketplace": "all",
  "priority": 2
}

Rule types: floor, ceiling, competitor_match, buy_box_target, margin_target

Update Pricing Rule

PATCH /api/pricing/rules/:ruleId

Required scope: pricing:write

Delete Pricing Rule

DELETE /api/pricing/rules/:ruleId

Required scope: pricing:write

Trigger Repricing

POST /api/pricing/recalculate

Required scope: pricing:write

Dispatch a pricing_recalculate AI job for specified SKUs.

Request Body:

{
  "skus": ["SKU-001", "SKU-002"],
  "marketplace": "amazon_us",
  "apply": false
}

Set "apply": true to automatically apply recommendations without returning them for review. Set "apply": false (default) to return recommendations for inspection.

Response:

{
  "data": {
    "job_id": "job_01HX...",
    "status": "queued",
    "sku_count": 2,
    "estimated_completion_seconds": 30
  }
}

Poll GET /api/ai-jobs/:jobId for completion.

Get Repricing Recommendations

GET /api/pricing/recommendations

Query Parameters:

Parameter	Type	Description
status	string	`pending`, `applied`, `dismissed`
marketplace	string	Filter by marketplace
min_confidence	number	Minimum confidence score (0.0–1.0)

Example Response:

{
  "data": [
    {
      "id": "rec_01HX...",
      "sku": "SKU-001",
      "marketplace": "amazon_us",
      "current_price": 14.99,
      "recommended_price": 13.49,
      "delta": -1.50,
      "delta_pct": -10.0,
      "buy_box_win_probability": 0.74,
      "estimated_margin": 0.21,
      "confidence": 0.87,
      "reasoning": "3 new competitors entered at €12.99; lowering to €13.49 maintains Buy Box without matching floor",
      "status": "pending",
      "created_at": "2026-03-12T14:00:00.000Z"
    }
  ]
}

Apply Recommendation

POST /api/pricing/recommendations/:recommendationId/apply

Required scope: pricing:write

Applies a specific recommendation immediately.

Get Competitor Prices

GET /api/pricing/competitors?sku=SKU-001&marketplace=amazon_us

Returns the latest competitor prices for a SKU on a marketplace.

Error Codes

Code	HTTP Status	Description
`RULE_NOT_FOUND`	404	Pricing rule ID does not exist
`RULE_CONFLICT`	409	New rule conflicts with an existing rule at the same priority
`RECOMMENDATION_NOT_FOUND`	404	Recommendation ID does not exist
`RECOMMENDATION_ALREADY_APPLIED`	409	Recommendation has already been applied

On this page