Products

Products represent your catalog items. Use these endpoints to list, create, update, sync from Shopify, and request AI optimizations.

The product model

The product model contains core catalog data, readiness scoring, and references to optimizations.

Properties

  • Name
    id
    Type
    string
    Description
  • Name
    shopify_id
    Type
    integer
    Description
  • Name
    title
    Type
    string
    Description
  • Name
    handle
    Type
    string
    Description
  • Name
    status
    Type
    string
    Description
  • Name
    vendor
    Type
    string
    Description
  • Name
    product_type
    Type
    string
    Description
  • Name
    readiness_score
    Type
    integer
    Description
  • Name
    readiness_grade
    Type
    string
    Description
  • Name
    optimization_status
    Type
    string
    Description
  • Name
    pending_optimizations_count
    Type
    integer
    Description
  • Name
    primary_image_url
    Type
    string
    Description
  • Name
    last_synced_at
    Type
    string
    Description
  • Name
    created_at
    Type
    string
    Description
  • Name
    updated_at
    Type
    string
    Description
  • Name
    description
    Type
    string
    Description
  • Name
    meta_title
    Type
    string
    Description
  • Name
    meta_description
    Type
    string
    Description
  • Name
    og_title
    Type
    string
    Description
    AI-optimized Open Graph title for social media previews
  • Name
    og_description
    Type
    string
    Description
    AI-optimized Open Graph description for social media previews
  • Name
    tags
    Type
    string
    Description
  • Name
    options
    Type
    object[]
    Description
  • Name
    images
    Type
    image[]
    Description
  • Name
    price_min
    Type
    number
    Description
  • Name
    latest_optimization
    Type
    optimization_summary
    Description
  • Name
    score_history
    Type
    score_history_summary[]
    Description
GET /v1/products

List all products

Returns a paginated list of products for the authenticated account

Optional parameters

  • Name
    page
    Type
    integer
    Description
    Default 1.
  • Name
    per_page
    Type
    integer
    Description
    Default 25. Max 100.
  • Name
    status
    Type
    string
    Description
    One of active, draft, archived.
  • Name
    min_score
    Type
    integer
    Description
    Max 100.
  • Name
    max_score
    Type
    integer
    Description
    Max 100.
  • Name
    grade
    Type
    string
    Description
    One of excellent, good, fair, poor, critical.
  • Name
    needs_optimization
    Type
    boolean
    Description
  • Name
    q
    Type
    string
    Description
    Search by title

Request

GET /v1/products 
curl -G \
  https://beaconed.ai/api/v1/products \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "shopify_id": 7982561779890,
      "title": "Organic Cotton T-Shirt",
      "status": "active",
      "readiness_score": 85,
      "grade": "B",
      "optimized_at": "2026-03-15T14:30:00Z",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}
POST /v1/products

Create a product

Create a product from external data (non-Shopify). Use external_id for idempotency.

Optional attributes

  • Name
    title
    Type
    string
    Description
    Product title
  • Name
    description
    Type
    string
    Description
    Full product description (HTML supported)
  • Name
    handle
    Type
    string
    Description
    URL-safe product handle
  • Name
    status
    Type
    string
    Description
  • Name
    vendor
    Type
    string
    Description
    Brand or manufacturer name
  • Name
    product_type
    Type
    string
    Description
    Product category
  • Name
    meta_title
    Type
    string
    Description
    SEO meta title (shown in search results)
  • Name
    meta_description
    Type
    string
    Description
    SEO meta description (shown in search results)
  • Name
    og_title
    Type
    string
    Description
    Open Graph title for social media previews
  • Name
    og_description
    Type
    string
    Description
    Open Graph description for social media previews
  • Name
    tags
    Type
    string
    Description
    Comma-separated product tags
  • Name
    external_id
    Type
    string
    Description
    Your system's product ID. Used for idempotency on create.
  • Name
    images
    Type
    object[]
    Description

Request

POST /v1/products 
curl -X POST \
  https://beaconed.ai/api/v1/products \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"product": {"title": "New Product", "shopify_id": 123456}}'
GET /v1/products/{id}

Get a product

Returns detailed information about a specific product

Request

GET /v1/products/{id} 
curl https://beaconed.ai/api/v1/products/{id} \
  -H "Authorization: Bearer {token}"
PATCH /v1/products/{id}

Update a product

Update a product's fields. Only include fields you want to change.

Optional attributes

  • Name
    title
    Type
    string
    Description
    Product title
  • Name
    description
    Type
    string
    Description
    Full product description (HTML supported)
  • Name
    handle
    Type
    string
    Description
    URL-safe product handle
  • Name
    status
    Type
    string
    Description
  • Name
    vendor
    Type
    string
    Description
    Brand or manufacturer name
  • Name
    product_type
    Type
    string
    Description
    Product category
  • Name
    meta_title
    Type
    string
    Description
    SEO meta title (shown in search results)
  • Name
    meta_description
    Type
    string
    Description
    SEO meta description (shown in search results)
  • Name
    og_title
    Type
    string
    Description
    Open Graph title for social media previews
  • Name
    og_description
    Type
    string
    Description
    Open Graph description for social media previews
  • Name
    tags
    Type
    string
    Description
    Comma-separated product tags
  • Name
    external_id
    Type
    string
    Description
    Your system's product ID. Used for idempotency on create.
  • Name
    images
    Type
    object[]
    Description

Request

PATCH /v1/products/{id} 
curl -X PATCH \
  https://beaconed.ai/api/v1/products/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"product": {"tags": "organic,cotton,sustainable"}}'
POST /v1/products/{product_id}/sync

Sync a product

Triggers a sync of the product from Shopify

Request

POST /v1/products/{product_id}/sync 
curl -X POST \
  https://beaconed.ai/api/v1/products/{product_id}/sync \
  -H "Authorization: Bearer {token}"
POST /v1/products/{product_id}/optimization

Request optimization

Queue AI optimization for one or more fields on a product. Each field generates a separate Optimization record with suggested content. Poll GET /api/v1/optimizations?product_id={product_id}&status=pending to retrieve results.

Optional attributes

  • Name
    fields
    Type
    string[]
    Description
    Fields to optimize. Defaults to all fields if omitted.

Request

POST /v1/products/{product_id}/optimization 
curl -X POST \
  https://beaconed.ai/api/v1/products/{product_id}/optimization \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"fields": ["title", "description"]}'

Response

{
  "success": true,
  "data": {
    "id": "opt-uuid-here",
    "product_id": "a1b2c3d4-...",
    "fields": ["title", "description"],
    "status": "queued",
    "created_at": "2026-03-31T10:00:00Z"
  }
}